Version

Represents a schema version, including version number, comment, migration, and source file details.

class Version extends \Hazaar\Model\Struct

Extends: Hazaar\Model\Struct

Provides methods for loading, creating, replaying, rolling back, and managing schema version migrations.

Properties

comment

The comment associated with this version.

public string $comment

Type: string

source

protected array $source

Type: array

number

protected int $number

Type: int

valid

protected bool $valid = true

Type: bool

migrate

protected Event $migrate

Type: Hazaar\DBI\Manager\Migration\Event

applied_on

protected DateTime $applied_on

Type: Hazaar\Util\DateTime

user

public string $user

Type: string

Methods

__toString

Returns a string representation of the version, including number, validity, and comment.

public __toString(): void

loadFromFile

Loads a schema version from a file.

public loadFromFile(string $filename, bool $forceLoad): ?self

Returns: self

This method reads the specified file and extracts version information from its filename. The filename must follow the pattern: {number}_{comment}.json where {number} is a sequence of digits and {comment} is a word.

Parameters

Parameter	Type	Description
$filename	string	the path to the file to load
$forceLoad	bool	whether to force loading the file even if it does not match the expected fileame pattern

create

Creates a new Version instance with the current timestamp and a default comment.

public create(): self

Returns: self

getSourceFile

Retrieves the full path of the source file.

public getSourceFile(): string

Returns: string

This method constructs the full path of the source file by concatenating the directory name and the base name of the source file, separated by the directory separator.

loadMigration

Retrieves the migration script from the source file.

public loadMigration(): ?Migration

Returns: Hazaar\DBI\Manager\Migration

This method reads the content of the source file, decodes it from JSON format, and returns it as a \stdClass object. If the JSON content is invalid, an exception is thrown.

replay

Replays the migration for the current version.

public replay(Adapter $dbi, string $schemaVersionTable): bool

Returns: bool

This method loads the migration, begins a database transaction, and attempts to replay the migration. If the migration is successfully replayed, it updates the schema version in the database. If any exception occurs during the process, the transaction is canceled and the exception is rethrown.

Parameters

Parameter	Type	Description
$dbi	Hazaar\DBI\Adapter	the database adapter instance
$schemaVersionTable	string

rollback

Rollbacks the current migration version.

public rollback(Adapter $dbi, string $schemaVersionTable): bool

Returns: bool

This method attempts to rollback the current migration version by running the down method of the migration. If the rollback is successful, the version number is removed from the schema_version table. If the rollback fails, an exception is thrown and the transaction is cancelled.

Parameters

Parameter	Type	Description
$dbi	Hazaar\DBI\Adapter	the database adapter instance
$schemaVersionTable	string

unlink

Unlinks (deletes) the source file associated with this object.

public unlink(): bool

Returns: bool

generateVersionNumber

Generates a 14-digit version number based on the current date and time (YYYYMMDDHHMMSS).

public generateVersionNumber(): string

Returns: string

grant

Grants this version operation a user context.

public grant(?string $user): void

Returns: void

Parameters

Parameter	Type	Description
$user	string	the user identifier to associate, or null to clear it

constructed

Event hook called after construction to ensure migration is loaded for serialization.

protected constructed(): void

Returns: void

loadMigrationEventsBody

Loads migration event functions from the specified event.

private loadMigrationEventsBody(Event $event, string $direction): void

Returns: void

This method iterates through the actions of the given event and checks if the action type is either a function or a trigger. If the action type is not a function or trigger, or if the action specification content is already set, it continues to the next action.

For each action that requires loading content, it constructs the file path to the SQL file containing the object definition. A direction-specific file ({name}.up.sql / {name}.down.sql) takes precedence, falling back to the shared {name}.sql file. This allows the up and down migrations within a single version to define different bodies for the same object, while remaining backwards compatible with versions that use a single shared body file.

Parameters

Parameter	Type	Description
$event	Hazaar\DBI\Manager\Migration\Event	the event containing actions to be processed
$direction	string	the migration direction ('up' or 'down') the event belongs to

---

Generated by Hazaar API Doc Generator on Fri, 04 Sep 2026 23:32:16 +0000