---

Manager

Relational Database Schema Manager.

• Full name: \Hazaar\DBI\Schema\Manager

Constants

Constant	Visibility	Type	Value
MACRO_VARIABLE	public		1
MACRO_LOOKUP	public		2

Properties

schemaInfoTable

public static string $schemaInfoTable

• This property is static.

---

dbi

private \Hazaar\DBI\Adapter $dbi

---

dbiConfig

private \Hazaar\Map $dbiConfig

---

dbDir

private string $dbDir

---

migrateDir

private string $migrateDir

---

dataFile

private string $dataFile

---

migrationLog

private (mixed|string)[][] $migrationLog

---

ignoreTables

private string[] $ignoreTables

---

versions

private array<int,string[]> $versions

---

currentVersion

private ?int $currentVersion

---

appliedVersions

private array<int,string> $appliedVersions

---

__callback

private ?\Closure $__callback

---

tableMap

private static array<string,array> $tableMap

• This property is static.

---

Methods

__construct

public __construct(\Hazaar\Map $dbiConfig, ?\Closure $logCallback = null): mixed

Parameters:

Parameter	Type	Description
$dbiConfig	\Hazaar\Map
$logCallback	?\Closure

---

getVersion

Returns the currently applied schema version.

public getVersion(): ?int

---

getVersions

Returns a list of available schema versions.

public getVersions(bool $returnFullPath = false, bool $appliedOnly = false): array<int,string>

Parameters:

Parameter	Type	Description
$returnFullPath	bool
$appliedOnly	bool

---

getLatestVersion

Returns the version number of the latest schema version.

public getLatestVersion(): ?int

---

isLatest

Boolean indicator for when the current schema version is the latest.

public isLatest(): bool

---

hasUpdates

Boolean indicator for when there are migrations that have not been applied.

public hasUpdates(): bool

---

getSchema

public getSchema(?int $maxVersion = null): array|false

Parameters:

Parameter	Type	Description
$maxVersion	?int

---

truncate

public truncate(): void

---

snapshot

Snapshot the database schema and create a new schema version with migration replay files.

public snapshot(string $comment = null, bool $test = false, int $override_version = null): bool

This method is used to create the database schema migration files. These files are used by the \Hazaar\Adapter::migrate() method to bring a database up to a certain version. Using this method simplifies creating these migration files and removes the need to create them manually when there are trivial changes.

When developing your project

Currently only the following changes are supported:

• Table creation, removal and rename.
• Column creation, removal and alteration.
• Index creation and removal.

!!! notice

Table rename detection works by comparing new tables with removed tables for tables that have the same columns. Because of this, rename detection will not work if columns are added or removed at the same time the table is renamed. If you want to rename a table, make sure that this is the only operation being performed on the table for a single snapshot. Modifying other tables will not affect this. If you want to rename a table AND change it's column layout, make sure you do either the rename or the modifications first, then snapshot, then do the other operation before snapshotting again.

Parameters:

Parameter	Type	Description
$comment	string	a comment to add to the migration file
$test	bool	Test only. Does not make any changes.
$override_version	int	Manually specify the version number. Default is to use current timestamp.

Return Value:

True if the snapshot was successful. False if no changes were detected and nothing needed to be done.

Throws:

• Snapshot

---

getMissingVersions

public getMissingVersions(?int $version = null, int[]& $appliedVersions = null): int[]

Parameters:

Parameter	Type	Description
$version	?int
$appliedVersions	int[]

---

migrate

Database migration method.

public migrate(int $version = null, bool $forceDataSync = false, bool $test = false, bool $keepTables = false, bool $force_reinitialise = false): bool

This method does some fancy database migration magic. It makes use of the 'db' subdirectory in the project directory which should contain the schema.json file. This file is the current database schema definition.

A few things can occur here.

If the database schema does not exist, then a new schema will be created using the schema.json schema definition file.

This will create the database at the latest version of the schema.

If the database schema already exists, then the current version is checked against the version requested using the

$version parameter. If no version is requested ($version is NULL) then the latest version number is used.

If the version numbers are different, then a migration will be performed.

# If the requested version is greater than the current version, the migration mode will be 'up'.

# If the requested version is less than the current version, the migration mode will be 'down'.

All migration files between the two selected versions (current and requested) will be replayed using the migration mode.

This process can be used to bring a database schema up to the latest version using database migration files stored in the db/migrate project subdirectory. These migration files are typically created using the \Hazaar\Adapter::snapshot() method although they can be created manually. Take care when using manually created migration files.

The migration is performed in a database transaction (if the database supports it) so that if anything goes wrong there is no damage to the database. If something goes wrong, errors will be availabl in the migration log accessible with \Hazaar\Adapter::getMigrationLog(). Errors in the migration files can be fixed and the migration retried.

Parameters:

Parameter	Type	Description
$version	int	the database schema version to migrate to
$forceDataSync	bool
$test	bool
$keepTables	bool
$force_reinitialise	bool

Return Value:

Returns true on successful migration. False if no migration was neccessary. Throws an Exception on error.

---

migrateReplay

public migrateReplay(int $version, bool $test = false): bool

Parameters:

Parameter	Type	Description
$version	int
$test	bool

---

rollback

Undo a migration version.

public rollback(int $version, bool $test = false, string[]& $rollbacks = []): bool

Parameters:

Parameter	Type	Description
$version	int
$test	bool
$rollbacks	string[]

---

applySchema

Takes a schema definition and creates it in the database.

public applySchema(array $schema, bool $test = false, bool $keepTables = false): bool

Parameters:

Parameter	Type	Description
$schema	array
$test	bool
$keepTables	bool

---

applySchemaFromFile

public applySchemaFromFile(string $filename): bool

Parameters:

Parameter	Type	Description
$filename	string

---

syncData

public syncData(array $dataSchema = null, bool $test = false, bool $forceDataSync = false): bool

Parameters:

Parameter	Type	Description
$dataSchema	array
$test	bool
$forceDataSync	bool

---

setLogCallback

Sets a callback function that can be used to process log messages.

public setLogCallback(\Closure $callback): bool

The callback function provided must accept two arguments. $time and $msg.

Example, to simply echo formatted log data:

'''php $manager->setLogCallback(function($time, $msg){ echo date('Y-m-d H:i:s', (int)$time) . " - $msg\n"; }); '''

Parameters:

Parameter	Type	Description
$callback	\Closure	The 'callable' callback function. See: is_callable();

---

getMigrationLog

Returns the migration log.

public getMigrationLog(): array<int,array>

Snapshots and migrations are complex processes where many things happen in a single execution. This means stuff can go wrong and you will probably want to know what/why when they do.

When running \Hazaar\Adapter::snapshot() or \Hazaar\Adapter::migrate() a log of what has been done is stored internally in an array of timestamped messages. You can use the \Hazaar\Adapter::getMigrationLog() method to retrieve this log so that if anything goes wrong, you can see what and fix it/

---

createRoleIfNotExists

public createRoleIfNotExists(array[]|string $roleOrRoles): void

Parameters:

Parameter	Type	Description
$roleOrRoles	array[]|string

---

checkpoint

public checkpoint(?int $version = null): bool

Parameters:

Parameter	Type	Description
$version	?int

---

createInfoTable

Creates the info table that stores the version info of the current database.

private createInfoTable(): bool

---

getColumn

private getColumn(string $needle, array $haystack, string $key = 'name'): mixed

Parameters:

Parameter	Type	Description
$needle	string
$haystack	array
$key	string

---

colExists

private colExists(string $needle, array $haystack, string $key = 'name'): bool

Parameters:

Parameter	Type	Description
$needle	string
$haystack	array
$key	string

---

getTableDiffs

private getTableDiffs(array $new, array $old): array

Parameters:

Parameter	Type	Description
$new	array
$old	array

---

processContent

private processContent(int $version, string $type, string[]& $item): void

Parameters:

Parameter	Type	Description
$version	int
$type	string
$item	string[]

---

replay

Reply a database migration schema file.

private replay(array $schema, bool $test = false, string[]& $globalVars = null, ?int $version = null): bool

This should only be used internally by the migrate method to replay an individual schema migration file.

Parameters:

Parameter	Type	Description
$schema	array	The JSON decoded schema to replay
$test	bool
$globalVars	string[]
$version	?int

---

replayItems

private replayItems(string $type, string $action, array $items, bool $test = false, bool $primaryKeysFirst = true, ?int $version = null): bool

Parameters:

Parameter	Type	Description
$type	string
$action	string
$items	array
$test	bool
$primaryKeysFirst	bool
$version	?int

---

loadDataFromFile

private loadDataFromFile(array& $dataSchema, \Hazaar\File|string $file, ?string $childElement = null): void

Parameters:

Parameter	Type	Description
$dataSchema	array
$file	\Hazaar\File|string
$childElement	?string

---

processMacro

private processMacro(string $field): array|false

Parameters:

Parameter	Type	Description
$field	string

---

prepareRow

private prepareRow(\stdClass& $row, \stdClass[]& $records = [], ?\stdClass $refs = null, ?\stdClass $vars = null): \stdClass

Parameters:

Parameter	Type	Description
$row	\stdClass
$records	\stdClass[]
$refs	?\stdClass
$vars	?\stdClass

---

processDataObject

private processDataObject(\stdClass $info, array& $records = null, ?\stdClass& $globalVars = null): bool

Parameters:

Parameter	Type	Description
$info	\stdClass
$records	array
$globalVars	?\stdClass

---

fixRow

Quick closure function to fix up the row ready for insert/update.

private fixRow(array& $row, mixed $tableDef): array

Parameters:

Parameter	Type	Description
$row	array
$tableDef	mixed

---

log

Logs a message to the migration log.

private log(string $msg): void

Parameters:

Parameter	Type	Description
$msg	string	The message to log

---

initDBIFilesystem

private initDBIFilesystem(): bool

---

---

Automatically generated on 2024-11-14