CRM/Upgrade/Incremental/Base.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 use Civi\Core\SettingsBag;
  13
  14 /**
  15  * Base class for incremental upgrades
  16  */
  17 class CRM_Upgrade_Incremental_Base {
  18   const BATCH_SIZE = 5000;
  19
  20   /**
  21    * @var string|null
  22    */
  23   protected $majorMinor;
  24
  25   /**
  26    * Get the major and minor version for this class (based on English-style class name).
  27    *
  28    * @return string
  29    *   Ex: '5.34' or '4.7'
  30    */
  31   public function getMajorMinor() {
  32     if (!$this->majorMinor) {
  33       $className = explode('_', static::CLASS);
  34       $numbers = preg_split("/([[:upper:]][[:lower:]]+)/", array_pop($className), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
  35       $major = CRM_Utils_EnglishNumber::toInt(array_shift($numbers));
  36       $minor = CRM_Utils_EnglishNumber::toInt(implode('', $numbers));
  37       $this->majorMinor = $major . '.' . $minor;
  38     }
  39     return $this->majorMinor;
  40   }
  41
  42   /**
  43    * Get a list of revisions (PATCH releases) related to this class.
  44    *
  45    * @return array
  46    *   Ex: ['4.5.6', '4.5.7']
  47    * @throws \ReflectionException
  48    */
  49   public function getRevisionSequence() {
  50     $revList = [];
  51
  52     $sqlGlob = implode(DIRECTORY_SEPARATOR, [dirname(__FILE__), 'sql', $this->getMajorMinor() . '.*.mysql.tpl']);
  53     $sqlFiles = glob($sqlGlob);;
  54     foreach ($sqlFiles as $file) {
  55       $revList[] = str_replace('.mysql.tpl', '', basename($file));
  56     }
  57
  58     $c = new ReflectionClass(static::class);
  59     foreach ($c->getMethods() as $method) {
  60       /** @var \ReflectionMethod $method */
  61       if (preg_match(';^upgrade_([0-9_alphabeta]+)$;', $method->getName(), $m)) {
  62         $revList[] = str_replace('_', '.', $m[1]);
  63       }
  64     }
  65
  66     $revList = array_unique($revList);
  67     usort($revList, 'version_compare');
  68     return $revList;
  69   }
  70
  71   /**
  72    * Compute any messages which should be displayed before upgrade.
  73    *
  74    * Downstream classes should implement this method to generate their messages.
  75    *
  76    * This method will be invoked multiple times. Implementations MUST consult the `$rev`
  77    * before deciding what messages to add. See the examples linked below.
  78    *
  79    * @see \CRM_Upgrade_Incremental_php_FourSeven::setPreUpgradeMessage()
  80    * @see \CRM_Upgrade_Incremental_php_FiveTwenty::setPreUpgradeMessage()
  81    *
  82    * @param string $preUpgradeMessage
  83    *   Accumulated list of messages. Alterable.
  84    * @param string $rev
  85    *   The incremental version number. (Called repeatedly, once for each increment.)
  86    *
  87    *   Ex: Suppose the system upgrades from 5.7.3 to 5.10.0. The method FiveEight::setPreUpgradeMessage()
  88    *   will be called for each increment of '5.8.*' ('5.8.alpha1' => '5.8.beta1' =>  '5.8.0').
  89    * @param null $currentVer
  90    *   This is the penultimate version targeted by the upgrader.
  91    *   Equivalent to CRM_Utils_System::version().
  92    */
  93   public function setPreUpgradeMessage(&$preUpgradeMessage, $rev, $currentVer = NULL) {
  94   }
  95
  96   /**
  97    * Compute any messages which should be displayed after upgrade.
  98    *
  99    * Downstream classes should implement this method to generate their messages.
 100    *
 101    * This method will be invoked multiple times. Implementations MUST consult the `$rev`
 102    * before deciding what messages to add. See the examples linked below.
 103    *
 104    * @see \CRM_Upgrade_Incremental_php_FourSeven::setPostUpgradeMessage()
 105    * @see \CRM_Upgrade_Incremental_php_FiveTwentyOne::setPostUpgradeMessage()
 106    *
 107    * @param string $postUpgradeMessage
 108    *   Accumulated list of messages. Alterable.
 109    * @param string $rev
 110    *   The incremental version number. (Called repeatedly, once for each increment.)
 111    *
 112    *   Ex: Suppose the system upgrades from 5.7.3 to 5.10.0. The method FiveEight::setPreUpgradeMessage()
 113    *   will be called for each increment of '5.8.*' ('5.8.alpha1' => '5.8.beta1' =>  '5.8.0').
 114    */
 115   public function setPostUpgradeMessage(&$postUpgradeMessage, $rev) {
 116   }
 117
 118   /**
 119    * (Queue Task Callback)
 120    *
 121    * @param \CRM_Queue_TaskContext $ctx
 122    * @param string $rev
 123    *
 124    * @return bool
 125    */
 126   public static function runSql(CRM_Queue_TaskContext $ctx, $rev) {
 127     $upgrade = new CRM_Upgrade_Form();
 128     $upgrade->processSQL($rev);
 129
 130     return TRUE;
 131   }
 132
 133   /**
 134    * Syntactic sugar for adding a task.
 135    *
 136    * Task is (a) in this class and (b) has a high priority.
 137    *
 138    * After passing the $funcName, you can also pass parameters that will go to
 139    * the function. Note that all params must be serializable.
 140    *
 141    * @param string $title
 142    * @param string $funcName
 143    */
 144   protected function addTask($title, $funcName) {
 145     $queue = CRM_Queue_Service::singleton()->load([
 146       'type' => 'Sql',
 147       'name' => CRM_Upgrade_Form::QUEUE_NAME,
 148     ]);
 149
 150     $args = func_get_args();
 151     $title = array_shift($args);
 152     $funcName = array_shift($args);
 153     $task = new CRM_Queue_Task(
 154       [get_class($this), $funcName],
 155       $args,
 156       $title
 157     );
 158     $queue->createItem($task, ['weight' => -1]);
 159   }
 160
 161   /**
 162    * Add a task to activate an extension. This task will run post-upgrade (after all
 163    * changes to core DB are settled).
 164    *
 165    * @param string $title
 166    * @param string[] $keys
 167    *   List of extensions to enable.
 168    */
 169   protected function addExtensionTask(string $title, array $keys): void {
 170     Civi::queue(CRM_Upgrade_Form::QUEUE_NAME)->createItem(
 171       new CRM_Queue_Task([static::CLASS, 'enableExtension'], [$keys], $title),
 172       ['weight' => 2000]
 173     );
 174   }
 175
 176   /**
 177    * @param \CRM_Queue_TaskContext $ctx
 178    * @param string[] $keys
 179    *   List of extensions to enable.
 180    * @return bool
 181    */
 182   public static function enableExtension(CRM_Queue_TaskContext $ctx, array $keys): bool {
 183     // The `enableExtension` has a very high value of `weight`, so this runs after all
 184     // core DB schema updates have been resolved. We can use high-level services.
 185
 186     Civi::dispatcher()->setDispatchPolicy(\CRM_Upgrade_DispatchPolicy::get('upgrade.finish'));
 187     $restore = \CRM_Utils_AutoClean::with(function() {
 188       Civi::dispatcher()->setDispatchPolicy(\CRM_Upgrade_DispatchPolicy::get('upgrade.main'));
 189     });
 190
 191     $manager = CRM_Extension_System::singleton()->getManager();
 192     $manager->enable($manager->findInstallRequirements($keys));
 193
 194     // Hrm, `enable()` normally does these things... but not during upgrade...
 195     // Note: A good test-scenario is to install 5.45; enable logging and CiviGrant; disable searchkit+afform; then upgrade to 5.47.
 196     $schema = new CRM_Logging_Schema();
 197     $schema->fixSchemaDifferences();
 198     CRM_Core_Invoke::rebuildMenuAndCaches(FALSE, TRUE);
 199
 200     return TRUE;
 201   }
 202
 203   /**
 204    * Remove a payment processor if not in use
 205    *
 206    * @param CRM_Queue_TaskContext $ctx
 207    * @param string $name
 208    * @return bool
 209    * @throws \CiviCRM_API3_Exception
 210    */
 211   public static function removePaymentProcessorType(CRM_Queue_TaskContext $ctx, $name) {
 212     $processors = civicrm_api3('PaymentProcessor', 'getcount', ['payment_processor_type_id' => $name]);
 213     if (empty($processors['result'])) {
 214       $result = civicrm_api3('PaymentProcessorType', 'get', [
 215         'name' => $name,
 216         'return' => 'id',
 217       ]);
 218       if (!empty($result['id'])) {
 219         civicrm_api3('PaymentProcessorType', 'delete', ['id' => $result['id']]);
 220       }
 221     }
 222     return TRUE;
 223   }
 224
 225   /**
 226    * @param string $table_name
 227    * @param string $constraint_name
 228    * @return bool
 229    */
 230   public static function checkFKExists($table_name, $constraint_name) {
 231     return CRM_Core_BAO_SchemaHandler::checkFKExists($table_name, $constraint_name);
 232   }
 233
 234   /**
 235    * Add a column to a table if it doesn't already exist
 236    *
 237    * @param CRM_Queue_TaskContext $ctx
 238    * @param string $table
 239    * @param string $column
 240    * @param string $properties
 241    * @param bool $localizable is this a field that should be localized
 242    * @param string|null $version CiviCRM version to use if rebuilding multilingual schema
 243    * @param bool $triggerRebuild should we trigger the rebuild of the multilingual schema
 244    *
 245    * @return bool
 246    */
 247   public static function addColumn($ctx, $table, $column, $properties, $localizable = FALSE, $version = NULL, $triggerRebuild = TRUE) {
 248     $locales = CRM_Core_I18n::getMultilingual();
 249     $queries = [];
 250     if (!CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, $column, FALSE)) {
 251       if ($locales) {
 252         if ($localizable) {
 253           foreach ($locales as $locale) {
 254             if (!CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, "{$column}_{$locale}", FALSE)) {
 255               $queries[] = "ALTER TABLE `$table` ADD COLUMN `{$column}_{$locale}` $properties";
 256             }
 257           }
 258         }
 259         else {
 260           $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
 261         }
 262       }
 263       else {
 264         $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
 265       }
 266       foreach ($queries as $query) {
 267         CRM_Core_DAO::executeQuery($query, [], TRUE, NULL, FALSE, FALSE);
 268       }
 269     }
 270     if ($locales && $triggerRebuild) {
 271       CRM_Core_I18n_Schema::rebuildMultilingualSchema($locales, $version, TRUE);
 272     }
 273     return TRUE;
 274   }
 275
 276   /**
 277    * Add the specified option group, gracefully if it already exists.
 278    *
 279    * @param CRM_Queue_TaskContext $ctx
 280    * @param array $params
 281    * @param array $options
 282    *
 283    * @return bool
 284    */
 285   public static function addOptionGroup(CRM_Queue_TaskContext $ctx, $params, $options): bool {
 286     $defaults = ['is_active' => 1];
 287     $optionDefaults = ['is_active' => 1];
 288     $optionDefaults['option_group_id'] = \CRM_Core_BAO_OptionGroup::ensureOptionGroupExists(array_merge($defaults, $params));
 289
 290     foreach ($options as $option) {
 291       \CRM_Core_BAO_OptionValue::ensureOptionValueExists(array_merge($optionDefaults, $option));
 292     }
 293     return TRUE;
 294   }
 295
 296   /**
 297    * Do any relevant message template updates.
 298    *
 299    * @param CRM_Queue_TaskContext $ctx
 300    * @param string $version
 301    */
 302   public static function updateMessageTemplates($ctx, $version) {
 303     $messageTemplateObject = new CRM_Upgrade_Incremental_MessageTemplates($version);
 304     $messageTemplateObject->updateTemplates();
 305   }
 306
 307   /**
 308    * Updated a message token within a template.
 309    *
 310    * @param CRM_Queue_TaskContext $ctx
 311    * @param string $workflowName
 312    * @param string $old
 313    * @param string $new
 314    * @param $version
 315    *
 316    * @return bool
 317    */
 318   public static function updateMessageToken($ctx, string $workflowName, string $old, string $new, $version):bool {
 319     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 320     if (!empty($workflowName)) {
 321       $messageObj->replaceTokenInTemplate($workflowName, $old, $new);
 322     }
 323     else {
 324       $messageObj->replaceTokenInMessageTemplates($old, $new);
 325     }
 326     return TRUE;
 327   }
 328
 329   /**
 330    * Updated a message token within a scheduled reminder.
 331    *
 332    * @param CRM_Queue_TaskContext $ctx
 333    * @param string $old
 334    * @param string $new
 335    * @param $version
 336    *
 337    * @return bool
 338    */
 339   public static function updateActionScheduleToken($ctx, string $old, string $new, $version):bool {
 340     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 341     $messageObj->replaceTokenInActionSchedule($old, $new);
 342     return TRUE;
 343   }
 344
 345   /**
 346    * Updated a message token within a label.
 347    *
 348    * @param CRM_Queue_TaskContext $ctx
 349    * @param string $old
 350    * @param string $new
 351    * @param $version
 352    *
 353    * @return bool
 354    */
 355   public static function updatePrintLabelToken($ctx, string $old, string $new, $version):bool {
 356     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 357     $messageObj->replaceTokenInPrintLabel($old, $new);
 358     return TRUE;
 359   }
 360
 361   /**
 362    * Updated a message token within greeting options.
 363    *
 364    * @param CRM_Queue_TaskContext $ctx
 365    * @param string $old
 366    * @param string $new
 367    * @param $version
 368    *
 369    * @return bool
 370    */
 371   public static function updateGreetingOptions($ctx, string $old, string $new, $version):bool {
 372     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 373     $messageObj->replaceTokenInGreetingOptions($old, $new);
 374     return TRUE;
 375   }
 376
 377   /**
 378    * Updated a currency in civicrm_currency and related configurations
 379    *
 380    * @param CRM_Queue_TaskContext $ctx
 381    * @param string $old_name
 382    * @param string $new_name
 383    *
 384    * @return bool
 385    */
 386   public static function updateCurrencyName($ctx, string $old_name, string $new_name): bool {
 387     CRM_Core_DAO::executeQuery('UPDATE civicrm_currency SET name = %1 WHERE name = %2', [
 388       1 => [$new_name, 'String'],
 389       2 => [$old_name, 'String'],
 390     ]);
 391
 392     $oid = CRM_Core_DAO::singleValueQuery("SELECT id FROM civicrm_option_group WHERE name = 'currencies_enabled'");
 393     if ($oid) {
 394       CRM_Core_DAO::executeQuery('UPDATE civicrm_option_value SET value = %1 WHERE value = %2 AND option_group_id = %3', [
 395         1 => [$new_name, 'String'],
 396         2 => [$old_name, 'String'],
 397         3 => [$oid, 'String'],
 398       ]);
 399     }
 400
 401     CRM_Core_DAO::executeQuery('UPDATE civicrm_participant SET fee_currency = %1 WHERE fee_currency = %2', [
 402       1 => [$new_name, 'String'],
 403       2 => [$old_name, 'String'],
 404     ]);
 405
 406     $tables = [
 407       'civicrm_contribution',
 408       'civicrm_contribution_page',
 409       'civicrm_contribution_recur',
 410       'civicrm_contribution_soft',
 411       'civicrm_event',
 412       'civicrm_financial_item',
 413       'civicrm_financial_trxn',
 414       'civicrm_grant',
 415       'civicrm_pcp',
 416       'civicrm_pledge_payment',
 417       'civicrm_pledge',
 418       'civicrm_product',
 419     ];
 420
 421     foreach ($tables as $table) {
 422       CRM_Core_DAO::executeQuery('UPDATE %3 SET currency = %1 WHERE currency = %2', [
 423         1 => [$new_name, 'String'],
 424         2 => [$old_name, 'String'],
 425         3 => [$table, 'MysqlColumnNameOrAlias'],
 426       ]);
 427     }
 428
 429     return TRUE;
 430   }
 431
 432   /**
 433    * Re-save any valid values from contribute settings into the normal setting
 434    * format.
 435    *
 436    * We render the array of contribution_invoice_settings and any that have
 437    * metadata defined we add to the correct key. This is safe to run even if no
 438    * settings are to be converted, per the test in
 439    * testConvertUpgradeContributeSettings.
 440    *
 441    * @param $ctx
 442    *
 443    * @return bool
 444    */
 445   public static function updateContributeSettings($ctx) {
 446     // Use a direct query as api now does some handling on this.
 447     $settings = CRM_Core_DAO::executeQuery("SELECT value, domain_id FROM civicrm_setting WHERE name = 'contribution_invoice_settings'");
 448
 449     while ($settings->fetch()) {
 450       $contributionSettings = (array) CRM_Utils_String::unserialize($settings->value);
 451       foreach (array_merge(SettingsBag::getContributionInvoiceSettingKeys(), ['deferred_revenue_enabled' => 'deferred_revenue_enabled']) as $possibleKeyName => $settingName) {
 452         if (!empty($contributionSettings[$possibleKeyName]) && empty(Civi::settings($settings->domain_id)->getExplicit($settingName))) {
 453           Civi::settings($settings->domain_id)->set($settingName, $contributionSettings[$possibleKeyName]);
 454         }
 455       }
 456     }
 457     return TRUE;
 458   }
 459
 460   /**
 461    * Do any relevant smart group updates.
 462    *
 463    * @param CRM_Queue_TaskContext $ctx
 464    * @param array $actions
 465    *
 466    * @return bool
 467    */
 468   public static function updateSmartGroups($ctx, $actions) {
 469     $groupUpdateObject = new CRM_Upgrade_Incremental_SmartGroups();
 470     $groupUpdateObject->updateGroups($actions);
 471     return TRUE;
 472   }
 473
 474   /**
 475    * Drop a column from a table if it exist.
 476    *
 477    * @param CRM_Queue_TaskContext $ctx
 478    * @param string $table
 479    * @param string $column
 480    * @return bool
 481    */
 482   public static function dropColumn($ctx, $table, $column) {
 483     if (CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, $column)) {
 484       CRM_Core_DAO::executeQuery("ALTER TABLE `$table` DROP COLUMN `$column`",
 485         [], TRUE, NULL, FALSE, FALSE);
 486     }
 487     return TRUE;
 488   }
 489
 490   /**
 491    * Add a index to a table column.
 492    *
 493    * @param CRM_Queue_TaskContext $ctx
 494    * @param string $table
 495    * @param string|array $columns
 496    * @param string $prefix
 497    * @return bool
 498    */
 499   public static function addIndex($ctx, $table, $columns, $prefix = 'index') {
 500     $tables = [$table => (array) $columns];
 501     CRM_Core_BAO_SchemaHandler::createIndexes($tables, $prefix);
 502
 503     return TRUE;
 504   }
 505
 506   /**
 507    * Drop a index from a table if it exist.
 508    *
 509    * @param CRM_Queue_TaskContext $ctx
 510    * @param string $table
 511    * @param string $indexName
 512    * @return bool
 513    */
 514   public static function dropIndex($ctx, $table, $indexName) {
 515     CRM_Core_BAO_SchemaHandler::dropIndexIfExists($table, $indexName);
 516
 517     return TRUE;
 518   }
 519
 520   /**
 521    * Drop a table... but only if it's empty.
 522    *
 523    * @param CRM_Queue_TaskContext $ctx
 524    * @param string $table
 525    * @return bool
 526    */
 527   public static function dropTableIfEmpty($ctx, $table) {
 528     if (CRM_Core_DAO::checkTableExists($table)) {
 529       if (!CRM_Core_DAO::checkTableHasData($table)) {
 530         CRM_Core_BAO_SchemaHandler::dropTable($table);
 531       }
 532       else {
 533         $ctx->log->warning("dropTableIfEmpty($table): Found data. Preserved table.");
 534       }
 535     }
 536
 537     return TRUE;
 538   }
 539
 540   /**
 541    * Rebuild Multilingual Schema.
 542    * @param CRM_Queue_TaskContext $ctx
 543    * @param string|null $version CiviCRM version to use if rebuilding multilingual schema
 544    *
 545    * @return bool
 546    */
 547   public static function rebuildMultilingalSchema($ctx, $version = NULL) {
 548     $locales = CRM_Core_I18n::getMultilingual();
 549     if ($locales) {
 550       CRM_Core_I18n_Schema::rebuildMultilingualSchema($locales, $version);
 551     }
 552     return TRUE;
 553   }
 554
 555 }