CrossEngineMigrationTrait
Helper trait for migrations that embed values directly in raw SQL strings.
The migration execution API does not accept bound parameters, so some migrations interpolate values. MySQL and Postgres differ on string escape syntax:
- MySQL accepts backslash escapes (e.g. " ' \) as well as SQL-standard doubled single-quotes.
- Postgres follows the SQL standard: inside a single-quoted string, only a doubled single-quote ('') represents a literal quote; backslashes are taken literally. Backslash-escaped characters embedded in JSON values therefore corrupt the payload on Postgres.
Using self::sqlEscape() in place of addslashes() produces a literal that parses identically on both engines.
Table of Contents
Methods
- jsonAsText() : string
- Return a stable text expression for JSON marker comparisons.
- sqlBool() : string
- Return the SQL boolean literal for the target database.
- sqlEscape() : string
- Escape a value for inclusion inside a single-quoted SQL string literal.
- tableExistsInDb() : bool
- Check whether a table exists in the current connection. Useful for data-backfill migrations that depend on tables created by plugin migrations (which may not have run yet on a fresh install).
Methods
jsonAsText()
Return a stable text expression for JSON marker comparisons.
protected
jsonAsText(string $column) : string
PostgreSQL JSONB inserts a space after structural colons when cast to text. Historical migrations compare compact json_encode() fragments, so normalize that formatting while preserving their existing predicates.
Parameters
- $column : string
Return values
stringsqlBool()
Return the SQL boolean literal for the target database.
protected
sqlBool(bool $value) : string
Postgres requires TRUE/FALSE keywords for boolean columns and does not auto-cast integers. MySQL accepts TRUE/FALSE as aliases for 1/0, so the keyword form is safe on both engines.
Parameters
- $value : bool
Return values
stringsqlEscape()
Escape a value for inclusion inside a single-quoted SQL string literal.
protected
sqlEscape(string $value) : string
Per the SQL standard, only the single-quote character needs escaping
(by doubling it). Postgres follows this exactly. MySQL, however, also
treats backslash () as an escape character inside string literals
unless NO_BACKSLASH_ESCAPES mode is set — so embedded \ in a value
(e.g. PHP class names like App\Policy\Foo or JSON \\ sequences)
would be eaten. On MySQL we therefore also double the backslashes.
On Postgres with the default standard_conforming_strings = on
backslashes are already literal, so doubling them would corrupt the
value — do not escape them there.
Parameters
- $value : string
Return values
stringtableExistsInDb()
Check whether a table exists in the current connection. Useful for data-backfill migrations that depend on tables created by plugin migrations (which may not have run yet on a fresh install).
protected
tableExistsInDb(string $tableName) : bool
Parameters
- $tableName : string