Download the PHP package woodholly/atk4-migrations without Composer

ATK4 Migrations

Database migrations for ATK4 Data using Doctrine Migrations.

Table of Contents

• Overview
• Features
• Installation
• Indexes and Foreign Keys
• Quick Start
• Available Commands
• Table Renaming
• Fixing Mistakes
• Advanced
• Configuration
• Requirements
• Testing

Overview

Automatic database migrations for ATK4 Data using Doctrine Migrations. Define your schema in ATK4 Models, generate migrations automatically.

Works with any database state: Empty, existing, or production databases. The tool compares your models with the current database and generates only the necessary changes (CREATE, ALTER, or nothing if already in sync).

Features

• Automatic Schema Detection - Compares models with database, generates only necessary changes
• Full Rollback Support - Reverse any migration
• Zero Schema Duplication - Schema defined once in ATK4 Models
• Production Ready - Built on Doctrine Migrations
• Multi-Database - MySQL, PostgreSQL, SQLite, Oracle, SQL Server
• Declarative Constraints - Define indexes and foreign keys in models (extended Model class)

Installation

Indexes and Foreign Keys

ATK4 Data lacks declarative index/FK support. This package provides Atk4\Migrations\Model - an extended Model class that adds:

• Field options: 'index' => true, 'unique' => true in addField()
• Relationship options: 'onDelete', 'onUpdate', 'index', 'unique' in hasOne()
• Methods: addIndex(), addForeignKey(), getIndexes(), getForeignKeys()

Usage: Replace use Atk4\Data\Model → use Atk4\Migrations\Model

Note: Standard Atk4\Data\Model works with migrations, but requires manual index/FK editing in each migration file. Atk4\Migrations\Model defines constraints declaratively. We hope this will be added to ATK4 Data core eventually.

Example:

Quick Start

1. Create Configuration

Create migrations.php in project root (or config/migrations.php for better organization):

2. Generate & Run Migrations

Use --configuration=config/migrations.php if config not in project root.

Available Commands

Note on dump-schema: This command dumps the current database schema (based on your models) to a SQL file. Useful for debugging schema differences or generating a full schema snapshot. The migrations directory should be empty or the schema reflects what would be created.

Table Renaming

Schema diff tools cannot distinguish table renames from drop+create operations. Changing public $table = 'old_name' to public $table = 'new_name' generates DROP + CREATE, deleting all data.

Workflow:

Renaming + modifying fields: Either create two separate migrations (rename first, then modify), or manually edit the migration to rename then ALTER using the new table name.

Fixing Mistakes

Migration not executed yet? Just delete the file:

Migration already executed? Use version command to unmark it:

Note: Use --delete when the migration didn't actually change anything or when you've manually reverted the changes. Use migrate prev when you want to actually reverse the database changes.

Wrong model definition? Fix the model and generate a new corrective migration:

Advanced

Manual Migration Editing

For advanced cases, manually edit generated migration files using Doctrine's Schema API. See Doctrine Migrations documentation for available methods.

Auto-Discovery

You can automatically discover models from a directory instead of listing them manually:

This auto-discovery approach requires files in src/Model/*.php with class names matching filenames.

Configuration

All available options:

Understanding table_storage

The table_storage option configures where Doctrine Migrations tracks migration execution history:

What it does:

• Creates a table in your database (default: doctrine_migration_versions)
• Stores a record each time a migration is executed
• Allows the system to know which migrations have already been applied

Example table contents:

When to customize:

• If you already have a table named doctrine_migration_versions (avoid conflicts)
• If your project has naming conventions for system tables
• If you're integrating with an existing migration system

Default values are fine for most projects - you only need to specify table_storage if you want to change the defaults.

How It Works

The package extracts Doctrine Table objects from ATK4's Migrator class (which already builds them internally), then uses Doctrine's built-in schema comparison to generate migrations.

Requirements

• PHP 7.4 or higher
• atk4/data ^6.0
• doctrine/migrations ^3.5
• symfony/console ^5.0 || ^6.0 || ^7.0

Testing

License

MIT

Credits

Built on top of:

• ATK4 Data
• Doctrine Migrations