Primordyx Framework Documentation

MigrationRunner
in package

Table of Contents

Properties

$databaseName  : string
$db  : PDO
$dryRun  : bool
$migrationsPath  : string|null
$sqlProcessor  : SqlProcessor
$tempPendingMigrations  : array<string|int, mixed>|null
$usingSystemConnection  : bool

Methods

__construct()  : mixed
MigrationRunner constructor.
continueFromMigration()  : int
Continue migrations starting from a specific migration
displayStatus()  : void
Display migration status.
dryRun()  : static
Enables or disables dry run mode for testing migrations.
getAllMigrationFiles()  : array<string|int, mixed>
Get all migration files from the migrations directory.
getExecutedMigrations()  : array<string|int, mixed>
Get executed migrations.
getLastBatch()  : array<string|int, mixed>|null
Get the last batch information.
getMigrationsInBatch()  : array<string|int, mixed>
Get migrations in a specific batch.
getMigrationsPath()  : string|null
Get the current migrations path.
getPendingMigrations()  : array<string|int, mixed>
Get all pending migrations.
getStatus()  : array<string|int, mixed>
Get migration status data.
isMigrationExecuted()  : bool
Check if a migration has been executed
logTo()  : static
Configure logging output to a specified file.
markAsExecuted()  : void
Mark a migration as executed without running it
reset()  : int
Reset all migrations by rolling back everything
rollbackBatch()  : int
Rollback a specific batch of migrations.
rollbackLast()  : int
Rollback the last batch of migrations.
runPending()  : int
Run all pending migrations with enhanced error recovery.
setMigrationsPath()  : static
Set the migrations directory path with method chaining.
checkForDatabaseSwitch()  : bool
Check if we should switch from system to target database
ensureMigrationsFile()  : void
Ensure migrations tracking file exists
establishConnection()  : void
Establish database connection, trying target database first, then system
executeMigration()  : void
Execute a migration file (up or down).
getMigrationsFilePath()  : string
Get path to migrations tracking file
getNextBatchNumber()  : int
Get the next batch number for new migrations.
readMigrationsFile()  : array<string|int, mixed>
Read migrations data from JSON file
recordMigration()  : void
Record a migration as executed.
removeMigrationRecord()  : void
Remove a migration record.
viewFailedSql()  : void
Display the SQL content that failed
writeMigrationsFile()  : void
Write migrations data to JSON file
createSystemDatabaseConnection()  : PDO
Create PDO system connection (no database) using Config
createTargetDatabaseConnection()  : PDO
Create PDO connection to target database using Config
extractErrorDetails()  : array<string|int, mixed>
Extract useful error details from SqlProcessor log text
isRecoverableError()  : bool
Determine if an error might be recoverable through user intervention
targetDatabaseExists()  : bool
Check if target database exists using system connection
truncateStatement()  : string
Truncate SQL statement for readable error messages

Properties

$tempPendingMigrations

protected array<string|int, mixed>|null $tempPendingMigrations = null

$usingSystemConnection

protected bool $usingSystemConnection = false

Methods

__construct()

MigrationRunner constructor.

public __construct(string $migrationsPath, string $databaseName) : mixed
Parameters
$migrationsPath : string

Absolute path to migrations directory.

$databaseName : string

Target database name (actual database, not connection name).

Tags
throws
RuntimeException

If connection cannot be established

throws
RuntimeException

If migrations tracking file cannot be created

throws
InvalidArgumentException

If databaseName is empty or invalid

throws
RuntimeException

If migrationsPath does not exist or is not readable

continueFromMigration()

Continue migrations starting from a specific migration

public continueFromMigration(string $startMigration) : int
Parameters
$startMigration : string

Migration name to start from

Tags
throws
Throwable
Return values
int —

Number of migrations executed

displayStatus()

Display migration status.

public displayStatus() : void

dryRun()

Enables or disables dry run mode for testing migrations.

public dryRun([bool $enable = true ]) : static
Parameters
$enable : bool = true

Set to true to enable dry run mode, false to disable

Return values
static —

Returns self for method chaining

getAllMigrationFiles()

Get all migration files from the migrations directory.

public getAllMigrationFiles() : array<string|int, mixed>
Tags
throws
RuntimeException

If migrations path is not configured

Return values
array<string|int, mixed> —

Array of migration names (without _up.sql suffix)

getExecutedMigrations()

Get executed migrations.

public getExecutedMigrations() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Associative array of executed migrations with their metadata

getLastBatch()

Get the last batch information.

public getLastBatch() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null —

Array with 'batch' and 'count' keys, or null if no migrations

getMigrationsInBatch()

Get migrations in a specific batch.

public getMigrationsInBatch(int $batchNumber) : array<string|int, mixed>
Parameters
$batchNumber : int

The batch number to filter by

Return values
array<string|int, mixed> —

Array of migration info for the specified batch

getMigrationsPath()

Get the current migrations path.

public getMigrationsPath() : string|null
Return values
string|null —

The configured migrations path, or null if not configured

getPendingMigrations()

Get all pending migrations.

public getPendingMigrations() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Array of migration names that haven't been executed

getStatus()

Get migration status data.

public getStatus() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Status information

isMigrationExecuted()

Check if a migration has been executed

public isMigrationExecuted(string $migration) : bool
Parameters
$migration : string

Migration name to check

Return values
bool —

True if migration has been executed

logTo()

Configure logging output to a specified file.

public logTo(string $logFile) : static
Parameters
$logFile : string

Absolute path to log file

Tags
throws
RuntimeException

If log file cannot be created or written

Return values
static —

Returns self for method chaining

markAsExecuted()

Mark a migration as executed without running it

public markAsExecuted(string $migration) : void
Parameters
$migration : string

Migration name to mark

Tags
throws
RuntimeException

If marking fails

reset()

Reset all migrations by rolling back everything

public reset() : int
Tags
throws
Throwable
Return values
int —

Number of migrations reset

rollbackBatch()

Rollback a specific batch of migrations.

public rollbackBatch(int $batchNumber) : int
Parameters
$batchNumber : int

Batch number to rollback

Tags
throws
RuntimeException

If rollback fails

throws
Throwable

If any error occurs during rollback

Return values
int —

Number of migrations rolled back

rollbackLast()

Rollback the last batch of migrations.

public rollbackLast() : int
Tags
throws
RuntimeException

If MigrationRunner has not been configured

throws
Throwable

If rollback fails

Return values
int —

Number of migrations rolled back

runPending()

Run all pending migrations with enhanced error recovery.

public runPending() : int
Tags
throws
RuntimeException

If migration execution fails

throws
Throwable

If any error occurs during execution

Return values
int —

Number of migrations executed

setMigrationsPath()

Set the migrations directory path with method chaining.

public setMigrationsPath(string $path) : static
Parameters
$path : string

Absolute path to migrations directory.

Return values
static —

Returns self for method chaining

checkForDatabaseSwitch()

Check if we should switch from system to target database

protected checkForDatabaseSwitch() : bool
Return values
bool —

True if we switched

ensureMigrationsFile()

Ensure migrations tracking file exists

protected ensureMigrationsFile() : void
Tags
throws
RuntimeException

If file creation fails

establishConnection()

Establish database connection, trying target database first, then system

protected establishConnection() : void
Tags
throws
RuntimeException

If neither connection type works

executeMigration()

Execute a migration file (up or down).

protected executeMigration(string $migrationName, string $direction) : void
Parameters
$migrationName : string

Migration identifier without suffix

$direction : string

Either 'up' or 'down'

Tags
throws
RuntimeException

If the migration file does not exist

throws
RuntimeException

If SqlProcessor fails to execute the SQL file

getMigrationsFilePath()

Get path to migrations tracking file

protected getMigrationsFilePath() : string
Return values
string —

Absolute path to migrations.json

getNextBatchNumber()

Get the next batch number for new migrations.

protected getNextBatchNumber() : int
Return values
int —

Next batch number to use

readMigrationsFile()

Read migrations data from JSON file

protected readMigrationsFile() : array<string|int, mixed>
Tags
throws
RuntimeException

If file cannot be read or parsed

Return values
array<string|int, mixed> —

Migration data

recordMigration()

Record a migration as executed.

protected recordMigration(string $migration, int $batch) : void
Parameters
$migration : string

Migration name

$batch : int

Batch number

Tags
throws
RuntimeException

If recording fails

removeMigrationRecord()

Remove a migration record.

protected removeMigrationRecord(string $migration) : void
Parameters
$migration : string

Migration name to remove

Tags
throws
RuntimeException

If removal fails

viewFailedSql()

Display the SQL content that failed

protected viewFailedSql(string $migrationName) : void
Parameters
$migrationName : string

The migration that failed

writeMigrationsFile()

Write migrations data to JSON file

protected writeMigrationsFile(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>

Migration data to write

Tags
throws
RuntimeException

If file cannot be written

createSystemDatabaseConnection()

Create PDO system connection (no database) using Config

private createSystemDatabaseConnection() : PDO
Tags
throws
RuntimeException

If configuration missing or connection fails

Return values
PDO

createTargetDatabaseConnection()

Create PDO connection to target database using Config

private createTargetDatabaseConnection() : PDO
Tags
throws
RuntimeException

If configuration missing or connection fails

Return values
PDO

extractErrorDetails()

Extract useful error details from SqlProcessor log text

private extractErrorDetails(string $logText, string $filePath) : array<string|int, mixed>
Parameters
$logText : string

The log text from SqlProcessor

$filePath : string

The SQL file path for context

Return values
array<string|int, mixed> —

Array with 'error' and 'statement' keys

isRecoverableError()

Determine if an error might be recoverable through user intervention

private isRecoverableError(string $message) : bool
Parameters
$message : string

Error message to analyze

Return values
bool —

True if error might be recoverable

targetDatabaseExists()

Check if target database exists using system connection

private targetDatabaseExists() : bool
Return values
bool

truncateStatement()

Truncate SQL statement for readable error messages

private truncateStatement(string $statement[, int $maxLength = 300 ]) : string
Parameters
$statement : string

The SQL statement

$maxLength : int = 300

Maximum length before truncation

Return values
string —

Truncated statement


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results