## Getting Started

### Minimal Steps to Begin
1. **Installation**:
   ```bash
   composer require kaliop/ezmigrationbundle --dev

new \Kaliop\eZMigrationBundle\EzMigrationBundle(),

Verify Installation: Confirm new commands appear:
```
php bin/console kaliop:migration:status
```
Generate First Migration:
```
php bin/console kaliop:migration:generate --format=yml MyBundle
```
This creates a timestamped .yml file in MyBundle/MigrationVersions/.
Apply a Migration: Edit the generated file (e.g., add a content step) and run:
```
php bin/console kaliop:migration:migrate
```

First Use Case: Content Type Update

Edit the generated YAML to add/update a content type:

-
    mode: update
    type: content_type
    identifier: article
    attributes:
        name: Article
        description: Updated article type

Run:

php bin/console kaliop:migration:migrate

Implementation Patterns

Workflow: Schema + Content Migrations

Schema Changes (e.g., content types, sections): Use YAML migrations for declarative changes:

-
    mode: create
    type: content_type
    identifier: blog_post
    attributes:
        name: Blog Post
        main_location: 2

Content Population: Loop over arrays to create multiple contents:

-
    type: loop
    items:
        - { title: "Post 1", body: "Content 1" }
        - { title: "Post 2", body: "Content 2" }
    steps:
        -
            mode: create
            type: content
            content_type: blog_post
            attributes:
                name: "%item.title%"
                body: "%item.body%"

SQL for Complex Logic: Generate an SQL migration:

php bin/console kaliop:migration:generate MyBundle fix_data --format=sql

Edit the generated .sql file (e.g., 20231001000000_mysql_fix_data.sql) and run:

php bin/console kaliop:migration:migrate --path=src/MyBundle/Migrations/20231001000000_mysql_fix_data.sql

Integration Tips

Dependency Management: Place migrations in feature-specific bundles (e.g., BlogBundle/MigrationVersions/).
Testing: Use kaliop:migration:status to verify migrations before deployment.
Rollbacks: Create inverse migrations (e.g., delete_content_type.yml after create_content_type.yml).
Admin User: Specify a non-default admin user with -a flag if needed:
```
php bin/console kaliop:migration:migrate -a 15
```

Gotchas and Tips

Pitfalls

Transaction Scope:
- Migrations run in transactions by default. Disable with -u flag if needed:
```
php bin/console kaliop:migration:migrate -u
```
- Workaround: Split complex migrations into smaller files to isolate failures.

Failed Migrations:

Remove failed migrations from the kaliop_migrations table to retry:

php bin/console kaliop:migration:migration 20231001000000_failed_migration --delete

SQL Limitations:

Long SQL queries may fail silently (e.g., MySQL). Split into multiple migrations or use YAML with sql steps:

-
    type: sql
    sql: |
        UPDATE ezcontentobject_attribute SET data_text1 = 'new_value'
        WHERE attribute_id = 123;

PHP Migrations:

Class names must match filenames (no namespaces). Example:

// 20231001000000_CustomMigration.php
class CustomMigration implements MigrationInterface {
    public function up(Connection $connection, array $options) {
        // Logic here
    }
}

References:
- Use %reference% placeholders for dynamic values (e.g., %content_id% from prior steps). Define references in the migration:
```
references:
    content_id: "%content.id%"
```

Debugging Tips

Dry Runs: Use kaliop:migration:status to preview changes before applying.
Logging: Enable debug mode (APP_DEBUG=1) for detailed step-by-step logs.

Event Listeners: Hook into ez_migration.step_executed to log or validate steps:

// config/services.yaml
services:
    App\EventListener\MigrationLogger:
        tags:
            - { name: kernel.event_listener, event: ez_migration.step_executed, method: logStep }

Extension Points

Custom Actions: Extend the DSL by creating a service tagged as ez_migration.action_executor:

# config/services.yaml
services:
    App\Migration\CustomActionExecutor:
        tags:
            - { name: ez_migration.action_executor, type: custom_action }

Event Subscribers: Subscribe to ez_migration.before_execution to validate migrations pre-run:

use Kaliop\eZMigrationBundle\API\Event\BeforeStepExecutionEvent;

class MigrationValidator implements EventSubscriberInterface {
    public static function getSubscribedEvents() {
        return ['ez_migration.before_execution' => 'validate'];
    }

    public function validate(BeforeStepExecutionEvent $event) {
        if ($event->getStep()['type'] === 'delete' && !$event->getOptions()['dry_run']) {
            throw new \RuntimeException("Deletes require dry-run mode.");
        }
    }
}

Configuration Overrides: Customize the migrations table name in config/packages/ez_migration.yaml:
```
kaliop_ez_migration:
    table_name: custom_migration_table
```

Pro Tips

Mass Migrate: Apply all pending migrations in a folder:

php bin/console kaliop:migration:migrate --path=src/MyBundle/MigrationVersions/

Resume Failed Migrations: Use kaliop:migration:resume to continue after a crash.
Backup First: Always snapshot the database before running migrations:
```
mysqldump -u user db_name > backup.sql
```
Version Control: Commit migrations to Git for reproducibility. Use .gitignore to exclude generated files like kaliop_migrations.

---

Ezmigrationbundle Laravel Package