class migrator

The migrator is responsible for applying new migrations in the correct order.

Properties

protected ContainerInterface $container
protected config $config
protected driver_interface $db
protected tools_interface $db_tools
protected helper $helper
protected string $table_prefix
protected string $phpbb_root_path
protected string $php_ext
protected string $migrations_table
protected array $migration_state

State of all migrations

protected array $migrations

Array of all migrations available to be run

protected array $fulfillable_migrations

Array of migrations that have been determined to be fulfillable

protected array $last_run_migration

'name,' 'class,' and 'state' of the last migration run

protected migrator_output_handler_interface $output_handler

The output handler. A null handler is configured by default.

Methods

__construct(ContainerInterface $container, config $config, driver_interface $db, tools_interface $db_tools, $migrations_table, $phpbb_root_path, $php_ext, $table_prefix, $tools, helper $helper)

Constructor of the database migrator

set_output_handler(migrator_output_handler_interface $handler)

Set the output handler.

null
load_migration_state()

Loads all migrations and their application state from the database.

array
get_last_run_migration()

Get an array with information about the last migration run.

null
set_migrations(array $class_names)

Sets the list of available migration class names to the given array.

array
get_migrations()

Get the list of available migration class names

array
get_installable_migrations()

Get the list of available and not installed migration class names

null
update()

Runs a single update step from the next migration to be applied.

string
get_valid_name(string $name)

Get a valid migration name from the migration state array in case the supplied name is not in the migration state list.

null
update_do()

Effectively runs a single update step from the next migration to be applied.

bool
try_apply(string $name)

Attempts to apply a step of the given migration or one of its dependencies

revert(string $migration)

Runs a single revert step from the last migration installed

null
revert_do(string $migration)

Effectively runs a single revert step from the last migration installed

bool
try_revert(string $name)

Attempts to revert a step of the given migration or one of its dependencies

bool|string
process_data_step(array $steps, bool|string $state, bool $revert = false)

Process the data step of the migration

null
run_step(mixed $step, mixed $last_result = 0, bool $reverse = false)

Run a single step

array
get_callable_from_step(array $step, mixed $last_result = 0, bool $reverse = false)

Get a callable statement from a data step

null
set_migration_state(string $name, array $state)

Insert/Update migration row into the database

bool|string
unfulfillable(string $name)

Checks if a migration's dependencies can even theoretically be satisfied.

bool
finished()

Checks whether all available, fulfillable migrations have been applied.

bool|array
migration_state(string $migration)

Gets a migration state (whether it is installed and to what extent)

get_migration(string $name)

Helper to get a migration

null
populate_migrations(array $migrations)

This function adds all migrations sent to it to the migrations table

null
create_migrations_table()

Creates the migrations table if it does not exist.

static bool
is_migration(string $migration)

Check if a class is a migration.

Details

at line 97
__construct(ContainerInterface $container, config $config, driver_interface $db, tools_interface $db_tools, $migrations_table, $phpbb_root_path, $php_ext, $table_prefix, $tools, helper $helper)

Constructor of the database migrator

Parameters

ContainerInterface $container
config $config
driver_interface $db
tools_interface $db_tools
$migrations_table
$phpbb_root_path
$php_ext
$table_prefix
$tools
helper $helper

at line 129
set_output_handler(migrator_output_handler_interface $handler)

Set the output handler.

Parameters

migrator_output_handler_interface $handler

The output handler

at line 139
null load_migration_state()

Loads all migrations and their application state from the database.

Return Value

null

at line 174
array get_last_run_migration()

Get an array with information about the last migration run.

The array contains 'name', 'class' and 'state'. 'effectively_installed' is set and set to true if the last migration was effectively_installed.

Return Value

array

at line 185
null set_migrations(array $class_names)

Sets the list of available migration class names to the given array.

Parameters

array $class_names

An array of migration class names

Return Value

null

at line 203
array get_migrations()

Get the list of available migration class names

Return Value

array

Array of all migrations available to be run

at line 213
array get_installable_migrations()

Get the list of available and not installed migration class names

Return Value

array

at line 238
null update()

Runs a single update step from the next migration to be applied.

The update step can either be a schema or a (partial) data update. To check if update() needs to be called again use the finished() method.

Return Value

null

at line 252
protected string get_valid_name(string $name)

Get a valid migration name from the migration state array in case the supplied name is not in the migration state list.

Parameters

string $name

Migration name

Return Value

string

Migration name

at line 278
protected null update_do()

Effectively runs a single update step from the next migration to be applied.

Return Value

null

at line 311
protected bool try_apply(string $name)

Attempts to apply a step of the given migration or one of its dependencies

Parameters

string $name

The class name of the migration

Return Value

bool

Whether any update step was successfully run

Exceptions

exception

at line 486
revert(string $migration)

Runs a single revert step from the last migration installed

YOU MUST ADD/SET ALL MIGRATIONS THAT COULD BE DEPENDENT ON THE MIGRATION TO REVERT TO BEFORE CALLING THIS METHOD! The revert step can either be a schema or a (partial) data revert. To check if revert() needs to be called again use the migration_state() method.

Parameters

string $migration

String migration name to revert (including any that depend on this migration)

at line 499
protected null revert_do(string $migration)

Effectively runs a single revert step from the last migration installed

Parameters

string $migration

String migration name to revert (including any that depend on this migration)

Return Value

null

at line 527
protected bool try_revert(string $name)

Attempts to revert a step of the given migration or one of its dependencies

Parameters

string $name

The class name of the migration

Return Value

bool

Whether any update step was successfully run

at line 634
protected bool|string process_data_step(array $steps, bool|string $state, bool $revert = false)

Process the data step of the migration

Parameters

array $steps

The steps to run

bool|string $state

Current state of the migration

bool $revert

true to revert a data step

Return Value

bool|string

migration state. True if completed, serialized array if not finished

Exceptions

exception

at line 703
protected null run_step(mixed $step, mixed $last_result = 0, bool $reverse = false)

Run a single step

An exception should be thrown if an error occurs

Parameters

mixed $step

Data step from migration

mixed $last_result

Result to pass to the callable (only for 'custom' method)

bool $reverse

False to install, True to attempt uninstallation by reversing the call

Return Value

null

at line 727
protected array get_callable_from_step(array $step, mixed $last_result = 0, bool $reverse = false)

Get a callable statement from a data step

Parameters

array $step

Data step from migration

mixed $last_result

Result to pass to the callable (only for 'custom' method)

bool $reverse

False to install, True to attempt uninstallation by reversing the call

Return Value

array

Array with parameters for call_user_func_array(), 0 is the callable, 1 is parameters

Exceptions

exception

at line 835
protected null set_migration_state(string $name, array $state)

Insert/Update migration row into the database

Parameters

string $name

Name of the migration

array $state

Return Value

null

at line 867
bool|string unfulfillable(string $name)

Checks if a migration's dependencies can even theoretically be satisfied.

Parameters

string $name

The class name of the migration

Return Value

bool|string

False if fulfillable, string of missing migration name if unfulfillable

at line 903
bool finished()

Checks whether all available, fulfillable migrations have been applied.

Return Value

bool

Whether the migrations have been applied

at line 936
bool|array migration_state(string $migration)

Gets a migration state (whether it is installed and to what extent)

Parameters

string $migration

String migration name to check if it is installed

Return Value

bool|array

False if the migration has not at all been installed, array

at line 952
migration get_migration(string $name)

Helper to get a migration

Parameters

string $name

Name of the migration

Return Value

migration

at line 973
null populate_migrations(array $migrations)

This function adds all migrations sent to it to the migrations table

THIS SHOULD NOT GENERALLY BE USED! THIS IS FOR THE PHPBB INSTALLER. THIS WILL THROW ERRORS IF MIGRATIONS ALREADY EXIST IN THE TABLE, DO NOT CALL MORE THAN ONCE!

Parameters

array $migrations

Array of migrations (names) to add to the migrations table

Return Value

null

at line 996
null create_migrations_table()

Creates the migrations table if it does not exist.

Return Value

null

at line 1022
static bool is_migration(string $migration)

Check if a class is a migration.

Parameters

string $migration

A migration class name

Return Value

bool

Return true if class is a migration, false otherwise