Download the PHP package pinkcrab/wp-db-migrations without Composer
On this page you can find all versions of the php package pinkcrab/wp-db-migrations. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download pinkcrab/wp-db-migrations
More information about pinkcrab/wp-db-migrations
Files in pinkcrab/wp-db-migrations
Package wp-db-migrations
Short Description Creates wpdb migrations as part of the PinkCrab Plugin Framework
License MIT
Homepage https://pinkcrab.co.uk
Rated 5.00 based on 1 reviews
Informations about the package wp-db-migrations
WPDB_Migrations
System for creating database migrations with WordPress
Requirements
Requires PinkCrab Table Builder, Composer and WordPress.
Uses the WPDB Table Builder library.
TESTED AGAINST
- PHP 7.2, 7.3, 7.4, 8.0 & 8.1
- Mysql 5.7, MariaDB 10.2, 10.3, 10.4, 10.5, 10.6 & 10.7
- WP5.9, WP6.0 & WP6.1
Installation
If you are using this with the PinkCrab Perique framework, please use the Perique Migrations module.
Why
Creates a wrapper around the WPDB_Table_Builder to make it easier to create Migrations for use with WP plugins or themes. Allows for the creation and dropping of database tables and the seeding of initial data.
How to use
You will need to create your Migrations using the abstract class.
Once you have your Migrations created it is a case of using the Migration_Manager to handle the creation, seeding and eventual dropping of the table.
Read the Builder documentation
It is suggested to wrap create_tables, seed_tables and drop_tables in a try/catch as they can throw exceptions.
Reade more about the Migration Manager
Factory
You can create an instance of both a Migration Manager and Migration Log.
Factory::manager_with_db_delta(?string $option_key = null, ?wpdb $wpdb = null)
Can be used to create a manager set with a standard wpdb instance. A custom log option key can be defined and a custom wpdb instance can be used if you wish to use multiple databases.
Factory::migration_log(?string $option_key = null)
Creates an instance of the migration log, the option key used in the migration manager can be optionally passed if a custom value is set.
Migration Log
The Migration Manager has an internal log which is serialised and stored as a WP Option. This is used to ensure that tables are only updated when the schema has changed and that only a single seeding of each table can happen. If you need to access the Log, you can either call it from a Migration_Manager instance or by creating an instance.
Reade more about the Migration Log
Exceptions
During the process, multiple exceptions can be thrown, these are all
All of our exceptions contain the instance of Schema being worked on, this can be accessed via
$exception->get_schema()
. Also WPDB error is set if WPDB error triggered, this can be accessed using$exception->get_wpdb_error()
(seed_column_doesnt_exist, doesn't use this)
seed_column_doesnt_exist
Thrown when trying get the column data from a schema, where the column doesn't exist.
Message: Could not find column {column name} in {table name} schema definition
Error Code: 1
failed_to_insert_seed
Thrown when attempting to insert seed data, but wpdb returns an error.
Message: Could not insert seed into {table name}, failed with error {wpdb error}
Error Code: 2
failed_to_drop_table
Thrown when wpdb produces an error removing a table.
Message: Failed to drop {table name}
Error Code: 3
Use With Plugins
The best way to use the Migration service is as part of your plugins activation/uninstall process. This would ensure that all tables are created and seeded when the plugin is activated and all tables are dropped when the plugin is uninstalled.
Thanks to the Migration_Log, tables will only be reprocessed if the schema has changed and data can only be seeded once. So if you plan to add seed data in for later versions of your plugin, they can be added when ready.
When working with Foreign Keys, ensure that all base tables are created first, then those that reference it. But when dropping ensure this is done in reverse.
Tables are all created, then all seeded in the same order
Change log
- 1.0.4 - Updated dependencies and testing pipeline
- 1.0.3 - Improved exceptions
- 1.0.2 - Updated docs, added in means to clear all Logs from Log Manager and fixed a type with
Migration_Manager::migation_log()
(this method has been deprecated and replace withMigration_Manager::migration_log()
) - 1.0.1 - Allows access to the migration manager log key via
Migration_Log_Manager->get_log_key()
method - 1.0.0 - Now supportsWPDB Table Builder 1.0.0
- 0.3.1 - Added Dependabot config
- 0.3.0 - Migrated from WPDB Table Builder 0.2 to 0.3
- 0.2.0 - Extracted from the (OLD) PinkCrab Framework v0.1.0 registerables package.