Documentation

CRM_Core_BAO_SchemaHandler
in package

CRM

This file contains functions for creating and altering CiviCRM-tables structure.

$table = array( 'name' => TABLE_NAME, 'attributes' => ATTRIBUTES, 'fields' => array( array( 'name' => FIELD_NAME, // can be field, index, constraint 'type' => FIELD_SQL_TYPE, 'class' => FIELD_CLASS_TYPE, 'primary' => BOOLEAN, 'required' => BOOLEAN, 'searchable' => TRUE, 'fk_table_name' => FOREIGN_KEY_TABLE_NAME, 'fk_field_name' => FOREIGN_KEY_FIELD_NAME, 'comment' => COMMENT, 'default' => DEFAULT, ) ... ));

Constants

DEFAULT_COLLATION = 'utf8mb4_unicode_ci'

Methods

addIndexSignature() : mixed: Add index signature hash to DAO file calculation.
alterFieldLength() : mixed
buildFieldChangeSql() : string: Build the sql to alter the field.
buildFieldSQL() : string
buildForeignKeySQL() : string
buildIndexSQL() : string
buildPrimaryKeySQL() : string
buildSearchIndexSQL() : null|string
buildTableSQL() : string
changeFKConstraint() : void
changeUniqueToIndex() : mixed
checkFKExists() : bool: Check if a foreign key Exists
checkIfFieldExists() : bool: Check if the table has a specified column.
checkIfIndexExists() : bool: Check if the table has an index matching the name.
createIndexes() : void: Create indexes.
createMissingIndices() : mixed: Create missing indices.
createTable() : bool: Create a CiviCRM-table
databaseSupportsUTF8MB4() : bool: Does the database support utf8mb4.
defaultAttributes() : string
dropColumn() : mixed
dropIndexIfExists() : mixed: Drop an index if one by that name exists.
dropTable() : void: Drop a table if it exists.
getDBCharset() : string: Get the database collation.
getDBCollation() : string: Get the database collation.
getFieldAlterSQL() : string: Get the sql to alter an individual field.
getIndexes() : mixed: Get indexes for tables
getIndexName() : string: Turns tableName + columnName into a safe & predictable index name
getInUseCollation() : string: Get the collation actually being used by the tables in the database.
getMissingIndices() : array<string|int, mixed>: Compare the indices specified in the XML files with those in the DB.
getRowCountForTable() : int: Get estimated number of rows in the given table.
getRowCountForTables() : array<string|int, mixed>: Get estimated number of rows in the given tables.
migrateUtf8mb4() : bool: Performs the utf8mb4 migration.
safeRemoveFK() : bool: Remove a foreign key from a table if it exists.

DEFAULT_COLLATION


    public
        mixed
    DEFAULT_COLLATION
    = 'utf8mb4_unicode_ci'

addIndexSignature()

Add index signature hash to DAO file calculation.


    public
            static        addIndexSignature(string $table, array<string|int, mixed> &$indices) : mixed

Parameters

$table : string: table name
$indices : array<string|int, mixed>: index array spec

alterFieldLength()


    public
            static        alterFieldLength(int $customFieldID, string $tableName, string $columnName, mixed $length) : mixed

Parameters

$customFieldID : int
$tableName : string
$columnName : string
$length : mixed

buildFieldChangeSql()

Build the sql to alter the field.


    public
            static        buildFieldChangeSql(array<string|int, mixed> $params) : string

Parameters

$params : array<string|int, mixed>

Return values

string

buildFieldSQL()


    public
            static        buildFieldSQL(array<string|int, mixed> $params, string $separator[, string $prefix = '' ]) : string

Parameters

$params : array<string|int, mixed>
$separator : string
$prefix : string = ''

Return values

string

buildForeignKeySQL()


    public
            static        buildForeignKeySQL(array<string|int, mixed> $params, string $separator, string $prefix, string $tableName) : string

Parameters

$params : array<string|int, mixed>
$separator : string
$prefix : string
$tableName : string

Return values

string

buildIndexSQL()


    public
            static        buildIndexSQL(array<string|int, mixed> $params[, string $separator = '' ]) : string

Parameters

$params : array<string|int, mixed>
$separator : string = ''

Return values

string

buildPrimaryKeySQL()


    public
            static        buildPrimaryKeySQL(array<string|int, mixed> $params, mixed $separator[, string $prefix = '' ]) : string

Parameters

$params : array<string|int, mixed>
$separator : mixed
$prefix : string = ''

Return values

string

buildSearchIndexSQL()


    public
            static        buildSearchIndexSQL(array<string|int, mixed> $params, string $separator[, string $prefix = '' ][, string $existingIndex = '' ]) : null|string

Parameters

$params : array<string|int, mixed>
$separator : string
$prefix : string = ''
$existingIndex : string = ''

Return values

null|string

buildTableSQL()


    public
            static        buildTableSQL(array<string|int, mixed> $params) : string

Parameters

$params : array<string|int, mixed>

Return values

string

changeFKConstraint()


    public
            static        changeFKConstraint(string $tableName, string $fkTableName) : void

Parameters

$tableName : string
$fkTableName : string

changeUniqueToIndex()


    public
            static        changeUniqueToIndex(string $tableName[, bool $dropUnique = TRUE ]) : mixed

Parameters

$tableName : string
$dropUnique : bool = TRUE

checkFKExists()

Check if a foreign key Exists


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

Parameters

$table_name : string
$constraint_name : string

Return values

bool —

TRUE if FK is found

checkIfFieldExists()

Check if the table has a specified column.


    public
            static        checkIfFieldExists(string $tableName, string $columnName[, bool $i18nRewrite = TRUE ]) : bool

Parameters

$tableName : string
$columnName : string
$i18nRewrite : bool = TRUE: Whether to rewrite the query on multilingual setups.

Return values

bool

checkIfIndexExists()

Check if the table has an index matching the name.


    public
            static        checkIfIndexExists(string $tableName, string $indexName) : bool

Parameters

$tableName : string
$indexName : string

Return values

bool

createIndexes()

Create indexes.


    public
            static        createIndexes(array<string|int, mixed> $tables[, string $createIndexPrefix = 'index' ][, array<string|int, mixed> $substrLengths = [] ]) : void

Parameters

$tables : array<string|int, mixed>: Tables to create index for in the format: ['civicrm_entity_table' => ['entity_id']] OR array['civicrm_entity_table' => [['entity_id', 'entity_table']] The latter will create a combined index on the 2 keys (in order).

Side note - when creating combined indexes the one with the most variation goes first - so entity_table always goes after entity_id.

It probably makes sense to consider more sophisticated options at some point but at the moment this is only being as enhanced as fast as the test is.
$createIndexPrefix : string = 'index'
$substrLengths : array<string|int, mixed> = []

createMissingIndices()

Create missing indices.


    public
            static        createMissingIndices(array<string|int, mixed> $missingIndices) : mixed

Parameters

$missingIndices : array<string|int, mixed>: as returned by getMissingIndices()

createTable()

Create a CiviCRM-table


    public
            static        createTable(array<string|int, mixed> $params) : bool

Parameters

$params : array<string|int, mixed>

Return values

bool —

TRUE if successfully created, FALSE otherwise

databaseSupportsUTF8MB4()

Does the database support utf8mb4.


    public
            static        databaseSupportsUTF8MB4() : bool

Utf8mb4 is required to support emojis but older databases may not have it enabled.

This is aggressively cached despite just being a string function as it is expected it might be called many times.

Return values

bool

defaultAttributes()


    public
            static        defaultAttributes() : string

Return values

string

dropColumn()


    public
            static        dropColumn(string $tableName, string $columnName[, bool $l18n = FALSE ][, bool $isUpgradeMode = FALSE ]) : mixed

Parameters

$tableName : string
$columnName : string
$l18n : bool = FALSE
$isUpgradeMode : bool = FALSE

dropIndexIfExists()

Drop an index if one by that name exists.


    public
            static        dropIndexIfExists(string $tableName, string $indexName) : mixed

Parameters

$tableName : string
$indexName : string

dropTable()

Drop a table if it exists.


    public
            static        dropTable(string $tableName) : void

Parameters

$tableName : string

getDBCharset()

Get the database collation.


    public
            static        getDBCharset() : string

Return values

string

getDBCollation()

Get the database collation.


    public
            static        getDBCollation() : string

Return values

string

getFieldAlterSQL()

Get the sql to alter an individual field.


    public
            static        getFieldAlterSQL(array<string|int, mixed> $params) : string

This will need to have an ALTER TABLE statement appended but by getting by individual field we can do one or many.

Parameters

$params : array<string|int, mixed>

Return values

string

getIndexes()

Get indexes for tables


    public
            static        getIndexes(array<string|int, mixed> $tables) : mixed

Parameters

$tables : array<string|int, mixed>: array of table names to find indexes for

getIndexName()

Turns tableName + columnName into a safe & predictable index name


    public
            static        getIndexName(mixed $tableName, mixed $columnName) : string

Parameters

$tableName : mixed
$columnName : mixed

Return values

string

getInUseCollation()

Get the collation actually being used by the tables in the database.


    public
            static        getInUseCollation() : string

The db collation may not match the collation used by the tables, get what is set on the tables (represented by civicrm_contact).

Return values

string

getMissingIndices()

Compare the indices specified in the XML files with those in the DB.


    public
            static        getMissingIndices([bool $dropFalseIndices = FALSE ][, array<string|int, mixed>|false $tables = FALSE ]) : array<string|int, mixed>

Parameters

$dropFalseIndices : bool = FALSE: If set - this function deletes false indices present in the DB which mismatches the expected values of xml file so that civi re-creates them with correct values using createMissingIndices() function.
$tables : array<string|int, mixed>|false = FALSE: An optional array of tables - if provided the results will be restricted to these tables.

Return values

array<string|int, mixed> —

index specifications

getRowCountForTable()

Get estimated number of rows in the given table.


    public
            static        getRowCountForTable(string $tableName) : int

Parameters

$tableName : string

Return values

int —

The approximate number of rows in the table. This is also 0 if the table does not exist.

getRowCountForTables()

Get estimated number of rows in the given tables.


    public
            static        getRowCountForTables(array<string|int, mixed> $tables) : array<string|int, mixed>

Note that this query is less precise than SELECT(*) - especially on larger tables but performs significantly better. See https://dba.stackexchange.com/questions/184685/why-is-count-slow-when-explain-knows-the-answer

Parameters

$tables : array<string|int, mixed>: e.g ['civicrm_contact', 'civicrm_activity']

Return values

array<string|int, mixed> —

e.g ['civicrm_contact' => 200000, 'civicrm_activity' => 100000]

migrateUtf8mb4()

Performs the utf8mb4 migration.


    public
            static        migrateUtf8mb4([bool $revert = FALSE ][, array<string|int, mixed> $patterns = [] ][, array<string|int, mixed> $databaseList = NULL ]) : bool

Parameters

$revert : bool = FALSE: Being able to revert if primarily for unit testing.
$patterns : array<string|int, mixed> = []: Defaults to ['civicrm_%'] but can be overridden to specify any pattern. eg ['civicrm_%', 'civi%_%', 'veda%_%'].
$databaseList : array<string|int, mixed> = NULL: Allows you to specify an alternative database to the configured CiviCRM database.

Return values

bool

safeRemoveFK()

Remove a foreign key from a table if it exists.


    public
            static        safeRemoveFK(mixed $table_name, mixed $constraint_name) : bool

Parameters

$table_name : mixed
$constraint_name : mixed

Return values

bool

CRM_Core_BAO_SchemaHandler in package CRM

Table of Contents

Constants

Methods

Constants

DEFAULT_COLLATION

Methods

addIndexSignature()

Parameters

alterFieldLength()

Parameters

Tags

buildFieldChangeSql()

Parameters

Return values

buildFieldSQL()

Parameters

Return values

buildForeignKeySQL()

Parameters

Return values

buildIndexSQL()

Parameters

Return values

buildPrimaryKeySQL()

Parameters

Return values

buildSearchIndexSQL()

Parameters

Return values

buildTableSQL()

Parameters

Return values

changeFKConstraint()

Parameters

changeUniqueToIndex()

Parameters

checkFKExists()

Parameters

Return values

checkIfFieldExists()

Parameters

Return values

checkIfIndexExists()

Parameters

Return values

createIndexes()

Parameters

Tags

createMissingIndices()

Parameters

createTable()

Parameters

Return values

databaseSupportsUTF8MB4()

Return values

defaultAttributes()

Return values

dropColumn()

Parameters

dropIndexIfExists()

Parameters

dropTable()

Parameters

Tags

getDBCharset()

Return values

getDBCollation()

Return values

getFieldAlterSQL()

Parameters

Return values

getIndexes()

Parameters

Tags

getIndexName()

Parameters

Return values

getInUseCollation()

Return values

CRM_Core_BAO_SchemaHandler
in package

CRM