Documentation

CRM_Upgrade_Incremental_php_FiveSeventy extends CRM_Upgrade_Incremental_Base
in package

Application

Upgrade logic for the 5.70.x series.

Each minor version in the series is handled by either a 5.70.x.mysql.tpl file, or a function in this class named upgrade_5_70_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.

Constants

BATCH_SIZE = 5000

Properties

$majorMinor : string|null

Methods

addColumn() : bool: Add a column to a table if it doesn't already exist
addIndex() : bool: Add a index to a table column.
addOptionGroup() : bool: Add the specified option group, gracefully if it already exists.
alterColumn() : bool
alterSchemaField() : bool: Task to add or change a column definition, based on the php schema spec.
checkFKExists() : bool
createEntityTable() : bool: Installs a newly-added core entity.
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.
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
runSql() : bool: (Queue Task Callback)
setPostUpgradeMessage() : mixed: Compute any messages which should be displayed after upgrade.
setPreUpgradeMessage() : mixed: Compute any messages which should be displayed before upgrade.
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_70_alpha1() : void: Upgrade step; adds tasks including 'runSql'.
upgrade_5_70_beta1() : void
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).

BATCH_SIZE


    public
        mixed
    BATCH_SIZE
    = 5000

$majorMinor


    protected
        string|null
    $majorMinor

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

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

Return values

bool

checkFKExists()


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

Parameters

$table_name : string
$constraint_name : string

Return values

bool

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

Return values

bool

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

dropTable()

Drop a table if it exists.


    public
            static        dropTable(CRM_Queue_TaskContext $ctx, string $tableName) : bool

Parameters

$ctx : CRM_Queue_TaskContext
$tableName : string

Return values

bool

dropTableIfEmpty()

Drop a table... but only if it's empty.


    public
            static        dropTableIfEmpty(CRM_Queue_TaskContext $ctx, string $table) : bool

Parameters

$ctx : CRM_Queue_TaskContext
$table : 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>

Return values

bool

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>

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

removePaymentProcessorType()

Remove a payment processor if not in use


    public
            static        removePaymentProcessorType(CRM_Queue_TaskContext $ctx, string $name) : bool

Parameters

$ctx : CRM_Queue_TaskContext
$name : string

Return values

bool

runSql()

(Queue Task Callback)


    public
            static        runSql(CRM_Queue_TaskContext $ctx, string $rev) : bool

Parameters

$ctx : CRM_Queue_TaskContext
$rev : string

Return values

bool

setPostUpgradeMessage()

Compute any messages which should be displayed after upgrade.


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

Downstream classes should implement this method to generate their messages.

This method will be invoked multiple times. Implementations MUST consult the $rev before deciding what messages to add. See the examples linked below.

Parameters

$postUpgradeMessage : string: Accumulated list of messages. Alterable.
$rev : string: The incremental version number. (Called repeatedly, once for each increment.)

Ex: Suppose the system upgrades from 5.7.3 to 5.10.0. The method FiveEight::setPreUpgradeMessage() will be called for each increment of '5.8.*' ('5.8.alpha1' => '5.8.beta1' => '5.8.0').

setPreUpgradeMessage()

Compute any messages which should be displayed before upgrade.


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

Downstream classes should implement this method to generate their messages.

This method will be invoked multiple times. Implementations MUST consult the $rev before deciding what messages to add. See the examples linked below.

Parameters

$preUpgradeMessage : string: Accumulated list of messages. Alterable.
$rev : string: The incremental version number. (Called repeatedly, once for each increment.)

Ex: Suppose the system upgrades from 5.7.3 to 5.10.0. The method FiveEight::setPreUpgradeMessage() will be called for each increment of '5.8.*' ('5.8.alpha1' => '5.8.beta1' => '5.8.0').
$currentVer : null = NULL: This is the penultimate version targeted by the upgrader. Equivalent to CRM_Utils_System::version().

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

updateMessageTemplates()

Do any relevant message template updates.


    public
            static        updateMessageTemplates(CRM_Queue_TaskContext $ctx, string $version) : mixed

Parameters

$ctx : CRM_Queue_TaskContext
$version : string

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_70_alpha1()

Upgrade step; adds tasks including 'runSql'.


    public
                    upgrade_5_70_alpha1(string $rev) : void

Parameters

$rev : string: The version number matching this function name

upgrade_5_70_beta1()


    public
                    upgrade_5_70_beta1(mixed $rev) : void

Parameters

$rev : mixed

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

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

CRM_Upgrade_Incremental_php_FiveSeventy extends CRM_Upgrade_Incremental_Base in package Application

Table of Contents

Constants

Properties

Methods

Constants

BATCH_SIZE

Properties

$majorMinor

Methods

addColumn()

Parameters

Return values

addIndex()

Parameters

Return values

addOptionGroup()

Parameters

Return values

alterColumn()

Parameters

Return values

alterSchemaField()

Parameters

Tags

Return values

checkFKExists()

Parameters

Return values

createEntityTable()

Parameters

Tags

Return values

dropColumn()

Parameters

Return values

dropIndex()

Parameters

Return values

dropTable()

Parameters

Return values

dropTableIfEmpty()

Parameters

Return values

enableExtension()

Parameters

Return values

enableSimpleExtension()

Parameters

Tags

Return values

getMajorMinor()

Return values

getRevisionSequence()

Tags

Return values

rebuildMultilingalSchema()

Parameters

Return values

removePaymentProcessorType()

Parameters

Tags

Return values

runSql()

Parameters

Return values

setPostUpgradeMessage()

Parameters

Tags

setPreUpgradeMessage()

Parameters

Tags

uninstallExtension()

Parameters

Return values

updateActionScheduleToken()

Parameters

Return values

updateContributeSettings()

CRM_Upgrade_Incremental_php_FiveSeventy extends CRM_Upgrade_Incremental_Base
in package

Application