Ezmigrationbundle2 Laravel Package

Getting Started

1. Install via Composer (pin the version — the package has no active releases and no dependents, so pin an exact tag/commit):

   composer require suez/ezmigrationbundle2
   

2. Register the bundle in config/bundles.php (Ibexa 3 uses Symfony Flex-style registration):

   Suez\EzMigrationBundle2\EzMigrationBundle2::class => ['all' => true],
   

   Verify the actual class name — the fork may keep the original Kaliop\... namespace for BC.
3. Locate the config block. Kaliop's original bundle used kaliop_migrations:; the Suez fork may rename it. Search the source for Configuration.php / Extension.php to confirm the key (likely ez_migration or suez_migration) and the migration_directory option.
4. Confirm the CLI namespace:

   php bin/console list | grep -i migr
   

   You'll see commands like kaliop:migration:create, …:migrate, …:list, …:status, and …:generate.
5. Create your first migration:

   php bin/console kaliop:migration:create --path=src/AppBundle/MigrationVersions my_first_migration
   

   This drops a timestamped YAML file (VersionYYYYMMDDHHMMSS.yml) into the path.
6. Run it:

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

7. First real use case: scripting a content-type schema change (adding a field via type: contentType) plus seeding new content with type: content and references — the canonical "define-then-populate" cycle this bundle shines at.

Implementation Patterns

• One file = one atomic deploy step. Place migration YAML files in a MigrationVersions/ folder inside a real bundle (not src/MigrationVersions unless --path is passed consistently every time). Files are applied in lexicographic order, so keep the Version<timestamp> prefix.
• Define-then-reference within a migration. The idiomatic pattern is:

  - type: contentType
    mode: update
    identifier: article
    translations: ...
  - type: content
    mode: create
    contentType: article
    parentLocationId: 2
    references:
      - identifier: my_article
        attribute: id
  - type: content
    mode: update
    match:
      location_remote_id: ${my_article.location_remote_id}
    attributes:
      title: "Updated via migration"
  

  References resolve only within the same file/run — you can't reference an entity created in a previous migration file.
• Idempotency matters. Use match: (by identifier, location_remote_id, content_remote_id) rather than raw IDs. Migrations get re-run on fresh envs; match + mode: update keeps them safe. Add --no-interaction in CI.
• Chaining env-specific migrations. Keep base schema migrations in a shared bundle and per-environment seed data in app/MigrationVersions. Run both by passing --path twice, or by symlinking — there is no built-in multi-directory config in the original bundle.
• Preview before applying: --plan lists pending versions without running them; add it to your local pre-commit hook. Use --dry-run in a deploy job to confirm no surprises.
• Targeted runs: --up / --down with a version number, or --target=Version20230101... to stop at a specific point. Useful for hotfixes on production.
• Content migration with --type=content filters: the CLI supports limiting by step type, which is handy for large content seeders where you only want to re-run the contentType schema portion.
• Deploy integration: wrap migrate in a Symfony command or a capistrano/deployer hook — call --no-interaction --env=prod. Do not run schema/content migrations inside the same artisan-style task as cache warmup; content caches need to be cleared after migrate.
• Generating migrations from existing content: kaliop:migration:generate can dump existing content types (and sometimes content) into a migration YAML — the fastest way to bootstrap a baseline from a legacy eZ install.

Gotchas and Tips

• Config key mismatch is the #1 tripwire. Because this is a renamed fork, docs from the original Kaliop bundle will have kaliop_migrations: — if that key does nothing, inspect DependencyInjection/Configuration.php in the vendor directory for the actual root node (Suez variants often use ez_migrations or suez_migrations).
• Command namespace may still be kaliop: even though the bundle is renamed. The fork typically preserves CLI names for backwards compatibility; grep AsCommand (or $this->setName) in Command/.
• Rollback is best-effort. --down only works if the step type supports reversal (e.g., content: delete will be attempted, but contentType: update cannot be un-done — the original schema isn't preserved). Treat migrations as forward-only in production unless you've verified the step type explicitly documents a down mode.
• YAML quoting: bare strings starting with -, containing :, or trailing whitespace break the parser. Language codes like eng-GB, and attribute values that look like numbers (e.g., phone numbers) should be quoted.
• References are volatile. ${ref.field} is resolved at execution time from the migration context. If your file splits content updates across multiple migrations, the reference dies with the run. Use remote_id or identifier match rules to bridge files.
• No transactions. Each step commits independently. A mid-migration failure leaves earlier steps applied; the bundle records only fully applied version files in the migrations log table, so a re-run will replay the whole file — hence idempotency via match is not optional.
• Ordering hazards with new content types: creating a content type and immediately creating content of that type in the same file can break because the content-type model cache isn't refreshed until the request ends. Either split into two files or add a small delay/cache:clear step in a wrapper command.
• Ibexa 4 compatibility is not guaranteed. Version 2 targets eZ Platform 3 / Ibexa 3.x. If you're on Ibexa 4, inspect the composer.json require constraint and the kernel version referenced in Repository/KernelFactory-like code before upgrading.
• Debugging: run with -vvv and tail var/log/prod.log — the bundle logs each step's parsed YAML payload. If a reference fails to resolve, the error is often a silent null that manifests as Entity not found on the next step; inspect the reference block carefully.
• Extension points: the package is designed around pluggable step handlers (one class per type:). If you need a custom step (e.g., type: myCustomData), implement a handler extending AbstractStep (or its fork equivalent) and tag it as a service — search the fork's Resources/config/services.yml for the handler tag name (ez_migration_bundle.step_handler or similar).
• Pin your version. With 0 stars, no released dependents, last commit in January 2023, and a fork of an already-mature GPL-2.0 codebase, treat upstream support as frozen: lock the composer version, and be prepared to patch the fork yourself. Consider whether you actually need the fork vs. the original kaliop/ezmigrationbundle if you target eZ Platform 2.x.
• --env sanity check: migrations are environment-aware. Running --env=dev against a prod DB is a classic footgun; double-check DATABASE_URL before hitting migrate.