Documentation

Activator

The activator class handles the plugin relevant activation hooks: Uninstall, activation, deactivation and installation. The "installation" means installing needed database tables.

Table of Contents

Properties

$charsetCollate  : string
See `$this->getCharsetCollate()`.

Methods

dbDelta()  : mixed
Install tables, stored procedures or whatever in the database.
getCharsetCollate()  : mixed
Get the charset collate definition for the SQL command. Similar to `$wpdb->get_charset_collate()` but it ensures to **not** mix the collates of our plugin database tables.
getDatabaseVersion()  : mixed
Get the current persisted database version.
getFirstDatabaseTableName()  : string
Return the first ever created database table created by this plugin.
getMaxIndexLength()  : mixed
Indexes have a maximum size of 767 bytes. Historically, we haven't need to be concerned about that.
getPreviousDatabaseVersions()  : array<string|int, string>
Get a list of previous installed database versions.
install()  : bool
Run an installation or dbDelta within a callable.
isMigrationLocked()  : If
Check if the migration is locked. It uses a time span of 10 minutes (like Yoast SEO plugin).
persistPreviousVersion()  : mixed
Persist the previous installed versions of this plugin so we can e.g. start migrations.
registerCapabilities()  : mixed
Register custom capabilities with e.g. `wp_roles()` and `->add_cap()`. If you add capabilities, please also remove them through the `deactivate` method.
removeColumnsFromTable()  : mixed
`dbDelta` does currently not support removing columns from tables. For this, we need to read the structure of the table and remove the column accordingly on existence.
removeIndicesFromTable()  : mixed
`dbDelta` does currently not support removing indices from tables so updating e.g. `UNIQUE KEYS` does not work.
removePreviousPersistedVersions()  : mixed
Remove the previous persisted versions from the saved option. This is useful if you have successfully finished your migration.
removeTables()  : mixed
Remove database tables if they exist.

Properties

$charsetCollate

See `$this->getCharsetCollate()`.

private string $charsetCollate = null

Methods

dbDelta()

Install tables, stored procedures or whatever in the database.

public abstract dbDelta(bool $errorlevel) : mixed

This method is always called when the version bumps up or for the first initial activation.

Use the following relevant functions to create your database tables:

  • https://developer.wordpress.org/reference/functions/dbdelta/
  • $this->getCharsetCollate() instead of $wpdb->get_charset_collate()
  • $this->getTableName() (from UtilsProvider) instead of $wpdb->prefix
  • $this->getMaxIndexLength() if you want to create an index from multiple varchar columns
Parameters
$errorlevel : bool

If true throw errors.

getDatabaseVersion()

Get the current persisted database version.

public getDatabaseVersion() : mixed

getFirstDatabaseTableName()

Return the first ever created database table created by this plugin.

public abstract getFirstDatabaseTableName() : string

This will be used to get the charset collate via $this->getCharsetCollate() to keep the charset collate intact within our plugin. Example: User updates the database version; and avoid mixed collates when a new database table gets collate utf8mb4_unicode_520_ci instead of utf8mb4_unicode_ci.

Return an empty string if your plugin does not create any database tables!

Tags
see
https://github.com/WordPress/WordPress/blob/d8c4000c53d4186b74a14c435ae44f547fde48d3/wp-includes/class-wpdb.php#L906C44-L908
see
https://github.com/WordPress/WordPress/blob/d8c4000c53d4186b74a14c435ae44f547fde48d3/wp-includes/class-wpdb.php#L4077-L4078
Return values
string

getMaxIndexLength()

Indexes have a maximum size of 767 bytes. Historically, we haven't need to be concerned about that.

public getMaxIndexLength() : mixed

As of 4.2, however, we moved to utf8mb4, which uses 4 bytes per character. This means that an index which used to have room for floor(767/3) = 255 characters, now only has room for floor(767/4) = 191 characters.

Tags
see
https://github.com/WordPress/WordPress/blob/5f9cf0141e2e32f47ae7f809b7a6bbc0d4bd4ef2/wp-admin/includes/schema.php#L48-L53
codeCoverageIgnore

getPreviousDatabaseVersions()

Get a list of previous installed database versions.

public getPreviousDatabaseVersions() : array<string|int, string>
Return values
array<string|int, string>

install()

Run an installation or dbDelta within a callable.

public install([bool $errorlevel = false ][, callable $installThisCallable = null ]) : bool
Parameters
$errorlevel : bool = false

Set true to throw errors.

$installThisCallable : callable = null

Set a callable to install this one instead of the default.

Return values
bool —

Returns false when e.g. the migration got locked

isMigrationLocked()

Check if the migration is locked. It uses a time span of 10 minutes (like Yoast SEO plugin).

public isMigrationLocked([int $set = null ]) : If
Parameters
$set : int = null
Tags
see
https://github.com/Yoast/wordpress-seo/blob/a5fd83173bf56bf7841d72bb6d3d33ecc4caa825/src/config/migration-status.php#L34-L46
Return values
If —

$set is a numeric, it returns a boolean indicating if the update of the migration was successful, otherwise it returns a boolean if the migration is locked.

persistPreviousVersion()

Persist the previous installed versions of this plugin so we can e.g. start migrations.

public persistPreviousVersion() : mixed

registerCapabilities()

Register custom capabilities with e.g. `wp_roles()` and `->add_cap()`. If you add capabilities, please also remove them through the `deactivate` method.

public registerCapabilities() : mixed

removeColumnsFromTable()

`dbDelta` does currently not support removing columns from tables. For this, we need to read the structure of the table and remove the column accordingly on existence.

public removeColumnsFromTable(string $tableName, array<string|int, string> $columnNames) : mixed
Parameters
$tableName : string

This is not escaped, so use only the result of $this->getTableName()!

$columnNames : array<string|int, string>

removeIndicesFromTable()

`dbDelta` does currently not support removing indices from tables so updating e.g. `UNIQUE KEYS` does not work.

public removeIndicesFromTable(string $tableName, array<string|int, array<string|int, mixed>> $indexConfigurations) : mixed

For this, you need to add a new index name and remove the old one.

The index needs to be configured like this:

$indexConfigurations = [
  'PRIMARY' = ['myColumn1', 'myColumn2']
]
Parameters
$tableName : string

This is not escaped, so use only the result of $this->getTableName()!

$indexConfigurations : array<string|int, array<string|int, mixed>>
Tags
see
https://whtly.com/2010/04/02/wp-dbdelta-function-cannot-modify-unique-keys/

removePreviousPersistedVersions()

Remove the previous persisted versions from the saved option. This is useful if you have successfully finished your migration.

public removePreviousPersistedVersions(callable $filter) : mixed
Parameters
$filter : callable

removeTables()

Remove database tables if they exist.

public removeTables(array<string|int, string> $tableNames) : mixed
Parameters
$tableNames : array<string|int, string>

This is not escaped, so use only the result of $this->getTableName()!


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results