3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
12 use Civi\Core\SettingsBag
;
15 * Base class for incremental upgrades
17 class CRM_Upgrade_Incremental_Base
{
18 const BATCH_SIZE
= 5000;
23 protected $majorMinor;
26 * Get the major and minor version for this class (based on English-style class name).
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;
39 return $this->majorMinor
;
43 * Get a list of revisions (PATCH releases) related to this class.
46 * Ex: ['4.5.6', '4.5.7']
47 * @throws \ReflectionException
49 public function getRevisionSequence() {
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));
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]);
66 $revList = array_unique($revList);
67 usort($revList, 'version_compare');
72 * Compute any messages which should be displayed before upgrade.
74 * Downstream classes should implement this method to generate their messages.
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.
79 * @see \CRM_Upgrade_Incremental_php_FourSeven::setPreUpgradeMessage()
80 * @see \CRM_Upgrade_Incremental_php_FiveTwenty::setPreUpgradeMessage()
82 * @param string $preUpgradeMessage
83 * Accumulated list of messages. Alterable.
85 * The incremental version number. (Called repeatedly, once for each increment.)
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().
93 public function setPreUpgradeMessage(&$preUpgradeMessage, $rev, $currentVer = NULL) {
97 * Compute any messages which should be displayed after upgrade.
99 * Downstream classes should implement this method to generate their messages.
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.
104 * @see \CRM_Upgrade_Incremental_php_FourSeven::setPostUpgradeMessage()
105 * @see \CRM_Upgrade_Incremental_php_FiveTwentyOne::setPostUpgradeMessage()
107 * @param string $postUpgradeMessage
108 * Accumulated list of messages. Alterable.
110 * The incremental version number. (Called repeatedly, once for each increment.)
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').
115 public function setPostUpgradeMessage(&$postUpgradeMessage, $rev) {
119 * (Queue Task Callback)
121 * @param \CRM_Queue_TaskContext $ctx
126 public static function runSql(CRM_Queue_TaskContext
$ctx, $rev) {
127 $upgrade = new CRM_Upgrade_Form();
128 $upgrade->processSQL($rev);
134 * Syntactic sugar for adding a task.
136 * Task is (a) in this class and (b) has a high priority.
138 * After passing the $funcName, you can also pass parameters that will go to
139 * the function. Note that all params must be serializable.
141 * @param string $title
142 * @param string $funcName
144 protected function addTask($title, $funcName) {
145 $queue = CRM_Queue_Service
::singleton()->load([
147 'name' => CRM_Upgrade_Form
::QUEUE_NAME
,
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],
158 $queue->createItem($task, ['weight' => -1]);
162 * Add a task to store a snapshot of some data (if upgrade-snapshots are supported).
164 * If there is a large amount of data, this may actually add multiple tasks.
166 * Ex :$this->addSnapshotTask('event_dates', CRM_Utils_SQL_Select::from('civicrm_event')
167 * ->select('id, start_date, end_date'));
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
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.
178 if (!empty(CRM_Upgrade_Snapshot
::getActivationIssues())) {
182 $queue = CRM_Queue_Service
::singleton()->load([
184 'name' => CRM_Upgrade_Form
::QUEUE_NAME
,
186 foreach (CRM_Upgrade_Snapshot
::createTasks('civicrm', $this->getMajorMinor(), $name, $select) as $task) {
187 $queue->createItem($task, ['weight' => -1]);
192 * Add a task to activate an extension. This task will run post-upgrade (after all
193 * changes to core DB are settled).
195 * @param string $title
196 * @param string[] $keys
197 * List of extensions to enable.
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),
207 * @param \CRM_Queue_TaskContext $ctx
208 * @param string[] $keys
209 * List of extensions to enable.
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.
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'));
221 $manager = CRM_Extension_System
::singleton()->getManager();
222 $manager->enable($manager->findInstallRequirements($keys));
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();
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().
236 * Remove a payment processor if not in use
238 * @param CRM_Queue_TaskContext $ctx
239 * @param string $name
241 * @throws \CiviCRM_API3_Exception
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', [
250 if (!empty($result['id'])) {
251 civicrm_api3('PaymentProcessorType', 'delete', ['id' => $result['id']]);
258 * @param string $table_name
259 * @param string $constraint_name
262 public static function checkFKExists($table_name, $constraint_name) {
263 return CRM_Core_BAO_SchemaHandler
::checkFKExists($table_name, $constraint_name);
267 * Add a column to a table if it doesn't already exist
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
279 public static function addColumn($ctx, $table, $column, $properties, $localizable = FALSE, $version = NULL, $triggerRebuild = TRUE) {
280 $locales = CRM_Core_I18n
::getMultilingual();
282 if (!CRM_Core_BAO_SchemaHandler
::checkIfFieldExists($table, $column, FALSE)) {
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";
292 $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
296 $queries[] = "ALTER TABLE `$table` ADD COLUMN `$column` $properties";
298 foreach ($queries as $query) {
299 CRM_Core_DAO
::executeQuery($query, [], TRUE, NULL, FALSE, FALSE);
302 if ($locales && $triggerRebuild) {
303 CRM_Core_I18n_Schema
::rebuildMultilingualSchema($locales, $version, TRUE);
309 * Add the specified option group, gracefully if it already exists.
311 * @param CRM_Queue_TaskContext $ctx
312 * @param array $params
313 * @param array $options
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));
322 foreach ($options as $option) {
323 \CRM_Core_BAO_OptionValue
::ensureOptionValueExists(array_merge($optionDefaults, $option));
329 * Do any relevant message template updates.
331 * @param CRM_Queue_TaskContext $ctx
332 * @param string $version
334 public static function updateMessageTemplates($ctx, $version) {
335 $messageTemplateObject = new CRM_Upgrade_Incremental_MessageTemplates($version);
336 $messageTemplateObject->updateTemplates();
340 * Updated a message token within a template.
342 * @param CRM_Queue_TaskContext $ctx
343 * @param string $workflowName
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);
356 $messageObj->replaceTokenInMessageTemplates($old, $new);
362 * Updated a message token within a scheduled reminder.
364 * @param CRM_Queue_TaskContext $ctx
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);
378 * Updated a message token within a label.
380 * @param CRM_Queue_TaskContext $ctx
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);
394 * Updated a message token within greeting options.
396 * @param CRM_Queue_TaskContext $ctx
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);
410 * Updated a currency in civicrm_currency and related configurations
412 * @param CRM_Queue_TaskContext $ctx
413 * @param string $old_name
414 * @param string $new_name
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'],
424 $oid = CRM_Core_DAO
::singleValueQuery("SELECT id FROM civicrm_option_group WHERE name = 'currencies_enabled'");
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'],
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'],
439 'civicrm_contribution',
440 'civicrm_contribution_page',
441 'civicrm_contribution_recur',
442 'civicrm_contribution_soft',
444 'civicrm_financial_item',
445 'civicrm_financial_trxn',
448 'civicrm_pledge_payment',
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'],
465 * Re-save any valid values from contribute settings into the normal setting
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.
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'");
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]);
493 * Do any relevant smart group updates.
495 * @param CRM_Queue_TaskContext $ctx
496 * @param array $actions
500 public static function updateSmartGroups($ctx, $actions) {
501 $groupUpdateObject = new CRM_Upgrade_Incremental_SmartGroups();
502 $groupUpdateObject->updateGroups($actions);
507 * Drop a column from a table if it exist.
509 * @param CRM_Queue_TaskContext $ctx
510 * @param string $table
511 * @param string $column
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);
523 * Add a index to a table column.
525 * @param CRM_Queue_TaskContext $ctx
526 * @param string $table
527 * @param string|array $columns
528 * @param string $prefix
531 public static function addIndex($ctx, $table, $columns, $prefix = 'index') {
532 $tables = [$table => (array) $columns];
533 CRM_Core_BAO_SchemaHandler
::createIndexes($tables, $prefix);
539 * Drop a index from a table if it exist.
541 * @param CRM_Queue_TaskContext $ctx
542 * @param string $table
543 * @param string $indexName
546 public static function dropIndex($ctx, $table, $indexName) {
547 CRM_Core_BAO_SchemaHandler
::dropIndexIfExists($table, $indexName);
553 * Drop a table... but only if it's empty.
555 * @param CRM_Queue_TaskContext $ctx
556 * @param string $table
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);
565 $ctx->log
->warning("dropTableIfEmpty($table): Found data. Preserved table.");
573 * Rebuild Multilingual Schema.
574 * @param CRM_Queue_TaskContext $ctx
575 * @param string|null $version CiviCRM version to use if rebuilding multilingual schema
579 public static function rebuildMultilingalSchema($ctx, $version = NULL) {
580 $locales = CRM_Core_I18n
::getMultilingual();
582 CRM_Core_I18n_Schema
::rebuildMultilingualSchema($locales, $version);