Upgrade from 1.x

Upgrade from 1.x

Barbarian 2.0 is a modernisation and bug-fix release that contains breaking changes. This page summarises what changed and how to adapt.

At a glance

Area	1.x	2.0
Minimum PHP	7.4	8.1
initphp/console	^1.0	^2.1
CLI flags	-version=	--version=
json command	json	init
Migrations & query gateway	one class	separate QueryRunner
getError()	array	renamed getErrors()
QueryInterface::query()	false|PDOStatement	PDOStatement, throws

Requirements

• Upgrade to PHP 8.1+.
• composer require initphp/barbarian:^2.0 — this also pulls in initphp/console:^2.1.

Breaking changes and how to adapt

getError() → getErrors()

- foreach ($migrations->getError() as $error) { ... }
+ foreach ($migrations->getErrors() as $error) { ... }

Migrations receive a QueryRunner, not the manager

Migrations no longer implements QueryInterface. The object passed to your up()/down() is now a QueryRunner (still a QueryInterface). If you only ever called $query->query(...), no change is needed. If you relied on the manager being passed in, update accordingly.

query() throws instead of returning false

The connection runs in PDO::ERRMODE_EXCEPTION mode and query() returns a PDOStatement, throwing \PDOException on failure. Remove any === false checks:

- $stmt = $query->query($sql);
- if ($stmt === false) { /* handle */ }
+ $stmt = $query->query($sql); // throws on failure

CLI flag syntax

Use double-dash arguments:

- vendor/bin/barbarian up -version=20221230091500
+ vendor/bin/barbarian up --version=20221230091500

The json command is now init

- vendor/bin/barbarian json
+ vendor/bin/barbarian init

init also creates the migrations/ folder referenced by the generated config.

Bugs fixed in 2.0

If any of these bit you in 1.x, they are now resolved (and covered by tests):

• Namespaced migrations are discovered. The namespace option previously had no effect.
• down actually runs. The status comparison no longer breaks under drivers that return the column as a string (e.g. MySQL).
• Selecting a migration by full class name no longer crashes the CLI.
• PostgreSQL works. The version table DDL is valid (SERIAL primary key).
• table_name in barbarian.json is honoured.
• up()/down() return values are honoured — returning false no longer records a state change.
• Bulk down runs in reverse order.
• create no longer needs a database connection.
• Invalid barbarian.json is reported instead of slipping through.

New in 2.0

• A status command, plus Migrations::status() and getStatuses().
• A force argument on downMigration() (symmetric with upMigration()).
• Read accessors: getFolder(), getNamespace(), getMigrationTable().
• A reusable console layer: Config, ConfigLoader, ManagerFactory, MigrationTemplate.

See also

• CLI Commands
• Programmatic Usage
• API Reference