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 store a snapshot of some data (if upgrade-snapshots are supported).
 163    *
 164    * If there is a large amount of data, this may actually add multiple tasks.
 165    *
 166    * Ex :$this->addSnapshotTask('event_dates', CRM_Utils_SQL_Select::from('civicrm_event')
 167    *      ->select('id, start_date, end_date'));
 168    *
 169    * @param string $name
 170    *   Logical name for the snapshot. This will become part of the table.
 171    * @param \CRM_Utils_SQL_Select $select
 172    * @throws \CRM_Core_Exception
 173    */
 174   protected function addSnapshotTask(string $name, CRM_Utils_SQL_Select $select): void {
 175     CRM_Upgrade_Snapshot::createTableName('civicrm', $this->getMajorMinor(), $name);
 176     // ^^ To simplify QA -- we should always throw an exception for bad snapshot names, even if the local policy doesn't use snapshots.
 177
 178     if (!empty(CRM_Upgrade_Snapshot::getActivationIssues())) {
 179       return;
 180     }
 181
 182     $queue = CRM_Queue_Service::singleton()->load([
 183       'type' => 'Sql',
 184       'name' => CRM_Upgrade_Form::QUEUE_NAME,
 185     ]);
 186     foreach (CRM_Upgrade_Snapshot::createTasks('civicrm', $this->getMajorMinor(), $name, $select) as $task) {
 187       $queue->createItem($task, ['weight' => -1]);
 188     }
 189   }
 190
 191   /**
 192    * Add a task to activate an extension. This task will run post-upgrade (after all
 193    * changes to core DB are settled).
 194    *
 195    * @param string $title
 196    * @param string[] $keys
 197    *   List of extensions to enable.
 198    */
 199   protected function addExtensionTask(string $title, array $keys): void {
 200     Civi::queue(CRM_Upgrade_Form::QUEUE_NAME)->createItem(
 201       new CRM_Queue_Task([static::CLASS, 'enableExtension'], [$keys], $title),
 202       ['weight' => 2000]
 203     );
 204   }
 205
 206   /**
 207    * @param \CRM_Queue_TaskContext $ctx
 208    * @param string[] $keys
 209    *   List of extensions to enable.
 210    * @return bool
 211    */
 212   public static function enableExtension(CRM_Queue_TaskContext $ctx, array $keys): bool {
 213     // The `enableExtension` has a very high value of `weight`, so this runs after all
 214     // core DB schema updates have been resolved. We can use high-level services.
 215
 216     Civi::dispatcher()->setDispatchPolicy(\CRM_Upgrade_DispatchPolicy::get('upgrade.finish'));
 217     $restore = \CRM_Utils_AutoClean::with(function() {
 218       Civi::dispatcher()->setDispatchPolicy(\CRM_Upgrade_DispatchPolicy::get('upgrade.main'));
 219     });
 220
 221     $manager = CRM_Extension_System::singleton()->getManager();
 222     $manager->enable($manager->findInstallRequirements($keys));
 223
 224     // Hrm, `enable()` normally does these things... but not during upgrade...
 225     // Note: A good test-scenario is to install 5.45; enable logging and CiviGrant; disable searchkit+afform; then upgrade to 5.47.
 226     $schema = new CRM_Logging_Schema();
 227     $schema->fixSchemaDifferences();
 228
 229     CRM_Core_Invoke::rebuildMenuAndCaches(FALSE, FALSE);
 230     // sessionReset is FALSE because upgrade status/postUpgradeMessages are needed by the page. We reset later in doFinish().
 231
 232     return TRUE;
 233   }
 234
 235   /**
 236    * Remove a payment processor if not in use
 237    *
 238    * @param CRM_Queue_TaskContext $ctx
 239    * @param string $name
 240    * @return bool
 241    * @throws \CiviCRM_API3_Exception
 242    */
 243   public static function removePaymentProcessorType(CRM_Queue_TaskContext $ctx, $name) {
 244     $processors = civicrm_api3('PaymentProcessor', 'getcount', ['payment_processor_type_id' => $name]);
 245     if (empty($processors['result'])) {
 246       $result = civicrm_api3('PaymentProcessorType', 'get', [
 247         'name' => $name,
 248         'return' => 'id',
 249       ]);
 250       if (!empty($result['id'])) {
 251         civicrm_api3('PaymentProcessorType', 'delete', ['id' => $result['id']]);
 252       }
 253     }
 254     return TRUE;
 255   }
 256
 257   /**
 258    * @param string $table_name
 259    * @param string $constraint_name
 260    * @return bool
 261    */
 262   public static function checkFKExists($table_name, $constraint_name) {
 263     return CRM_Core_BAO_SchemaHandler::checkFKExists($table_name, $constraint_name);
 264   }
 265
 266   /**
 267    * Add a column to a table if it doesn't already exist
 268    *
 269    * @param CRM_Queue_TaskContext $ctx
 270    * @param string $table
 271    * @param string $column
 272    * @param string $properties
 273    * @param bool $localizable is this a field that should be localized
 274    * @param string|null $version CiviCRM version to use if rebuilding multilingual schema
 275    * @param bool $triggerRebuild should we trigger the rebuild of the multilingual schema
 276    *
 277    * @return bool
 278    */
 279   public static function addColumn($ctx, $table, $column, $properties, $localizable = FALSE, $version = NULL, $triggerRebuild = TRUE) {
 280     $locales = CRM_Core_I18n::getMultilingual();
 281     $queries = [];
 282     if (!CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, $column, FALSE)) {
 283       if ($locales) {
 284         if ($localizable) {
 285           foreach ($locales as $locale) {
 286             if (!CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, "{$column}_{$locale}", FALSE)) {
 287               $queries[] = "ALTER TABLE `$table` ADD COLUMN `{$column}_{$locale}` $properties";
 288             }
 289           }
 290         }
 291         else {
 292           $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
 293         }
 294       }
 295       else {
 296         $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
 297       }
 298       foreach ($queries as $query) {
 299         CRM_Core_DAO::executeQuery($query, [], TRUE, NULL, FALSE, FALSE);
 300       }
 301     }
 302     if ($locales && $triggerRebuild) {
 303       CRM_Core_I18n_Schema::rebuildMultilingualSchema($locales, $version, TRUE);
 304     }
 305     return TRUE;
 306   }
 307
 308   /**
 309    * Add the specified option group, gracefully if it already exists.
 310    *
 311    * @param CRM_Queue_TaskContext $ctx
 312    * @param array $params
 313    * @param array $options
 314    *
 315    * @return bool
 316    */
 317   public static function addOptionGroup(CRM_Queue_TaskContext $ctx, $params, $options): bool {
 318     $defaults = ['is_active' => 1];
 319     $optionDefaults = ['is_active' => 1];
 320     $optionDefaults['option_group_id'] = \CRM_Core_BAO_OptionGroup::ensureOptionGroupExists(array_merge($defaults, $params));
 321
 322     foreach ($options as $option) {
 323       \CRM_Core_BAO_OptionValue::ensureOptionValueExists(array_merge($optionDefaults, $option));
 324     }
 325     return TRUE;
 326   }
 327
 328   /**
 329    * Do any relevant message template updates.
 330    *
 331    * @param CRM_Queue_TaskContext $ctx
 332    * @param string $version
 333    */
 334   public static function updateMessageTemplates($ctx, $version) {
 335     $messageTemplateObject = new CRM_Upgrade_Incremental_MessageTemplates($version);
 336     $messageTemplateObject->updateTemplates();
 337   }
 338
 339   /**
 340    * Updated a message token within a template.
 341    *
 342    * @param CRM_Queue_TaskContext $ctx
 343    * @param string $workflowName
 344    * @param string $old
 345    * @param string $new
 346    * @param $version
 347    *
 348    * @return bool
 349    */
 350   public static function updateMessageToken($ctx, string $workflowName, string $old, string $new, $version):bool {
 351     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 352     if (!empty($workflowName)) {
 353       $messageObj->replaceTokenInTemplate($workflowName, $old, $new);
 354     }
 355     else {
 356       $messageObj->replaceTokenInMessageTemplates($old, $new);
 357     }
 358     return TRUE;
 359   }
 360
 361   /**
 362    * Updated a message token within a scheduled reminder.
 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 updateActionScheduleToken($ctx, string $old, string $new, $version):bool {
 372     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 373     $messageObj->replaceTokenInActionSchedule($old, $new);
 374     return TRUE;
 375   }
 376
 377   /**
 378    * Updated a message token within a label.
 379    *
 380    * @param CRM_Queue_TaskContext $ctx
 381    * @param string $old
 382    * @param string $new
 383    * @param $version
 384    *
 385    * @return bool
 386    */
 387   public static function updatePrintLabelToken($ctx, string $old, string $new, $version):bool {
 388     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 389     $messageObj->replaceTokenInPrintLabel($old, $new);
 390     return TRUE;
 391   }
 392
 393   /**
 394    * Updated a message token within greeting options.
 395    *
 396    * @param CRM_Queue_TaskContext $ctx
 397    * @param string $old
 398    * @param string $new
 399    * @param $version
 400    *
 401    * @return bool
 402    */
 403   public static function updateGreetingOptions($ctx, string $old, string $new, $version):bool {
 404     $messageObj = new CRM_Upgrade_Incremental_MessageTemplates($version);
 405     $messageObj->replaceTokenInGreetingOptions($old, $new);
 406     return TRUE;
 407   }
 408
 409   /**
 410    * Updated a currency in civicrm_currency and related configurations
 411    *
 412    * @param CRM_Queue_TaskContext $ctx
 413    * @param string $old_name
 414    * @param string $new_name
 415    *
 416    * @return bool
 417    */
 418   public static function updateCurrencyName($ctx, string $old_name, string $new_name): bool {
 419     CRM_Core_DAO::executeQuery('UPDATE civicrm_currency SET name = %1 WHERE name = %2', [
 420       1 => [$new_name, 'String'],
 421       2 => [$old_name, 'String'],
 422     ]);
 423
 424     $oid = CRM_Core_DAO::singleValueQuery("SELECT id FROM civicrm_option_group WHERE name = 'currencies_enabled'");
 425     if ($oid) {
 426       CRM_Core_DAO::executeQuery('UPDATE civicrm_option_value SET value = %1 WHERE value = %2 AND option_group_id = %3', [
 427         1 => [$new_name, 'String'],
 428         2 => [$old_name, 'String'],
 429         3 => [$oid, 'String'],
 430       ]);
 431     }
 432
 433     CRM_Core_DAO::executeQuery('UPDATE civicrm_participant SET fee_currency = %1 WHERE fee_currency = %2', [
 434       1 => [$new_name, 'String'],
 435       2 => [$old_name, 'String'],
 436     ]);
 437
 438     $tables = [
 439       'civicrm_contribution',
 440       'civicrm_contribution_page',
 441       'civicrm_contribution_recur',
 442       'civicrm_contribution_soft',
 443       'civicrm_event',
 444       'civicrm_financial_item',
 445       'civicrm_financial_trxn',
 446       'civicrm_grant',
 447       'civicrm_pcp',
 448       'civicrm_pledge_payment',
 449       'civicrm_pledge',
 450       'civicrm_product',
 451     ];
 452
 453     foreach ($tables as $table) {
 454       CRM_Core_DAO::executeQuery('UPDATE %3 SET currency = %1 WHERE currency = %2', [
 455         1 => [$new_name, 'String'],
 456         2 => [$old_name, 'String'],
 457         3 => [$table, 'MysqlColumnNameOrAlias'],
 458       ]);
 459     }
 460
 461     return TRUE;
 462   }
 463
 464   /**
 465    * Re-save any valid values from contribute settings into the normal setting
 466    * format.
 467    *
 468    * We render the array of contribution_invoice_settings and any that have
 469    * metadata defined we add to the correct key. This is safe to run even if no
 470    * settings are to be converted, per the test in
 471    * testConvertUpgradeContributeSettings.
 472    *
 473    * @param $ctx
 474    *
 475    * @return bool
 476    */
 477   public static function updateContributeSettings($ctx) {
 478     // Use a direct query as api now does some handling on this.
 479     $settings = CRM_Core_DAO::executeQuery("SELECT value, domain_id FROM civicrm_setting WHERE name = 'contribution_invoice_settings'");
 480
 481     while ($settings->fetch()) {
 482       $contributionSettings = (array) CRM_Utils_String::unserialize($settings->value);
 483       foreach (array_merge(SettingsBag::getContributionInvoiceSettingKeys(), ['deferred_revenue_enabled' => 'deferred_revenue_enabled']) as $possibleKeyName => $settingName) {
 484         if (!empty($contributionSettings[$possibleKeyName]) && empty(Civi::settings($settings->domain_id)->getExplicit($settingName))) {
 485           Civi::settings($settings->domain_id)->set($settingName, $contributionSettings[$possibleKeyName]);
 486         }
 487       }
 488     }
 489     return TRUE;
 490   }
 491
 492   /**
 493    * Do any relevant smart group updates.
 494    *
 495    * @param CRM_Queue_TaskContext $ctx
 496    * @param array $actions
 497    *
 498    * @return bool
 499    */
 500   public static function updateSmartGroups($ctx, $actions) {
 501     $groupUpdateObject = new CRM_Upgrade_Incremental_SmartGroups();
 502     $groupUpdateObject->updateGroups($actions);
 503     return TRUE;
 504   }
 505
 506   /**
 507    * Drop a column from a table if it exist.
 508    *
 509    * @param CRM_Queue_TaskContext $ctx
 510    * @param string $table
 511    * @param string $column
 512    * @return bool
 513    */
 514   public static function dropColumn($ctx, $table, $column) {
 515     if (CRM_Core_BAO_SchemaHandler::checkIfFieldExists($table, $column)) {
 516       CRM_Core_DAO::executeQuery("ALTER TABLE `$table` DROP COLUMN `$column`",
 517         [], TRUE, NULL, FALSE, FALSE);
 518     }
 519     return TRUE;
 520   }
 521
 522   /**
 523    * Add a index to a table column.
 524    *
 525    * @param CRM_Queue_TaskContext $ctx
 526    * @param string $table
 527    * @param string|array $columns
 528    * @param string $prefix
 529    * @return bool
 530    */
 531   public static function addIndex($ctx, $table, $columns, $prefix = 'index') {
 532     $tables = [$table => (array) $columns];
 533     CRM_Core_BAO_SchemaHandler::createIndexes($tables, $prefix);
 534
 535     return TRUE;
 536   }
 537
 538   /**
 539    * Drop a index from a table if it exist.
 540    *
 541    * @param CRM_Queue_TaskContext $ctx
 542    * @param string $table
 543    * @param string $indexName
 544    * @return bool
 545    */
 546   public static function dropIndex($ctx, $table, $indexName) {
 547     CRM_Core_BAO_SchemaHandler::dropIndexIfExists($table, $indexName);
 548
 549     return TRUE;
 550   }
 551
 552   /**
 553    * Drop a table... but only if it's empty.
 554    *
 555    * @param CRM_Queue_TaskContext $ctx
 556    * @param string $table
 557    * @return bool
 558    */
 559   public static function dropTableIfEmpty($ctx, $table) {
 560     if (CRM_Core_DAO::checkTableExists($table)) {
 561       if (!CRM_Core_DAO::checkTableHasData($table)) {
 562         CRM_Core_BAO_SchemaHandler::dropTable($table);
 563       }
 564       else {
 565         $ctx->log->warning("dropTableIfEmpty($table): Found data. Preserved table.");
 566       }
 567     }
 568
 569     return TRUE;
 570   }
 571
 572   /**
 573    * Rebuild Multilingual Schema.
 574    * @param CRM_Queue_TaskContext $ctx
 575    * @param string|null $version CiviCRM version to use if rebuilding multilingual schema
 576    *
 577    * @return bool
 578    */
 579   public static function rebuildMultilingalSchema($ctx, $version = NULL) {
 580     $locales = CRM_Core_I18n::getMultilingual();
 581     if ($locales) {
 582       CRM_Core_I18n_Schema::rebuildMultilingualSchema($locales, $version);
 583     }
 584     return TRUE;
 585   }
 586
 587 }