Documentation

CRM_Upgrade_Incremental_php_FiveFortyEight extends CRM_Upgrade_Incremental_Base
in package
uses CRM_Upgrade_Incremental_php_TimezoneRevertTrait

Upgrade logic for the 5.48.x series.

Each minor version in the series is handled by either a 5.48.x.mysql.tpl file, or a function in this class named upgrade_5_48_x. If only a .tpl file exists for a version, it will be run automatically. If the function exists, it must explicitly add the 'runSql' task if there is a corresponding .mysql.tpl.

This class may also implement setPreUpgradeMessage() and setPostUpgradeMessage() functions.

Table of Contents

Constants

BATCH_SIZE  = 5000

Properties

$majorMinor  : string|null

Methods

addColumn()  : bool
Add a column to a table if it doesn't already exist
addEventTzTasks()  : void
addIndex()  : bool
Add a index to a table column.
addOptionGroup()  : bool
Add the specified option group, gracefully if it already exists.
addSeconds()  : string
alterColumn()  : bool
alterSchemaField()  : bool
Task to add or change a column definition, based on the php schema spec.
checkFKExists()  : bool
convertAutorun()  : bool
The `is_autorun` column was introduced in 5.47, but we didn't finish adding the additional changes to use, so there shouldn't be any real usage. But just to be paranoid, we'll convert to 5.48's `runner`.
convertModifiedEvents()  : bool
If a user edited an `Event` in the UI while running 5.47.alpha1 - 5.47.2, then `revertEventDates` won't be good enough. In particular:
convertTz()  : mixed
createEntityTable()  : bool
Installs a newly-added core entity.
createEventTzPostUpgradeMessage()  : string
createEventTzPreUpgradeMessage()  : string
dropColumn()  : bool
Drop a column from a table if it exist.
dropIndex()  : bool
Drop a index from a table if it exist.
dropTable()  : bool
Drop a table if it exists.
dropTableIfEmpty()  : bool
Drop a table... but only if it's empty.
enableExtension()  : bool
enableSimpleExtension()  : bool
This callback is used to enable one or more extensions which have no install or upgrade code, and whose autoloaders are needed right away.
fillBackupEventDates()  : bool
dev/core#2122 - keep a copy of converted dates In theory we could skip this step if logging is enabled, but (a) people might turn off logging before running upgrades, and (b) there may not be a complete record anyway. People can drop the new column if they don't need it.
findDstError()  : int
getMajorMinor()  : string
Get the major and minor version for this class (based on English-style class name).
getRevisionSequence()  : array<string|int, mixed>
Get a list of revisions (PATCH releases) related to this class.
rebuildMultilingalSchema()  : bool
Rebuild Multilingual Schema.
removePaymentProcessorType()  : bool
Remove a payment processor if not in use
revertEventDates()  : bool
This is the straight-up opposite of the conversion done in `5.47.alpha1`.
runSql()  : bool
(Queue Task Callback)
setPostUpgradeMessage()  : void
Compute any messages which should be displayed after upgrade.
setPreUpgradeMessage()  : void
Compute any messages which should be displayed beforeupgrade.
uninstallExtension()  : bool
updateActionScheduleToken()  : bool
Updated a message token within a scheduled reminder.
updateContributeSettings()  : bool
Re-save any valid values from contribute settings into the normal setting format.
updateCurrencyName()  : bool
Updated a currency in civicrm_currency and related configurations
updateGreetingOptions()  : bool
Updated a message token within greeting options.
updateMessageTemplates()  : mixed
Do any relevant message template updates.
updateMessageToken()  : bool
Updated a message token within a template.
updatePrintLabelToken()  : bool
Updated a message token within a label.
updateSmartGroups()  : bool
Do any relevant smart group updates.
upgrade_5_48_alpha1()  : void
Upgrade step; adds tasks including 'runSql'.
upgrade_5_48_beta2()  : void
Upgrade step; adds tasks including 'runSql'.
addExtensionTask()  : void
Add a task to activate an extension. It will use the full, normal installation process (invoking `hook_install`, `hook_enable`, and so on). To ensure that the installation process can rely on regular core services and APIs, it will run after the core-upgrade-steps.
addSimpleExtensionTask()  : void
Add a task to activate an extension. It will use a simple (low-tech) installation process (skipping events like `hook_install`; instead, it merely updates `civicrm_extension` and `CRM_Extension_ClassLoader`). The extension should not now (or in the future) use `hook_install`. Simple installations can run at any point during the upgrade process.
addSnapshotTask()  : void
Add a task to store a snapshot of some data (if upgrade-snapshots are supported).
addTask()  : mixed
Syntactic sugar for adding a task.
addUninstallTask()  : void
Add a task to uninstall an extension. It will use the full, uninstallation process (invoking `hook_uninstall`, `hook_disable`, and so on).
findLogRange()  : array<string|int, mixed>
Find the slice of `civicrm_log` which occurred between version $X and version $Y.
pickSkewTz()  : string
Choose a representative timezone for identifying DST errors.
swapTz()  : CRM_Utils_AutoClean
areEventsUsingTimestamp()  : bool
Check if civicrm_event start_date is a timestamp.
areThereAnyCiviEvents()  : bool
Are there any events in the system?
getTimezoneStats()  : array<string|int, mixed>

Constants

BATCH_SIZE

public mixed BATCH_SIZE = 5000

Properties

$majorMinor

protected string|null $majorMinor

Methods

addColumn()

Add a column to a table if it doesn't already exist

public static addColumn(CRM_Queue_TaskContext $ctx, string $table, string $column, string $properties[, bool $localizable = FALSE ][, string|null $version = NULL ][, bool $triggerRebuild = TRUE ]) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$table : string
$column : string
$properties : string
$localizable : bool = FALSE

is this a field that should be localized

$version : string|null = NULL

CiviCRM version to use if rebuilding multilingual schema

$triggerRebuild : bool = TRUE

should we trigger the rebuild of the multilingual schema

Return values
bool

addIndex()

Add a index to a table column.

public static addIndex(CRM_Queue_TaskContext $ctx, string $table, string|array<string|int, mixed> $columns[, string $prefix = 'index' ]) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$table : string
$columns : string|array<string|int, mixed>
$prefix : string = 'index'
Return values
bool

addOptionGroup()

Add the specified option group, gracefully if it already exists.

public static addOptionGroup(CRM_Queue_TaskContext $ctx, array<string|int, mixed> $params, array<string|int, mixed> $options) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$params : array<string|int, mixed>
$options : array<string|int, mixed>
Return values
bool

addSeconds()

public static addSeconds(string $dateTime, int $skew) : string
Parameters
$dateTime : string
$skew : int
Return values
string

alterColumn()

public static alterColumn(mixed $ctx, mixed $table, mixed $column, mixed $properties[, mixed $localizable = FALSE ]) : bool
Parameters
$ctx : mixed
$table : mixed
$column : mixed
$properties : mixed
$localizable : mixed = FALSE
Return values
bool

alterSchemaField()

Task to add or change a column definition, based on the php schema spec.

public static alterSchemaField(mixed $ctx, string $entityName, string $fieldName, array<string|int, mixed> $fieldSpec) : bool
Parameters
$ctx : mixed
$entityName : string
$fieldName : string
$fieldSpec : array<string|int, mixed>

As definied in the .entityType.php file for $entityName

Tags
throws
CRM_Core_Exception
Return values
bool

checkFKExists()

public static checkFKExists(string $table_name, string $constraint_name) : bool
Parameters
$table_name : string
$constraint_name : string
Return values
bool

convertAutorun()

The `is_autorun` column was introduced in 5.47, but we didn't finish adding the additional changes to use, so there shouldn't be any real usage. But just to be paranoid, we'll convert to 5.48's `runner`.

public static convertAutorun(CRM_Queue_TaskContext $ctx) : bool
Parameters
$ctx : CRM_Queue_TaskContext
Return values
bool

convertModifiedEvents()

If a user edited an `Event` in the UI while running 5.47.alpha1 - 5.47.2, then `revertEventDates` won't be good enough. In particular:

public static convertModifiedEvents([CRM_Queue_TaskContext|null $ctx = NULL ]) : bool
  • It's likely to have activated the DST bug (based on the current-user's TZ).
  • The user could have filled-in/corrected the values of event_tz and/or each TIMESTAMP column.

The algorithm reads backup values (eg start_date_ts_bak) and rewrites live values (eg start_date)

It uses a heuristic approach to cleaning DST error ("skew"). This requires a representative timezone ("skewTz"). It should not be necessary to know the exact TZ of every edit -- as long as all TZs have similar DST rules. For example:

  • Most locales in US+CA have the same DST rules. (America/Los_Angeles and America/Chicago are equally representative.)
  • Most locales in Europe have the same DST rules. (Europe/Helsinki and Europe/Berlin are equally representative.)
  • Most locales in Australia have the same DST rules.

By default, this will borrow the current user (sysadmin)'s timezone as the representative skewTz. This can be overridden with env-var CIVICRM_TZ_SKEW.

Parameters
$ctx : CRM_Queue_TaskContext|null = NULL
Return values
bool

convertTz()

public static convertTz(string $dateTimeExpr, string $srcTz, string $destTz) : mixed
Parameters
$dateTimeExpr : string
$srcTz : string
$destTz : string

createEntityTable()

Installs a newly-added core entity.

public static createEntityTable(mixed $ctx, string $fileName) : bool

The entityType.php file should be copied into CRM/Upgrade/Incremental/schema and prefixed with the version-added.

Parameters
$ctx : mixed
$fileName : string
Tags
throws
DBQueryException
Return values
bool

createEventTzPostUpgradeMessage()

public createEventTzPostUpgradeMessage() : string
Return values
string

createEventTzPreUpgradeMessage()

public createEventTzPreUpgradeMessage() : string
Return values
string

dropColumn()

Drop a column from a table if it exist.

public static dropColumn(CRM_Queue_TaskContext $ctx, string $table, string $column) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$table : string
$column : string
Return values
bool

dropIndex()

Drop a index from a table if it exist.

public static dropIndex(CRM_Queue_TaskContext $ctx, string $table, string $indexName) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$table : string
$indexName : string
Return values
bool

enableExtension()

public static enableExtension(CRM_Queue_TaskContext $ctx, array<string|int, string> $keys) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$keys : array<string|int, string>

List of extensions to enable.

Return values
bool

enableSimpleExtension()

This callback is used to enable one or more extensions which have no install or upgrade code, and whose autoloaders are needed right away.

public static enableSimpleExtension(CRM_Queue_TaskContext $ctx, string|array<string|int, mixed> $keys) : bool

It was written to facilitate migrating core code into extensions. Moving a class into an extension means it is no longer loaded by the core autoloader. Upgrade code that relies on it could crash if classes disappear during the upgrade, so this function sets the extension status to enabled and installs its autoloader; both of which are important depending on the upgrade interface:

  • The web UI does each step as a separate ajax request, so inserting/enabling the extension in the db ensures it is loaded on subsequent requests.
  • The CLI upgrader does everything in a single request so its autoloader should be installed right away.
Parameters
$ctx : CRM_Queue_TaskContext
$keys : string|array<string|int, mixed>
Tags
throws
CRM_Extension_Exception
throws
DBQueryException
Return values
bool

fillBackupEventDates()

dev/core#2122 - keep a copy of converted dates In theory we could skip this step if logging is enabled, but (a) people might turn off logging before running upgrades, and (b) there may not be a complete record anyway. People can drop the new column if they don't need it.

public static fillBackupEventDates(CRM_Queue_TaskContext $ctx) : bool
Parameters
$ctx : CRM_Queue_TaskContext
Return values
bool

findDstError()

public static findDstError(string $modificationTime, string $targetValue, string $timeZone) : int
Parameters
$modificationTime : string
$targetValue : string
$timeZone : string
Return values
int

getMajorMinor()

Get the major and minor version for this class (based on English-style class name).

public getMajorMinor() : string
Return values
string —

Ex: '5.34' or '4.7'

getRevisionSequence()

Get a list of revisions (PATCH releases) related to this class.

public getRevisionSequence() : array<string|int, mixed>
Tags
throws
ReflectionException
Return values
array<string|int, mixed> —

Ex: ['4.5.6', '4.5.7']

rebuildMultilingalSchema()

Rebuild Multilingual Schema.

public static rebuildMultilingalSchema(CRM_Queue_TaskContext $ctx[, string|null $version = NULL ]) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$version : string|null = NULL

CiviCRM version to use if rebuilding multilingual schema

Return values
bool

revertEventDates()

This is the straight-up opposite of the conversion done in `5.47.alpha1`.

public static revertEventDates([CRM_Queue_TaskContext|null $ctx = NULL ]) : bool

It flips the TIMESTAMPs back to DATETIMEs. This should be a clean/straight revert - provided that the records have not changed.

But some records may have changed. convertModifiedEvents() will address those.

Parameters
$ctx : CRM_Queue_TaskContext|null = NULL
Return values
bool

setPostUpgradeMessage()

Compute any messages which should be displayed after upgrade.

public setPostUpgradeMessage(string &$postUpgradeMessage, string $rev) : void

Note: This function is called iteratively for each incremental upgrade step. There must be a concrete step (eg 'X.Y.Z.mysql.tpl' or 'upgrade_X_Y_Z()').

Parameters
$postUpgradeMessage : string

alterable.

$rev : string

an intermediate version; note that setPostUpgradeMessage is called repeatedly with different $revs.

setPreUpgradeMessage()

Compute any messages which should be displayed beforeupgrade.

public setPreUpgradeMessage(string &$preUpgradeMessage, string $rev[, null $currentVer = NULL ]) : void

Note: This function is called iteratively for each incremental upgrade step. There must be a concrete step (eg 'X.Y.Z.mysql.tpl' or 'upgrade_X_Y_Z()').

Parameters
$preUpgradeMessage : string
$rev : string

a version number, e.g. '4.4.alpha1', '4.4.beta3', '4.4.0'.

$currentVer : null = NULL

uninstallExtension()

public static uninstallExtension(CRM_Queue_TaskContext $ctx, array<string|int, string> $extensionKeys) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$extensionKeys : array<string|int, string>

List of extensions to enable.

Return values
bool

updateActionScheduleToken()

Updated a message token within a scheduled reminder.

public static updateActionScheduleToken(CRM_Queue_TaskContext $ctx, string $old, string $new, mixed $version) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$old : string
$new : string
$version : mixed
Return values
bool

updateContributeSettings()

Re-save any valid values from contribute settings into the normal setting format.

public static updateContributeSettings(mixed $ctx) : bool

We render the array of contribution_invoice_settings and any that have metadata defined we add to the correct key. This is safe to run even if no settings are to be converted, per the test in testConvertUpgradeContributeSettings.

Parameters
$ctx : mixed
Return values
bool

updateCurrencyName()

Updated a currency in civicrm_currency and related configurations

public static updateCurrencyName(CRM_Queue_TaskContext $ctx, string $old_name, string $new_name) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$old_name : string
$new_name : string
Return values
bool

updateGreetingOptions()

Updated a message token within greeting options.

public static updateGreetingOptions(CRM_Queue_TaskContext $ctx, string $old, string $new, mixed $version) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$old : string
$new : string
$version : mixed
Return values
bool

updateMessageToken()

Updated a message token within a template.

public static updateMessageToken(CRM_Queue_TaskContext $ctx, string $workflowName, string $old, string $new, mixed $version) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$workflowName : string
$old : string
$new : string
$version : mixed
Return values
bool

updatePrintLabelToken()

Updated a message token within a label.

public static updatePrintLabelToken(CRM_Queue_TaskContext $ctx, string $old, string $new, mixed $version) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$old : string
$new : string
$version : mixed
Return values
bool

updateSmartGroups()

Do any relevant smart group updates.

public static updateSmartGroups(CRM_Queue_TaskContext $ctx, array<string|int, mixed> $actions) : bool
Parameters
$ctx : CRM_Queue_TaskContext
$actions : array<string|int, mixed>
Return values
bool

upgrade_5_48_alpha1()

Upgrade step; adds tasks including 'runSql'.

public upgrade_5_48_alpha1(string $rev) : void
Parameters
$rev : string

The version number matching this function name

upgrade_5_48_beta2()

Upgrade step; adds tasks including 'runSql'.

public upgrade_5_48_beta2(string $rev) : void
Parameters
$rev : string

The version number matching this function name

addExtensionTask()

Add a task to activate an extension. It will use the full, normal installation process (invoking `hook_install`, `hook_enable`, and so on). To ensure that the installation process can rely on regular core services and APIs, it will run after the core-upgrade-steps.

protected addExtensionTask(string $title, array<string|int, string> $keys[, int $weight = 2000 ]) : void

This is more suited to green-field extensions (which started life as an extension). If you have a brown-field extension which doesn't have install-logic (i.e. it arises from rearranging pre-existing core-core functionality), then consider addSimpleExtensionTask().

Parameters
$title : string
$keys : array<string|int, string>

List of extensions to enable.

$weight : int = 2000

A weight > 1500 will install after extension upgrades run. Do this for brand-new extensions. A weight < 1500 will install before extension upgrades. Do this if the extension may have previously been enabled.

addSimpleExtensionTask()

Add a task to activate an extension. It will use a simple (low-tech) installation process (skipping events like `hook_install`; instead, it merely updates `civicrm_extension` and `CRM_Extension_ClassLoader`). The extension should not now (or in the future) use `hook_install`. Simple installations can run at any point during the upgrade process.

protected addSimpleExtensionTask(string $title, string|array<string|int, string> $keys) : void

This is more suited to brown-field extensions (which arise from rearranging pre-existing core-core functionality). If you have a green-field extension (which has always been an extension), then consider addExtensionTask() instead.

Parameters
$title : string
$keys : string|array<string|int, string>

List of extensions to enable.

addSnapshotTask()

Add a task to store a snapshot of some data (if upgrade-snapshots are supported).

protected addSnapshotTask(string $name, CRM_Utils_SQL_Select $select) : void

If there is a large amount of data, this may actually add multiple tasks.

Ex :$this->addSnapshotTask('event_dates', CRM_Utils_SQL_Select::from('civicrm_event') ->select('id, start_date, end_date'));

Parameters
$name : string

Logical name for the snapshot. This will become part of the table.

$select : CRM_Utils_SQL_Select
Tags
throws
CRM_Core_Exception

addTask()

Syntactic sugar for adding a task.

protected addTask(string $title, string $funcName) : mixed

Task is (a) in this class and (b) has a high priority.

After passing the $funcName, you can also pass parameters that will go to the function. Note that all params must be serializable.

Parameters
$title : string
$funcName : string

addUninstallTask()

Add a task to uninstall an extension. It will use the full, uninstallation process (invoking `hook_uninstall`, `hook_disable`, and so on).

protected addUninstallTask(string $title, array<string|int, string> $keys[, int $weight = 1000 ]) : void
Parameters
$title : string
$keys : array<string|int, string>

List of extensions to uninstall.

$weight : int = 1000

findLogRange()

Find the slice of `civicrm_log` which occurred between version $X and version $Y.

protected static findLogRange(string $lowVersion, string $highVersion) : array<string|int, mixed>
Parameters
$lowVersion : string
$highVersion : string
Return values
array<string|int, mixed>

pickSkewTz()

Choose a representative timezone for identifying DST errors.

protected static pickSkewTz() : string

Preference will be given to ENV['CIVICRM_TZ_SKEW'] or the current user's TZ.

An explict value of IGNORE will opt-out of skew correction.

Return values
string

areEventsUsingTimestamp()

Check if civicrm_event start_date is a timestamp.

private static areEventsUsingTimestamp() : bool
Return values
bool

areThereAnyCiviEvents()

Are there any events in the system?

private static areThereAnyCiviEvents() : bool
Return values
bool

getTimezoneStats()

private getTimezoneStats() : array<string|int, mixed>
Return values
array<string|int, mixed> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results