### Install SQL Formatter

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Install the required package to enable formatted SQL output.

```sh
$ composer require doctrine/sql-formatter
```

--------------------------------

### Create database via command line

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Use mysqladmin to create the required database for the migrations example.

```sh
$ mysqladmin create migrations_docs_example
```

--------------------------------

### Install YAML support

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Required dependency installation for using YAML configuration files.

```sh
composer require symfony/yaml
```

--------------------------------

### Configure Doctrine Migrations

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Configuration examples for defining storage, paths, and execution behavior in various formats.

```php
<?php

return [
    'table_storage' => [
        'table_name' => 'doctrine_migration_versions',
        'version_column_name' => 'version',
        'version_column_length' => 191,
        'executed_at_column_name' => 'executed_at',
        'execution_time_column_name' => 'execution_time',
    ],

    'migrations_paths' => [
        'MyProject\Migrations' => '/data/doctrine/migrations/lib/MyProject/Migrations',
        'MyProject\Component\Migrations' => './Component/MyProject/Migrations',
    ],

    'all_or_nothing' => true,
    'transactional' => true,
    'check_database_platform' => true,
    'organize_migrations' => 'none',
    'connection' => null,
    'em' => null,
];
```

```yaml
table_storage:
   table_name: doctrine_migration_versions
   version_column_name: version
   version_column_length: 191
   executed_at_column_name: executed_at
   execution_time_column_name: execution_time

migrations_paths:
   'MyProject\Migrations': /data/doctrine/migrations/lib/MyProject/Migrations
   'MyProject\Component\Migrations': ./Component/MyProject/Migrations

all_or_nothing: true
transactional: true
check_database_platform: true
organize_migrations: none

connection: null
em: null
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<doctrine-migrations xmlns="http://doctrine-project.org/schemas/migrations/configuration/3.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/migrations/configuration/3.0
                    http://doctrine-project.org/schemas/migrations/configuration-3.0.xsd">

    <connection>default</connection>
    <em>default</em>

    <storage>
        <table-storage
                table-name="doctrine_migration_versions"
                version-column-name="version"
                version-column-length="191"
                executed-at-column-name="executed_at"
                executed-time-column-name="execution_time"
        />
    </storage>
    <migrations-paths>
        <path namespace="MyProject\Migrations">/data/doctrine/migrations/lib/MyProject/Migrations</path>
        <path namespace="MyProject\Component\Migrations">./Component/MyProject/Migrations</path>
    </migrations-paths>

    <all-or-nothing>true</all-or-nothing>
    <transactional>true</transactional>

    <check-database-platform>true</check-database-platform>
    <organize_migrations>none</organize_migrations>
</doctrine-migrations>
```

```json
{
    "table_storage": {
       "table_name": "doctrine_migration_versions",
       "version_column_name": "version",
       "version_column_length": 191,
       "executed_at_column_name": "executed_at",
       "execution_time_column_name": "execution_time"
    },

    "migrations_paths": {
       "MyProject\\Migrations": "/data/doctrine/migrations/lib/MyProject/Migrations",
       "MyProject\\Component\\Migrations": "./Component/MyProject/Migrations"
    },

    "all_or_nothing": true,
    "transactional": true,
    "check_database_platform": true,
    "organize_migrations": "none",

    "connection": null,
    "em": null
}
```

--------------------------------

### Install Doctrine ORM

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Install the Doctrine ORM package via Composer.

```sh
composer require doctrine/orm
```

--------------------------------

### Install via Composer

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Add the doctrine/migrations package to the project dependencies.

```sh
composer require "doctrine/migrations"
```

--------------------------------

### Generated migration class

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Example of an auto-generated migration class containing up and down methods.

```php
<?php

declare(strict_types=1);

namespace MyProject\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * Auto-generated Migration: Please modify to your needs!
 */
final class Version20180601215504 extends AbstractMigration
{
    public function getDescription(): string
    {
        return '';
    }

    public function up(Schema $schema): void
    {
        // this up() migration is auto-generated, please modify it to your needs
        $this->abortIf($this->connection->getDatabasePlatform()->getName() !== 'mysql', 'Migration can only be executed safely on \'mysql\'.');

        $this->addSql('CREATE TABLE users (id INT AUTO_INCREMENT NOT NULL, username VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci ENGINE = InnoDB');
        $this->addSql('DROP TABLE example_table');
    }

    public function down(Schema $schema): void
    {
        // this down() migration is auto-generated, please modify it to your needs
        $this->abortIf($this->connection->getDatabasePlatform()->getName() !== 'mysql', 'Migration can only be executed safely on \'mysql\'.');

        $this->addSql('CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL COLLATE latin1_swedish_ci, PRIMARY KEY(id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci ENGINE = InnoDB');
        $this->addSql('DROP TABLE users');
    }
}
```

--------------------------------

### Define Migration Class

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Example of a migration class implementing the up and down methods to modify the database schema.

```php
<?php

declare(strict_types=1);

namespace MyProject\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * Auto-generated Migration: Please modify to your needs!
 */
final class Version20180601193057 extends AbstractMigration
{
    public function getDescription(): string
    {
        return 'This is my example migration.';
    }

    public function up(Schema $schema): void
    {
        $this->addSql('CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))');
    }

    public function down(Schema $schema): void
    {
        $this->addSql('DROP TABLE example_table');
    }
}
```

--------------------------------

### Migration with DDL and DML statements

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/explanation/implicit-commits.rst

An example of a migration that mixes DML updates with a DDL CREATE TABLE statement, which can trigger implicit commit errors on certain platforms.

```php
public function up(Schema $schema): void
{
    $users = [
        ['name' => 'mike', 'id' => 1],
        ['name' => 'jwage', 'id' => 2],
        ['name' => 'ocramius', 'id' => 3],
    ];

    foreach ($users as $user) {
        $this->addSql('UPDATE user SET happy = true WHERE name = :name AND id = :id', $user);
    }

    $this->addSql('CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))');
}
```

--------------------------------

### Initialize project directory

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Create and enter a new directory for the migration project.

```sh
$ mkdir /data/doctrine/migrations-docs-example
$ cd /data/doctrine/migrations-docs-example
```

--------------------------------

### Manually building a custom configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-configuration.rst

Use this approach to define migration directories and metadata storage programmatically instead of using configuration files.

```php
#!/usr/bin/env php
<?php

require_once __DIR__.'/vendor/autoload.php';

use Doctrine\
DBAL\\DriverManager;
use Doctrine\\Migrations\\Configuration\\Configuration;
use Doctrine\\Migrations\\Configuration\\Connection\\ExistingConnection;
use Doctrine\\Migrations\\Configuration\\Migration\\ExistingConfiguration;
use Doctrine\\Migrations\\DependencyFactory;
use Doctrine\\Migrations\\Metadata\\Storage\\TableMetadataStorageConfiguration;
use Doctrine\\Migrations\\Tools\\Console\\Command;
use Symfony\\Component\\Console\\Application;

$dbParams = [
    'dbname' => 'migrations_docs_example',
    'user' => 'root',
    'password' => '',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
];

$connection = DriverManager::getConnection($dbParams);

$configuration = new Configuration($connection);

$configuration->addMigrationsDirectory('MyProject\\Migrations', '/data/doctrine/migrations-docs-example/lib/MyProject/Migrations');
$configuration->setAllOrNothing(true);
$configuration->setCheckDatabasePlatform(false);

$storageConfiguration = new TableMetadataStorageConfiguration();
$storageConfiguration->setTableName('doctrine_migration_versions');

$configuration->setMetadataStorageConfiguration($storageConfiguration);

$dependencyFactory = DependencyFactory::fromConnection(
    new ExistingConfiguration($configuration),
    new ExistingConnection($connection)
);

$cli = new Application('Doctrine Migrations');
$cli->setCatchExceptions(true);

$cli->addCommands(array(
    new Command\\CurrentCommand($dependencyFactory),
    new Command\\DiffCommand($dependencyFactory),
    new Command\\DumpSchemaCommand($dependencyFactory),
    new Command\\ExecuteCommand($dependencyFactory),
    new Command\\GenerateCommand($dependencyFactory),
    new Command\\LatestCommand($dependencyFactory),
    new Command\\ListCommand($dependencyFactory),
    new Command\\MigrateCommand($dependencyFactory),
    new Command\\RollupCommand($dependencyFactory),
    new Command\\StatusCommand($dependencyFactory),
    new Command\\SyncMetadataCommand($dependencyFactory),
    new Command\\UpToDateCommand($dependencyFactory),
    new Command\\VersionCommand($dependencyFactory),
));

$cli->run();
```

--------------------------------

### Provide a migration description

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Override getDescription to return a string that will be displayed when running the status command.

```php
public function getDescription(): string
{
    return 'The description of my awesome migration!';
}
```

--------------------------------

### Simple Connection Configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Define database connection parameters in a migrations-db.php file for the console application.

```php
<?php
```

--------------------------------

### Execute migration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Run the migrate command to apply pending migrations.

```sh
$ ./vendor/bin/doctrine-migrations migrate

                    My Project Migrations


WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n)y
Migrating up to MyProject\Migrations\Version20180601215504 from MyProject\Migrations\Version20180601193057

  ++ migrating MyProject\Migrations\Version20180601215504
```

--------------------------------

### Execute migrations console application

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Run the migrations console application from the vendor directory.

```sh
./vendor/bin/doctrine-migrations
```

--------------------------------

### Demonstrate correct sorting with zero-padded version numbers

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/version-numbers.rst

Shows how padding custom version numbers to 14 characters ensures they sort correctly alongside generated versions.

```php
<?php

$versions = [
    'Version00000000000001',
    'Version00000000000002',
    // ...
    'Version00000000000010',
    'Version20180107070000', // generated version
];

sort($versions, SORT_STRING);

var_dump($versions);
/*
array(4) {
  [0] =>
  string(21) "Version00000000000001"
  [1] =>
  string(21) "Version00000000000002"
  [2] =>
  string(21) "Version00000000000010"
  [3] =>
  string(21) "Version20180107070000"
}
*/
```

--------------------------------

### Configure DependencyFactory with existing connection

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Use cli-config.php to return a DependencyFactory instance when not using the ORM.

```php
<?php

require 'vendor/autoload.php';

use Doctrine\DBAL\DriverManager;
use Doctrine\Migrations\Configuration\Connection\ExistingConnection;
use Doctrine\Migrations\Configuration\Migration\PhpFile;
use Doctrine\Migrations\DependencyFactory;

$config = new PhpFile('migrations.php'); // Or use one of the Doctrine\Migrations\Configuration\Configuration\* loaders

$conn = DriverManager::getConnection(['driver' => 'pdo_sqlite', 'memory' => true]);

return DependencyFactory::fromConnection($config, new ExistingConnection($conn));
```

--------------------------------

### Execute SQL with addSql

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use addSql to queue SQL queries for execution, supporting prepared statements by passing parameters as the second argument.

```php
public function up(Schema $schema): void
{
    $users = [
        ['name' => 'mike', 'id' => 1],
        ['name' => 'jwage', 'id' => 2],
        ['name' => 'ocramius', 'id' => 3],
    ];

    foreach ($users as $user) {
        $this->addSql('UPDATE user SET happy = true WHERE name = :name AND id = :id', $user);
    }
}
```

--------------------------------

### Update migrations.php configuration

Source: https://github.com/doctrine/migrations/blob/3.9.x/UPGRADE.md

Shows the transition from the legacy flat configuration structure to the new nested table_storage and migrations_paths format.

```php
<?php

return [
    'name' => 'My Project Migrations',
    'migrations_namespace' => 'MyProject\Migrations',
    'table_name' => 'doctrine_migration_versions',
    'column_name' => 'version',
    'column_length' => 14,
    'executed_at_column_name' => 'executed_at',
    'migrations_directory' => '/data/doctrine/migrations-docs-example/lib/MyProject/Migrations',
    'all_or_nothing' => true,
    'check_database_platform' => true,
];
```

```php
<?php

return [

    'table_storage' => [
        'table_name' => 'doctrine_migration_versions',
        'version_column_name' => 'version',
        'version_column_length' => 191,
        'executed_at_column_name' => 'executed_at',
        'execution_time_column_name' => 'execution_time',
    ],

    'migrations_paths' => [
        'MyProject\Migrations' => '/data/doctrine/migrations/lib/MyProject/Migrations',
        'MyProject\Component\Migrations' => './Component/MyProject/Migrations',
    ],

    'all_or_nothing' => true,
    'check_database_platform' => true,
];
```

--------------------------------

### Execute custom migrations script

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-integration.rst

Run the newly created custom migrations console application.

```bash
$ ./migrations
```

--------------------------------

### Define a custom migration template

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-configuration.rst

Create a PHP template file using placeholders like <namespace>, <className>, and <up> to define the structure of generated migrations.

```php
<?php

declare(strict_types=1);

namespace <namespace>;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

final class <className> extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        <up>
    }
}
```

--------------------------------

### Export Migration SQL to a File

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Use the --write-sql option to generate a file containing the SQL statements that would be executed during a migration.

```sh
$ ./vendor/bin/doctrine-migrations migrate --write-sql
```

```sh
$ cat doctrine_migration_20180601172528.sql
-- Doctrine Migration File Generated on 2018-06-01 17:25:28

-- Version MyProject\Migrations\Version20180601193057
CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id));
INSERT INTO doctrine_migration_versions (version, executed_at) VALUES ('MyProject\Migrations\Version20180601193057', CURRENT_TIMESTAMP);
```

```sh
$ ./vendor/bin/doctrine-migrations migrate --write-sql=migration.sql
```

```sh
$ ./vendor/bin/doctrine-migrations migrate --write-sql=/path/to/migration.sql
```

```sh
$ ./vendor/bin/doctrine-migrations migrate --write-sql=/path/to/directory
```

--------------------------------

### Execute Migrations Using Version Aliases

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Use aliases like 'latest' or 'first' to navigate migration versions without specifying exact version numbers.

```bash
$ ./vendor/bin/doctrine-migrations migrate latest
$ ./vendor/bin/doctrine-migrations migrate first
```

--------------------------------

### Create migrations directory

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Command to create the directory structure for storing migration files.

```sh
$ mkdir -p lib/MyProject/Migrations
```

--------------------------------

### Execute PHAR application

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Run the downloaded PHAR file using the PHP interpreter.

```sh
php doctrine-migrations.phar
```

--------------------------------

### Create entity directory

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Create the directory structure for ORM entities.

```sh
$ mkdir lib/MyProject/Entities
```

--------------------------------

### Configuring multiple connections with a registry

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-configuration.rst

Implement a custom manager registry to support multiple database connections, allowing the use of the --conn parameter in CLI commands.

```php
#!/usr/bin/env php
<?php

require_once __DIR__.'/vendor/autoload.php';

use Doctrine\\DBAL\\DriverManager;
use Doctrine\\Migrations\\Configuration\\Configuration;
use Doctrine\\Migrations\\Configuration\\Configuration\\ExistingConfiguration;
use Doctrine\\Migrations\\Configuration\\Connection\\ConnectionRegistryConnection;
use Doctrine\\Migrations\\DependencyFactory;
use Doctrine\\Migrations\\Tools\\Console\\Command;
use Symfony\\Component\\Console\\Application;

$connection1 = DriverManager::getConnection([...]);
$connection2 = DriverManager::getConnection([...]);

$connectionRegistry = new class(
    'some_registry',
    ['foo' => $connection1, 'bar' => $connection2],
    [], // entity managers
    'foo', // default connection
    null, // default entity manager
    'Doctrine\\Persistence\\Proxy' // proxy class
) extends AbstractManagerRegistry {
    // implement abstract methods here
};

$configuration = new Configuration($connection);
$configuration->addMigrationsDirectory('MyProject\\Migrations', 'some path');
$configurationLoader = new ExistingConfiguration($configuration);

$connectionLoader = ConnectionRegistryConnection::withSimpleDefault($connectionRegistry);

$dependencyFactory = DependencyFactory::fromConnection(
    $configurationLoader,
    $connectionLoader
);

$cli = new Application('Doctrine Migrations');
$cli->setCatchExceptions(true);

$cli->addCommands(array(
    new Command\\MigrateCommand($dependencyFactory),
    // more commands here
));

$cli->run();
```

--------------------------------

### Implement CustomSchemaProvider

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Create a custom schema provider by implementing the SchemaProviderInterface to define the target database state.

```php
<?php

use Doctrine\\DBAL\\Schema\\Schema;
use Doctrine\\Migrations\\Provider\\SchemaProviderInterface;

final class CustomSchemaProvider implements SchemaProviderInterface
{
    public function createSchema()
    {
        $schema = new Schema();

        $table = $schema->createTable('users');

        $table->addColumn('id', 'integer', [
            'autoincrement' => true,
        ]);

        $table->addColumn('username', 'string', [
            'notnull' => false,
        ]);

        $table->setPrimaryKey(array('id'));

        return $schema;
    }
}
```

--------------------------------

### Demonstrate sorting issues with non-padded version numbers

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/version-numbers.rst

Shows how standard string sorting causes 'Version10' to appear before 'Version2'.

```php
<?php

$versions = [
    'Version1',
    'Version2',
    // ...
    'Version10',
];

sort($versions, SORT_STRING);

var_dump($versions);

/*
array(3) {
  [0] =>
  string(8) "Version1"
  [1] =>
  string(9) "Version10"
  [2] =>
  string(8) "Version2"
}
*/
```

--------------------------------

### Diff and execute migrations

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Commands to generate a migration based on schema changes and manage execution.

```sh
$ ./vendor/bin/doctrine-migrations diff
Generated new migration class to "/data/doctrine/migrations-docs-example/lib/MyProject/Migrations/Version20180601215504.php"

To run just this migration for testing purposes, you can use migrations:execute --up 'MyProject\Migrations\Version20180601215504'

To revert the migration you can use migrations:execute --down 'MyProject\Migrations\Version20180601215504'
```

--------------------------------

### Implementing a Migrations Event Subscriber

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/events.rst

Create a class implementing EventSubscriber to listen for specific migration lifecycle events.

```php
<?php

use Doctrine\Common\EventSubscriber;
use Doctrine\Migrations\Event\MigrationsEventArgs;
use Doctrine\Migrations\Event\MigrationsVersionEventArgs;
use Doctrine\Migrations\Events;

class MigrationsListener implements EventSubscriber
{
    public function getSubscribedEvents(): array
    {
        return [
            Events::onMigrationsMigrating,
            Events::onMigrationsMigrated,
            Events::onMigrationsVersionExecuting,
            Events::onMigrationsVersionExecuted,
            Events::onMigrationsVersionSkipped,
        ];
    }

    public function onMigrationsMigrating(MigrationsEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsMigrated(MigrationsEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionExecuting(MigrationsVersionEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionExecuted(MigrationsVersionEventArgs $args): void
    {
        // ...
    }

    public function onMigrationsVersionSkipped(MigrationsVersionEventArgs $args): void
    {
        // ...
    }
}
```

--------------------------------

### Define database connection parameters

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Return an array of database connection parameters in migrations-db.php.

```php
return [
    'dbname' => 'migrations_docs_example',
    'user' => 'root',
    'password' => '',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
];
```

--------------------------------

### Generate a blank migration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Use the generate command to create an empty migration file.

```sh
$ ./vendor/bin/doctrine-migrations generate
```

--------------------------------

### Perform Migration Dry Run

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Simulates the migration process to verify the generated SQL without applying changes to the database.

```sh
$ ./vendor/bin/doctrine-migrations migrate --dry-run
```

--------------------------------

### Use StubSchemaProvider

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Utilize the built-in StubSchemaProvider to return a pre-defined schema object.

```php
<?php

use Doctrine\\DBAL\\Schema\\Schema;
use Doctrine\\Migrations\\Provider\\StubSchemaProvider;

$schema = new Schema();

$table = $schema->createTable('users');

$table->addColumn('id', 'integer', [
    'autoincrement' => true,
        ]);

$table->addColumn('username', 'string', [
    'notnull' => false,
        ]);

$table->setPrimaryKey(array('id'));

$provider = new StubSchemaProvider($schema);
$provider->createSchema() === $schema; // true
```

--------------------------------

### Generate and execute migrations via CLI

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Commands to generate a new migration class and execute it in either the up or down direction.

```sh
$ ./vendor/bin/doctrine-migrations generate
Generated new migration class to "/data/doctrine/migrations-docs-example/lib/MyProject/Migrations/Version20180601193057.php"

To run just this migration for testing purposes, you can use migrations:execute --up 'MyProject\Migrations\Version20180601193057'

To revert the migration you can use migrations:execute --down 'MyProject\Migrations\Version20180601193057'
```

--------------------------------

### Blank migration class structure

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

The default template for a migration class extending AbstractMigration.

```php
<?php

declare(strict_types=1);

namespace MyProject\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * Auto-generated Migration: Please modify to your needs!
 */
final class Version20180601193057 extends AbstractMigration
{
    public function getDescription(): string
    {
        return '';
    }

    public function up(Schema $schema): void
    {
        // this up() migration is auto-generated, please modify it to your needs

    }

    public function down(Schema $schema): void
    {
        // this down() migration is auto-generated, please modify it to your needs

    }
}
```

--------------------------------

### Custom migrations script implementation

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-integration.rst

PHP script to initialize the Doctrine Migrations console application with a custom connection and configuration.

```php
#!/usr/bin/env php
<?php

require_once __DIR__.'/vendor/autoload.php';

use Doctrine\DBAL\DriverManager;
use Doctrine\Migrations\DependencyFactory;
use Doctrine\Migrations\Configuration\Migration\PhpFile;
use Doctrine\Migrations\Configuration\Connection\ExistingConnection;
use Doctrine\Migrations\Tools\Console\Command;
use Symfony\Component\Console\Application;

$dbParams = [
    'dbname' => 'migrations_docs_example',
    'user' => 'root',
    'password' => '',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
];

$connection = DriverManager::getConnection($dbParams);

$config = new PhpFile('migrations.php'); // Or use one of the Doctrine\Migrations\Configuration\Configuration\* loaders

$dependencyFactory = DependencyFactory::fromConnection($config, new ExistingConnection($connection));

$cli = new Application('Doctrine Migrations');
$cli->setCatchExceptions(true);

$cli->addCommands(array(
    new Command\DumpSchemaCommand($dependencyFactory),
    new Command\ExecuteCommand($dependencyFactory),
    new Command\GenerateCommand($dependencyFactory),
    new Command\LatestCommand($dependencyFactory),
    new Command\ListCommand($dependencyFactory),
    new Command\MigrateCommand($dependencyFactory),
    new Command\RollupCommand($dependencyFactory),
    new Command\StatusCommand($dependencyFactory),
    new Command\SyncMetadataCommand($dependencyFactory),
    new Command\VersionCommand($dependencyFactory),
));

$cli->run();
```

--------------------------------

### Download PHAR release

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/introduction.rst

Download a specific version of the migrations PHAR file.

```sh
wget https://github.com/doctrine/migrations/releases/download/v2.0.0/doctrine-migrations.phar
```

--------------------------------

### Return existing DBAL connection

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Return a pre-configured DBAL connection instance from migrations-db.php.

```php
<?php
use Doctrine\DBAL\DriverManager;

return DriverManager::getConnection([
    'dbname' => 'migrations_docs_example',
    'user' => 'root',
    'password' => '',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
]);
```

--------------------------------

### Execute Migrations

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Applies pending migrations to the database. This command will execute all available unexecuted versions sequentially.

```sh
$ ./vendor/bin/doctrine-migrations migrate
```

--------------------------------

### Migration lifecycle hooks

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Implement these methods to execute logic before or after the up or down migration steps.

```php
public function preUp(Schema $schema): void
{
}
```

```php
public function postUp(Schema $schema): void
{
}
```

```php
public function preDown(Schema $schema): void
{
}
```

```php
public function postDown(Schema $schema): void
{
}
```

--------------------------------

### Check migration status

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Display the current migration configuration and version history.

```sh
$ ./vendor/bin/doctrine-migrations status --show-versions

 == Configuration

    >> Name:                                               My Project Migrations
    >> Database Driver:                                    pdo_mysql
    >> Database Host:                                      localhost
    >> Database Name:                                      migrations_docs_example
    >> Configuration Source:                               /data/doctrine/migrations-docs-example/migrations.php
    >> Version Table Name:                                 doctrine_migration_versions
    >> Version Column Name:                                version
    >> Migrations Namespace:                               MyProject\Migrations
    >> Migrations Directory:                               /data/doctrine/migrations-docs-example/lib/MyProject/Migrations
    >> Previous Version:                                   0
    >> Current Version:                                    2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
    >> Next Version:                                       Already at latest version
    >> Latest Version:                                     2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)
    >> Executed Migrations:                                1
    >> Executed Unavailable Migrations:                    0
    >> Available Migrations:                               1
    >> New Migrations:                                     0

 == Available Migration Versions

    >> 2018-06-01 19:30:57 (MyProject\Migrations\Version20180601193057)                migrated (executed at 2018-06-01 17:08:44)     This is my example migration.
```

--------------------------------

### Execute a single migration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Run a specific migration up or down using the execute command. Requires the migration version class name.

```sh
$ ./vendor/bin/doctrine-migrations execute MyProject\Migrations\Version20180601193057 --down
WARNING! You are about to execute a database migration that could result in schema changes and data lost. Are you sure you wish to continue? (y/n)y

  ++ migrating MyProject\Migrations\Version20180601193057

     -> DROP TABLE example_table

  ++ migrated (took 42.6ms, used 8M memory)
```

--------------------------------

### Make migrations script executable

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-integration.rst

Set the execution permission for the custom migrations file.

```bash
$ chmod +x migrations
```

--------------------------------

### Write debug information

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use the write method to output custom messages to the console during migration execution.

```php
public function up(Schema $schema): void
{
    $this->write('Doing some cool migration!');

    // ...
}
```

--------------------------------

### Rollback to the first version

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Use the first alias with the migrate command to revert all migrations.

```sh
$ ./vendor/bin/doctrine-migrations migrate first

                    My Project Migrations


WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n)y
Migrating down to 0 from MyProject\Migrations\Version20180601193057

  -- reverting MyProject\Migrations\Version20180601193057

     -> DROP TABLE example_table

  -- reverted (took 38.4ms, used 8M memory)

  ------------------------

  ++ finished in 39.5ms
  ++ used 8M memory
  ++ 1 migrations executed
  ++ 1 sql queries
```

--------------------------------

### Configure DependencyFactory with EntityManager

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Use cli-config.php to return a DependencyFactory instance when using the Doctrine ORM.

```php
<?php

require 'vendor/autoload.php';

use Doctrine\ORM\EntityManager;
use Doctrine\ORM\ORMSetup;
use Doctrine\Migrations\Configuration\EntityManager\ExistingEntityManager;
use Doctrine\Migrations\DependencyFactory;
use Doctrine\Migrations\Configuration\Migration\PhpFile;
use Doctrine\DBAL\DriverManager;

$config = new PhpFile('migrations.php'); // Or use one of the Doctrine\Migrations\Configuration\Configuration\* loaders

$paths = [__DIR__.'/lib/MyProject/Entities'];
$isDevMode = true;

$ORMConfig = ORMSetup::createAttributeMetadataConfiguration($paths, $isDevMode);
$connection = DriverManager::getConnection(['driver' => 'pdo_sqlite', 'memory' => true]);

$entityManager = new EntityManager($connection, $ORMConfig);

return DependencyFactory::fromEntityManager($config, new ExistingEntityManager($entityManager));
```

--------------------------------

### Configure the custom migration template

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/custom-configuration.rst

Register the custom template file path using the setCustomTemplate method on the configuration object.

```php
$configuration->setCustomTemplate(__DIR__ . '/custom_template.tpl');
```

--------------------------------

### Check Migration Status

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Displays the current migration state and available versions using the status command.

```sh
$ ./vendor/bin/doctrine-migrations status --show-versions
```

--------------------------------

### Manually Specify Migration Classes

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Explicitly define migration classes in the configuration when automatic discovery is not desired.

```php
<?php

return [
    // ..

    'migrations' => [
        'MyProject\Migrations\NewMigration',
    ],
];
```

```yaml
// ...

migrations:
    - "MyProject\Migrations\NewMigration"
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<doctrine-migrations xmlns="http://doctrine-project.org/schemas/migrations/configuration"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/migrations/configuration
                    http://doctrine-project.org/schemas/migrations/configuration.xsd">

    // ...

    <migrations>
        <migration class="MyProject\Migrations\NewMigration" />
    </migrations>
</doctrine-migrations>
```

```json
{
    // ...

    "migrations": [
        "DoctrineMigrations\NewMigration"
    ]
}
```

--------------------------------

### Define a User entity

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Create a new entity class to be used for schema comparison.

```php
<?php

namespace MyProject\Entities;

use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\GeneratedValue;
use Doctrine\ORM\Mapping\Id;
use Doctrine\ORM\Mapping\Table;

#[Entity]
#[Table(name: 'users')]
class User
{
    #[Id]
    #[Column(type: 'integer')]
    #[GeneratedValue]
    private $id;

    #[Column(type: 'string', nullable: true)]
    private $username;

    public function setId(int $id)
    {
        $this->id = $id;
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function setUsername(string $username): void
    {
        $this->username = $username;
    }

    public function getUsername(): ?string
    {
        return $this->username;
    }
}
```

--------------------------------

### Conditional migration execution

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Use these methods to control migration flow based on specific conditions.

```php
public function up(Schema $schema): void
{
    $this->warnIf(true, 'Something might be going wrong');

    // ...
}
```

```php
public function up(Schema $schema): void
{
    $this->abortIf(true, 'Something went wrong. Aborting.');

    // ...
}
```

```php
public function up(Schema $schema): void
{
    $this->skipIf(true, 'Skipping this migration.');

    // ...
}
```

--------------------------------

### Check status after rollback

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Verify the database state after performing a rollback.

```sh
$ ./vendor/bin/doctrine-migrations status --show-versions

 == Configuration
```

--------------------------------

### Override All or Nothing Transaction via CLI

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/configuration.rst

Use command line flags to enable or disable the all-or-nothing transaction behavior for migrations.

```sh
$ ./vendor/bin/doctrine-migrations migrate --all-or-nothing
```

```sh
$ ./vendor/bin/doctrine-migrations migrate --no-all-or-nothing
```

--------------------------------

### Run migrations in non-interactive mode

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Execute migrations without prompts by adding the --no-interaction flag.

```sh
$ ./vendor/bin/doctrine-migrations migrate --no-interaction

                    My Project Migrations


Migrating up to MyProject\Migrations\Version20180601193057 from 0

  ++ migrating MyProject\Migrations\Version20180601193057

     -> CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))

  ++ migrated (took 46.5ms, used 8M memory)

  ------------------------

  ++ finished in 47.3ms
  ++ used 8M memory
  ++ 1 migrations executed
  ++ 1 sql queries
```

--------------------------------

### Registering an Event Subscriber with the Connection

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/events.rst

Attach the event subscriber to the DBAL connection's event manager during application configuration.

```php
<?php

use Doctrine\DBAL\DriverManager;

$connection = DriverManager::getConnection([
    // ...
]);

$connection->getEventManager()->addEventSubscriber(new MigrationsListener());

// rest of the cli set up...
```

--------------------------------

### Manually Update the Version Table

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Use the version command to manually add or remove migration versions from the tracking table. Exercise caution as this can cause migrations to re-run.

```sh
$ ./vendor/bin/doctrine-migrations version 'MyProject\Migrations\Version20180601193057' --add
```

--------------------------------

### Register DiffCommand Manually

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Manually add the diff command to a console application when not using the ORM.

```php
<?php

use Doctrine\\Migrations\\Tools\\Console\\Command\\DiffCommand;

$schemaProvider = new CustomSchemaProvider();
$dependencyFactory->setDefinition(SchemaProvider::class, static fn () => $schemaProvider);

/** @var Symfony\\Component\\Console\\Application */
$cli->add(new DiffCommand($dependencyFactory);

// ...

$cli->run();
```

--------------------------------

### Splitting migrations to avoid implicit commits

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/explanation/implicit-commits.rst

Recommended approach to separate DML and DDL statements into distinct migrations, with the DDL migration explicitly disabling transactions.

```php
final class Version20210401193057 extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        $users = [
            ['name' => 'mike', 'id' => 1],
            ['name' => 'jwage', 'id' => 2],
            ['name' => 'ocramius', 'id' => 3],
        ];

        foreach ($users as $user) {
            $this->addSql('UPDATE user SET happy = true WHERE name = :name AND id = :id', $user);
        }
    }
}

final class Version20210401193058 extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        $this->addSql('CREATE TABLE example_table (id INT AUTO_INCREMENT NOT NULL, title VARCHAR(255) DEFAULT NULL, PRIMARY KEY(id))');
    }

    public function isTransactional(): bool
    {
        return false;
    }
}
```

--------------------------------

### Handle irreversible migrations

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Call this method within the down method to signal that a migration cannot be reversed.

```php
public function down(Schema $schema): void
{
    $this->throwIrreversibleMigrationException();

    // ...
}
```

--------------------------------

### Configure Schema Filter

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/generating-migrations.rst

Use setSchemaAssetsFilter to ignore specific tables during schema diff operations.

```php
$connection->getConfiguration()->setSchemaAssetsFilter(static function (string|AbstractAsset $assetName): bool {
    if ($assetName instanceof AbstractAsset) {
        $assetName = $assetName->getName();
    }

    return (bool) preg_match("~^(?!t_)~", $assetName);
});
```

--------------------------------

### Delete a migration version

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/managing-migrations.rst

Removes a specific migration version from the tracking table. This does not execute the migration.

```sh
$ ./vendor/bin/doctrine-migrations version 'MyProject\Migrations\Version20180601193057' --delete
```

--------------------------------

### Disable transactions in a migration

Source: https://github.com/doctrine/migrations/blob/3.9.x/docs/en/reference/migration-classes.rst

Override isTransactional to return false if you need to disable automatic transaction wrapping. Note that some databases may implicitly commit transactions when encountering DDL statements.

```php
public function isTransactional(): bool
{
    return false;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.