SqlMigrationPlanner
in package
Selects the SQL migrations a deployment has to run (`bin/migrate.php`).
A migration is a file sql/YYYY-MM-DD_NN_name.sql. Migrations run in name order, each once;
the table cms_system_sql_migrations records what already ran. Rollbacks (*_rollback.sql)
and development anonymization scripts never run.
IMPORTANT: on the first run against a database (no record table yet) it is impossible to tell
what was applied by hand earlier. Without --baseline the runner therefore fails and only
prints what it would treat as done; with --baseline everything before self::BASELINE
is only recorded as done and migrations run from there on. The operator thereby confirms
the database was brought in line with all older files by hand.
IMPORTANT: a deployed file must not change. The record keeps the SHA-256 of the content and
the runner fails on a mismatch (self::changed()). --accept-changed accepts a change
deliberately (overwrites the checksum, runs nothing again). Fix a migration with a new file.
Table of Contents
Constants
- BASELINE : string = '2026-10-02_08'
- First migration the runner executes itself; older ones were applied by hand on existing databases.
- ACCEPTED_REVISIONS : array<string|int, mixed> = ['2026-08-31_01_invoicer_customer_billing_profi...
- Earlier contents of already applied migrations that differ only in a comment; treated as identical.
- NAME_PATTERN : string = '~^\d{4}-\d{2}-\d{2}_\d+_.+\.sql$~'
Methods
- baseline() : array<int, string>
- Returns the migrations that are only recorded as done when the record table is created (see the class docblock).
- changed() : array<int, string>
- Returns the applied migrations whose file content differs from the recorded one, sorted by name.
- migrations() : array<int, string>
- Returns the files that are migrations, sorted by name.
- missing() : array<int, string>
- Returns the recorded migrations whose file is no longer in the `sql/` folder.
- pending() : array<int, string>
- Returns the migrations that have not run yet, in execution order.
Constants
BASELINE
First migration the runner executes itself; older ones were applied by hand on existing databases.
public
string
BASELINE
= '2026-10-02_08'
ACCEPTED_REVISIONS
Earlier contents of already applied migrations that differ only in a comment; treated as identical.
private
array<string|int, mixed>
ACCEPTED_REVISIONS
= ['2026-08-31_01_invoicer_customer_billing_profile.sql' => ['e6439fb9a22a0172511e4d9157e11498e07a8e17f6297acd5ac21adc7b04ad5f'], '2026-08-31_02_company_worklist_user_column_drop.sql' => ['0d997fe28e98fcd8a1df63f5648d7c19dd57fdbb854864fea2f2bc4b641ce535'], '2026-08-31_03_billing_profile_overrides.sql' => ['e55296d8004878b9fbcdfab3a591a3e32c5b961b0c6c98ef494c9ebd24027a76'], '2026-09-13_01_system_regions_geo_import.sql' => ['54856afc6a43adc1815be514310c8302505ca5db7253729fefca518d10f6064f'], '2026-09-13_02_discussion_messages_nested_set_rebuild.sql' => ['e7d47028b9cde6d5b0946ab6959ce12d41ae364c693c3bf5913aa3553c57c0ed'], '2026-09-20_03_tree_lft_rgt_indexes.sql' => ['83558d859eb2850c955399af2c1254ad3c5f6f9898d4cef0fb71a65d931eecf0']]
The records on the dev and demo databases may have been created with the original content.
file name => SHA-256 of accepted earlier contents
NAME_PATTERN
private
string
NAME_PATTERN
= '~^\d{4}-\d{2}-\d{2}_\d+_.+\.sql$~'
Methods
baseline()
Returns the migrations that are only recorded as done when the record table is created (see the class docblock).
public
static baseline(array<int, string> $fileNames) : array<int, string>
Parameters
- $fileNames : array<int, string>
Return values
array<int, string>changed()
Returns the applied migrations whose file content differs from the recorded one, sorted by name.
public
static changed(array<string, string> $recorded, array<string, string> $current) : array<int, string>
A file missing from the folder is not reported here (see self::missing()).
Parameters
- $recorded : array<string, string>
-
name => checksum from the record table
- $current : array<string, string>
-
name => current SHA-256 of the file
Return values
array<int, string>migrations()
Returns the files that are migrations, sorted by name.
public
static migrations(array<int, string> $fileNames) : array<int, string>
Parameters
- $fileNames : array<int, string>
-
file names in the
sql/folder (without path)
Return values
array<int, string>missing()
Returns the recorded migrations whose file is no longer in the `sql/` folder.
public
static missing(array<string, string> $recorded, array<int, string> $fileNames) : array<int, string>
Parameters
- $recorded : array<string, string>
-
name => checksum from the record table
- $fileNames : array<int, string>
Return values
array<int, string>pending()
Returns the migrations that have not run yet, in execution order.
public
static pending(array<int, string> $fileNames, array<int, string> $applied) : array<int, string>
Parameters
- $fileNames : array<int, string>
- $applied : array<int, string>
-
names from the record table