Getting Started

Minimal Steps

Installation
```
composer require a5sys/doctrine-migration-tools-bundle
```
Ensure DoctrineMigrationsBundle is already installed (this package extends its functionality).
First Use Case Generate a migration from a schema file (e.g., schema.yml or schema.xml) instead of the database:
```
php bin/console doctrine:migrations:diff-file
```
- Outputs a migration file in src/Migrations/ (default) and dumps the current schema to: app/DoctrineMigrations/SchemaVersion/.
Where to Look First
- Command Reference: php bin/console list → Filter for doctrine:migrations:diff-file.
- Configuration: Check config/packages/a5sys_doctrine_migration_tools.yaml (if it exists) for custom paths or defaults.
- Schema File: Ensure your schema file (e.g., config/schema.yml) is up-to-date and matches your intended database structure.

Implementation Patterns

Workflows

Schema-Driven Migrations
- Pre-Migration Workflow:
  1. Update your schema file (e.g., schema.yml) with new tables/columns.
  2. Run doctrine:migrations:diff-file to generate a migration comparing the schema file to the current database state.
  3. Review the generated migration (e.g., YYYYMMDDHHMMSS_UpdateSchema.php) and commit it.
- Post-Migration Workflow: Apply the migration as usual:
```
php bin/console doctrine:migrations:migrate
```
CI/CD Integration
- Automated Schema Validation: Add the --check flag to a CI pipeline to fail builds if migrations are needed:
```
php bin/console doctrine:migrations:diff-file --check
```
  Exit code 1 indicates pending migrations (useful for enforcing schema consistency).
Multi-Environment Sync
- Use the schema file as a source of truth for environments where direct DB access is restricted (e.g., staging).
- Example:
```
# Generate migration for staging (schema file vs. staging DB)
php bin/console doctrine:migrations:diff-file --env=staging
```

Integration Tips

Custom Schema Paths: Override the default schema file path in config:

# config/packages/a5sys_doctrine_migration_tools.yaml
a5sys_doctrine_migration_tools:
    schema_file: '%kernel.project_dir%/config/custom_schema.yml'

Combine with Doctrine Extensions: If using StoDoctrineExtensionsBundle (e.g., for behaviors like timestamps), ensure your schema file includes these extensions to avoid migration conflicts.
Version Control: Commit the generated schema dump (SchemaVersion/) to track schema evolution alongside migrations.

Gotchas and Tips

Pitfalls

Schema File Desync
- Issue: The schema file (schema.yml) drifts from the actual database schema due to manual migrations or third-party changes.
- Fix: Periodically regenerate the schema dump:
```
php bin/console doctrine:schema:update --dump-sql --complete
```
  Then update schema.yml manually or use a diff tool to reconcile.
False Positives with --check
- Issue: The --check flag may return 1 (error) even if no changes are needed, due to:
  - Case-sensitive path issues (e.g., schema.yml vs. Schema.yml).
  - File permission problems in SchemaVersion/.
- Fix: Verify paths and permissions:
```
ls -la app/DoctrineMigrations/SchemaVersion/
```
Migration Generation Conflicts
- Issue: Running diff-file after manual DB changes may produce incorrect migrations.
- Fix: Always migrate the database to match the schema file before generating new migrations:
```
php bin/console doctrine:schema:update --force
```
Namespace/Autoloading Issues
- Issue: Generated migrations may fail to autoload if the src/Migrations/ directory isn’t properly configured.
- Fix: Ensure src/Migrations/ is listed in composer.json:
```
"autoload": {
    "psr-4": {
        "App\\Migrations\\": "src/Migrations/"
    }
}
```

Debugging

Verbose Output: Use -v or -vv to debug the diff process:
```
php bin/console doctrine:migrations:diff-file -vv
```
Dry Run: Test schema updates without writing to the database:
```
php bin/console doctrine:schema:update --dry-run
```

Extension Points

Custom Diff Logic Override the diff command by extending the bundle’s service:

# config/services.yaml
a5sys_doctrine_migration_tools.diff_command:
    class: App\Command\CustomDiffCommand
    arguments:
        - '@a5sys_doctrine_migration_tools.diff_command.inner'
    tags: ['console.command']

Implement App\Command\CustomDiffCommand to modify diff behavior (e.g., ignore specific tables).

Post-Generation Hooks Use Symfony’s event system to act after migration generation:

// src/EventListener/MigrationGeneratedListener.php
class MigrationGeneratedListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            'a5sys_doctrine_migration_tools.migration_generated' => 'onMigrationGenerated',
        ];
    }

    public function onMigrationGenerated(MigrationGeneratedEvent $event)
    {
        // Example: Slack notification or Git hook trigger
    }
}

Configuration Quirks

Schema Version Directory: The default SchemaVersion/ path is hardcoded to app/DoctrineMigrations/SchemaVersion/. To change it:
```
a5sys_doctrine_migration_tools:
    schema_version_dir: '%kernel.project_dir%/var/schema_backups'
```
Migration Naming: Generated migrations use YYYYMMDDHHMMSS_ prefix. To customize: Override the MigrationGenerator service (advanced; requires deep bundle knowledge).

Pro Tips

Schema File Format: Prefer schema.yml over schema.xml for readability and easier version control diffs.
Atomic Schema Updates: Use transactions when updating the schema file to avoid partial states:
```
php bin/console doctrine:schema:update --complete --dump-sql | mysql -u user -p db_name
```

Backup Schema Dumps: Archive SchemaVersion/ periodically to audit schema history:

tar -czvf schema_backup_$(date +%Y-%m-%d).tar.gz app/DoctrineMigrations/SchemaVersion/

Doctrine Migration Tools Bundle Laravel Package