MigrationRunner
The migration engine — discovers the version files, compares them with the tracking collection of the database, and applies / rolls back the difference.
Stateless with respect to time and identity: the run timestamps, the
acting agent (user@host) and the gitCommit are injected, so a host
can stamp them and the tests can pin them.
Tags
Table of Contents
Properties
- $agent : string|null
- $db : ArangoDB
- $gitCommit : string|null
- $namespace : string
- $path : string
- $store : MigrationStore
Methods
- __construct() : mixed
- apply() : array<int, MigrationAction>
- Applies the pending migrations in order. For each: records an `active` row, runs `up()`, then records `completed` — or `failed` (with the error) and **stops immediately**, leaving the following migrations untouched.
- discover() : array<string, Migration>
- Discovers the migration version files of the configured directory, instantiated and sorted by version (the timestamp prefix orders them).
- down() : array<int, string>
- Rolls back the `$count` most recently applied migrations (LIFO): runs each `down()` then removes its tracking row. A migration whose file is gone, or whose `down()` is the default no-op, is skipped from the rollback effect but still un-tracked.
- forget() : void
- Removes a migration's tracking row **without** running its `down()` — the rescue operation for a tracking collection that drifted from reality (e.g. a migration undone by hand). Dangerous: the migration will be considered pending again on the next run.
- pending() : array<string, Migration>
- Returns the pending migrations — discovered but not yet applied, in ascending order.
- status() : array<int, array<string, mixed>>
- Returns the status of every migration — discovered files crossed with the applied tracking rows.
- newAction() : MigrationAction
- Builds a fresh {@see MigrationAction} stamped with the run identity.
- now() : string
- The current ISO 8601 timestamp (overridable in tests).
- version() : string
- Strips the `Version` prefix to get the tracking version / `_key`.
- versionFiles() : array<int, string>
- The `Version*.php` files of the configured directory.
Properties
$agent
protected
string|null
$agent
= null
$db
protected
ArangoDB
$db
$gitCommit
protected
string|null
$gitCommit
= null
$namespace
protected
string
$namespace
= ''
$path
protected
string
$path
$store
protected
MigrationStore
$store
Methods
__construct()
public
__construct(ArangoDB $db, MigrationStore $store, string $path[, string $namespace = '' ][, string|null $gitCommit = null ][, string|null $agent = null ]) : mixed
Parameters
- $db : ArangoDB
-
The façade handed to every Migration.
- $store : MigrationStore
-
The tracking-collection persistence.
- $path : string
-
The directory holding the
Version*.phpfiles. - $namespace : string = ''
-
The PHP namespace the version classes live in (e.g.
fr\bouney\migrations). - $gitCommit : string|null = null
-
The current git commit hash, or null outside a repository.
- $agent : string|null = null
-
The acting agent (
user@host), or null.
apply()
Applies the pending migrations in order. For each: records an `active` row, runs `up()`, then records `completed` — or `failed` (with the error) and **stops immediately**, leaving the following migrations untouched.
public
apply([string|null $now = null ]) : array<int, MigrationAction>
Parameters
- $now : string|null = null
-
The run timestamp (ISO 8601) — injected for determinism; defaults to the current time.
Tags
Return values
array<int, MigrationAction> —The recorded actions, in run order (the last is failed when the run aborted).
discover()
Discovers the migration version files of the configured directory, instantiated and sorted by version (the timestamp prefix orders them).
public
discover() : array<string, Migration>
Tags
Return values
array<string, Migration> —The migrations keyed by version, in ascending order.
down()
Rolls back the `$count` most recently applied migrations (LIFO): runs each `down()` then removes its tracking row. A migration whose file is gone, or whose `down()` is the default no-op, is skipped from the rollback effect but still un-tracked.
public
down([int $count = 1 ]) : array<int, string>
Parameters
- $count : int = 1
-
The number of migrations to roll back (the last ones).
Tags
Return values
array<int, string> —The versions rolled back, most-recent first.
forget()
Removes a migration's tracking row **without** running its `down()` — the rescue operation for a tracking collection that drifted from reality (e.g. a migration undone by hand). Dangerous: the migration will be considered pending again on the next run.
public
forget(string $version) : void
Parameters
- $version : string
-
The migration version to forget.
Tags
pending()
Returns the pending migrations — discovered but not yet applied, in ascending order.
public
pending() : array<string, Migration>
Tags
Return values
array<string, Migration>status()
Returns the status of every migration — discovered files crossed with the applied tracking rows.
public
status() : array<int, array<string, mixed>>
Each entry: version, description, applied (bool), status
(the tracking actionStatus, or null), missingFile (true for an
applied version whose file is gone).
Tags
Return values
array<int, array<string, mixed>>newAction()
Builds a fresh {@see MigrationAction} stamped with the run identity.
protected
newAction(string $version, string $description, string $additionalType) : MigrationAction
Parameters
- $version : string
-
The version (
_key). - $description : string
-
The human description.
- $additionalType : string
-
The event family (MigrationKind).
Return values
MigrationActionnow()
The current ISO 8601 timestamp (overridable in tests).
protected
now() : string
Return values
stringversion()
Strips the `Version` prefix to get the tracking version / `_key`.
protected
version(string $className) : string
Parameters
- $className : string
-
The
Version<timestamp>_<Label>class/file name.
Return values
stringversionFiles()
The `Version*.php` files of the configured directory.
protected
versionFiles() : array<int, string>