Home

InitPHP Barbarian — Wiki

Welcome to the official documentation for initphp/barbarian — a small, dependency-light database migration library for PHP. It discovers your migration classes on disk, keeps a version table in sync, and runs the up()/down() side of each migration either from your own code or through a simple command-line interface.

composer require initphp/barbarian

<?php

declare(strict_types=1);

namespace App\Migrations;

use InitPHP\Barbarian\MigrationAbstract;
use InitPHP\Barbarian\QueryInterface;

final class Migration_20240101000000 extends MigrationAbstract
{
    public function up(QueryInterface $query): bool
    {
        $query->query('CREATE TABLE IF NOT EXISTS `users` (
            `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
            `name` VARCHAR(255) NOT NULL,
            PRIMARY KEY (`id`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;');

        return true;
    }

    public function down(QueryInterface $query): bool
    {
        $query->query('DROP TABLE IF EXISTS `users`');

        return true;
    }
}

vendor/bin/barbarian status   # up / down / pending for every migration
vendor/bin/barbarian up       # apply all migrations
vendor/bin/barbarian down     # revert all migrations (reverse order)

The building blocks

Type	Purpose
Migrations	Discovers migrations, keeps the version table in sync, runs up()/down().
MigrationInterface	The contract every migration fulfils.
MigrationAbstract	Base class implementing getName() for you.
QueryInterface	The query gateway handed to each migration.
QueryRunner	Default QueryInterface: a thin PDO wrapper.
MigrationStatus	Enum: Down = 0, Up = 1.
Schema\Grammar	Driver-specific version table DDL and identifier quoting.
MigrationException	Raised for failures in Barbarian itself.
Console\*	Configuration loading, the manager factory and the CLI commands.

Start here

• New to the package? Read Installation, then Quick Start.
• Writing migrations? See Writing Migrations.
• Configuring it? See Configuration for both the Migrations options and barbarian.json.
• Using the CLI? See CLI Commands.
• Driving it from code? See Programmatic Usage.
• Targeting a specific database? See Database Drivers.
• Looking for a specific method? The full API Reference lists every class member.
• Coming from 1.x? Read Upgrade from 1.x.

Core concepts

Term	Meaning
Migration	A class implementing MigrationInterface (usually via MigrationAbstract) with up() and down().
Version name	The unqualified class name (e.g. Migration_20240101000000); the unique key in the version table.
Version table	A table (default migrations_versions) recording each migration's status and last change time.
Manager	Migrations — discovers migrations, ensures the version table and runs migrations.
Query gateway	QueryInterface (implemented by QueryRunner) — the object passed to every up()/down().

Package metadata

• License: MIT
• Minimum PHP: 8.1 (CI matrix runs 8.1 – 8.4)
• Runtime dependencies: initphp/console ^2.1
• Required extensions: ext-pdo, ext-json (plus the PDO driver for your database)
• Supported databases: MySQL/MariaDB, SQLite, PostgreSQL
• Packagist: initphp/barbarian
• Source: github.com/InitPHP/Barbarian
• Issues: github.com/InitPHP/Barbarian/issues
• Discussions: github.com/orgs/InitPHP/discussions
• Security: SECURITY.md

If something in this wiki is unclear, ambiguous, or wrong, please open an issue — documentation fixes are reviewed eagerly.