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
 199     CRM_Core_Invoke::rebuildMenuAndCaches(FALSE, FALSE);
 200     // sessionReset is FALSE because upgrade status/postUpgradeMessages are needed by the page. We reset later in doFinish().
 201
 202     return TRUE;
 203   }
 204
 205   /**
 206    * Remove a payment processor if not in use
 207    *
 208    * @param CRM_Queue_TaskContext $ctx
 209    * @param string $name
 210    * @return bool
 211    * @throws \CiviCRM_API3_Exception
 212    */
 213   public static function removePaymentProcessorType(CRM_Queue_TaskContext $ctx, $name) {
 214     $processors = civicrm_api3('PaymentProcessor', 'getcount', ['payment_processor_type_id' => $name]);
 215     if (empty($processors['result'])) {
 216       $result = civicrm_api3('PaymentProcessorType', 'get', [
 217         'name' => $name,
 218         'return' => 'id',
 219       ]);
 220       if (!empty($result['id'])) {
 221         civicrm_api3('PaymentProcessorType', 'delete', ['id' => $result['id']]);
 222       }
 223     }
 224     return TRUE;
 225   }
 226
 227   /**
 228    * @param string $table_name
 229    * @param string $constraint_name
 230    * @return bool
 231    */
 232   public static function checkFKExists($table_name, $constraint_name) {
 233     return CRM_Core_BAO_SchemaHandler::checkFKExists($table_name, $constraint_name);
 234   }
 235
 236   /**
 237    * Add a column to a table if it doesn't already exist
 238    *
 239    * @param CRM_Queue_TaskContext $ctx
 240    * @param string $table
 241    * @param string $column
 242    * @param string $properties
 243    * @param bool $localizable is this a field that should be localized
 244    * @param string|null $version CiviCRM version to use if rebuilding multilingual schema
 245    * @param bool $triggerRebuild should we trigger the rebuild of the multilingual schema
 246    *
 247    * @return bool
 248    */
 249   public static function addColumn($ctx, $table, $column, $properties, $localizable = FALSE, $version = NULL, $triggerRebuild = TRUE) {
 250     $locales = CRM_Core_I18n::getMultilingual();
 251     $queries = [];
 252     if (!CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, $column, FALSE)) {
 253       if ($locales) {
 254         if ($localizable) {
 255           foreach ($locales as $locale) {
 256             if (!CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, "{$column}_{$locale}", FALSE)) {
 257               $queries[] = "ALTER TABLE `$table` ADD COLUMN `{$column}_{$locale}` $properties";
 258             }
 259           }
 260         }
 261         else {
 262           $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
 263         }
 264       }
 265       else {
 266         $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
 267       }
 268       foreach ($queries as $query) {
 269         CRM_Core_DAO::executeQuery($query, [], TRUE, NULL, FALSE, FALSE);
 270       }
 271     }
 272     if ($locales && $triggerRebuild) {
 273       CRM_Core_I18n_Schema::rebuildMultilingualSchema($locales, $version, TRUE);
 274     }
 275     return TRUE;
 276   }
 277
 278   /**
 279    * Add the specified option group, gracefully if it already exists.
 280    *
 281    * @param CRM_Queue_TaskContext $ctx
 282    * @param array $params
 283    * @param array $options
 284    *
 285    * @return bool
 286    */
 287   public static function addOptionGroup(CRM_Queue_TaskContext $ctx, $params, $options): bool {
 288     $defaults = ['is_active' => 1];
 289     $optionDefaults = ['is_active' => 1];
 290     $optionDefaults['option_group_id'] = \CRM_Core_BAO_OptionGroup::ensureOptionGroupExists(array_merge($defaults, $params));
 291
 292     foreach ($options as $option) {
 293       \CRM_Core_BAO_OptionValue::ensureOptionValueExists(array_merge($optionDefaults, $option));
 294     }
 295     return TRUE;
 296   }
 297
 298   /**
 299    * Do any relevant message template updates.
 300    *
 301    * @param CRM_Queue_TaskContext $ctx
 302    * @param string $version
 303    */
 304   public static function updateMessageTemplates($ctx, $version) {
 305     $messageTemplateObject = new CRM_Upgrade_Incremental_MessageTemplates($version);
 306     $messageTemplateObject->updateTemplates();
 307   }
 308
 309   /**
 310    * Updated a message token within a template.
 311    *
 312    * @param CRM_Queue_TaskContext $ctx
 313    * @param string $workflowName
 314    * @param string $old
 315    * @param string $new
 316    * @param $version
 317    *
 318    * @return bool
 319    */
 320   public static function updateMessageToken($ctx, string $workflowName, string $old, string $new, $version):bool {
 321     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 322     if (!empty($workflowName)) {
 323       $messageObj->replaceTokenInTemplate($workflowName, $old, $new);
 324     }
 325     else {
 326       $messageObj->replaceTokenInMessageTemplates($old, $new);
 327     }
 328     return TRUE;
 329   }
 330
 331   /**
 332    * Updated a message token within a scheduled reminder.
 333    *
 334    * @param CRM_Queue_TaskContext $ctx
 335    * @param string $old
 336    * @param string $new
 337    * @param $version
 338    *
 339    * @return bool
 340    */
 341   public static function updateActionScheduleToken($ctx, string $old, string $new, $version):bool {
 342     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 343     $messageObj->replaceTokenInActionSchedule($old, $new);
 344     return TRUE;
 345   }
 346
 347   /**
 348    * Updated a message token within a label.
 349    *
 350    * @param CRM_Queue_TaskContext $ctx
 351    * @param string $old
 352    * @param string $new
 353    * @param $version
 354    *
 355    * @return bool
 356    */
 357   public static function updatePrintLabelToken($ctx, string $old, string $new, $version):bool {
 358     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 359     $messageObj->replaceTokenInPrintLabel($old, $new);
 360     return TRUE;
 361   }
 362
 363   /**
 364    * Updated a message token within greeting options.
 365    *
 366    * @param CRM_Queue_TaskContext $ctx
 367    * @param string $old
 368    * @param string $new
 369    * @param $version
 370    *
 371    * @return bool
 372    */
 373   public static function updateGreetingOptions($ctx, string $old, string $new, $version):bool {
 374     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 375     $messageObj->replaceTokenInGreetingOptions($old, $new);
 376     return TRUE;
 377   }
 378
 379   /**
 380    * Updated a currency in civicrm_currency and related configurations
 381    *
 382    * @param CRM_Queue_TaskContext $ctx
 383    * @param string $old_name
 384    * @param string $new_name
 385    *
 386    * @return bool
 387    */
 388   public static function updateCurrencyName($ctx, string $old_name, string $new_name): bool {
 389     CRM_Core_DAO::executeQuery('UPDATE civicrm_currency SET name = %1 WHERE name = %2', [
 390       1 => [$new_name, 'String'],
 391       2 => [$old_name, 'String'],
 392     ]);
 393
 394     $oid = CRM_Core_DAO::singleValueQuery("SELECT id FROM civicrm_option_group WHERE name = 'currencies_enabled'");
 395     if ($oid) {
 396       CRM_Core_DAO::executeQuery('UPDATE civicrm_option_value SET value = %1 WHERE value = %2 AND option_group_id = %3', [
 397         1 => [$new_name, 'String'],
 398         2 => [$old_name, 'String'],
 399         3 => [$oid, 'String'],
 400       ]);
 401     }
 402
 403     CRM_Core_DAO::executeQuery('UPDATE civicrm_participant SET fee_currency = %1 WHERE fee_currency = %2', [
 404       1 => [$new_name, 'String'],
 405       2 => [$old_name, 'String'],
 406     ]);
 407
 408     $tables = [
 409       'civicrm_contribution',
 410       'civicrm_contribution_page',
 411       'civicrm_contribution_recur',
 412       'civicrm_contribution_soft',
 413       'civicrm_event',
 414       'civicrm_financial_item',
 415       'civicrm_financial_trxn',
 416       'civicrm_grant',
 417       'civicrm_pcp',
 418       'civicrm_pledge_payment',
 419       'civicrm_pledge',
 420       'civicrm_product',
 421     ];
 422
 423     foreach ($tables as $table) {
 424       CRM_Core_DAO::executeQuery('UPDATE %3 SET currency = %1 WHERE currency = %2', [
 425         1 => [$new_name, 'String'],
 426         2 => [$old_name, 'String'],
 427         3 => [$table, 'MysqlColumnNameOrAlias'],
 428       ]);
 429     }
 430
 431     return TRUE;
 432   }
 433
 434   /**
 435    * Re-save any valid values from contribute settings into the normal setting
 436    * format.
 437    *
 438    * We render the array of contribution_invoice_settings and any that have
 439    * metadata defined we add to the correct key. This is safe to run even if no
 440    * settings are to be converted, per the test in
 441    * testConvertUpgradeContributeSettings.
 442    *
 443    * @param $ctx
 444    *
 445    * @return bool
 446    */
 447   public static function updateContributeSettings($ctx) {
 448     // Use a direct query as api now does some handling on this.
 449     $settings = CRM_Core_DAO::executeQuery("SELECT value, domain_id FROM civicrm_setting WHERE name = 'contribution_invoice_settings'");
 450
 451     while ($settings->fetch()) {
 452       $contributionSettings = (array) CRM_Utils_String::unserialize($settings->value);
 453       foreach (array_merge(SettingsBag::getContributionInvoiceSettingKeys(), ['deferred_revenue_enabled' => 'deferred_revenue_enabled']) as $possibleKeyName => $settingName) {
 454         if (!empty($contributionSettings[$possibleKeyName]) && empty(Civi::settings($settings->domain_id)->getExplicit($settingName))) {
 455           Civi::settings($settings->domain_id)->set($settingName, $contributionSettings[$possibleKeyName]);
 456         }
 457       }
 458     }
 459     return TRUE;
 460   }
 461
 462   /**
 463    * Do any relevant smart group updates.
 464    *
 465    * @param CRM_Queue_TaskContext $ctx
 466    * @param array $actions
 467    *
 468    * @return bool
 469    */
 470   public static function updateSmartGroups($ctx, $actions) {
 471     $groupUpdateObject = new CRM_Upgrade_Incremental_SmartGroups();
 472     $groupUpdateObject->updateGroups($actions);
 473     return TRUE;
 474   }
 475
 476   /**
 477    * Drop a column from a table if it exist.
 478    *
 479    * @param CRM_Queue_TaskContext $ctx
 480    * @param string $table
 481    * @param string $column
 482    * @return bool
 483    */
 484   public static function dropColumn($ctx, $table, $column) {
 485     if (CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, $column)) {
 486       CRM_Core_DAO::executeQuery("ALTER TABLE `$table` DROP COLUMN `$column`",
 487         [], TRUE, NULL, FALSE, FALSE);
 488     }
 489     return TRUE;
 490   }
 491
 492   /**
 493    * Add a index to a table column.
 494    *
 495    * @param CRM_Queue_TaskContext $ctx
 496    * @param string $table
 497    * @param string|array $columns
 498    * @param string $prefix
 499    * @return bool
 500    */
 501   public static function addIndex($ctx, $table, $columns, $prefix = 'index') {
 502     $tables = [$table => (array) $columns];
 503     CRM_Core_BAO_SchemaHandler::createIndexes($tables, $prefix);
 504
 505     return TRUE;
 506   }
 507
 508   /**
 509    * Drop a index from a table if it exist.
 510    *
 511    * @param CRM_Queue_TaskContext $ctx
 512    * @param string $table
 513    * @param string $indexName
 514    * @return bool
 515    */
 516   public static function dropIndex($ctx, $table, $indexName) {
 517     CRM_Core_BAO_SchemaHandler::dropIndexIfExists($table, $indexName);
 518
 519     return TRUE;
 520   }
 521
 522   /**
 523    * Drop a table... but only if it's empty.
 524    *
 525    * @param CRM_Queue_TaskContext $ctx
 526    * @param string $table
 527    * @return bool
 528    */
 529   public static function dropTableIfEmpty($ctx, $table) {
 530     if (CRM_Core_DAO::checkTableExists($table)) {
 531       if (!CRM_Core_DAO::checkTableHasData($table)) {
 532         CRM_Core_BAO_SchemaHandler::dropTable($table);
 533       }
 534       else {
 535         $ctx->log->warning("dropTableIfEmpty($table): Found data. Preserved table.");
 536       }
 537     }
 538
 539     return TRUE;
 540   }
 541
 542   /**
 543    * Rebuild Multilingual Schema.
 544    * @param CRM_Queue_TaskContext $ctx
 545    * @param string|null $version CiviCRM version to use if rebuilding multilingual schema
 546    *
 547    * @return bool
 548    */
 549   public static function rebuildMultilingalSchema($ctx, $version = NULL) {
 550     $locales = CRM_Core_I18n::getMultilingual();
 551     if ($locales) {
 552       CRM_Core_I18n_Schema::rebuildMultilingualSchema($locales, $version);
 553     }
 554     return TRUE;
 555   }
 556
 557 }