Phpcr Migrations Bundle Laravel Package

Getting Started

1. Install and enable. composer require phpcr/phpcr-migrations-bundle. On Symfony Flex the bundle is usually auto-registered; otherwise add it to config/bundles.php. You need a working Doctrine PHPCR-ODM / Jackalope stack already configured (doctrine_phpcr), because the bundle just wires the migration manager to your existing PHPCR session.
2. Create the migrations directory and point the bundle at it in config/packages/phpcr_migrations.yaml (the key is typically migrations_path, plus an optional version/collection name). If your project uses a custom autoloader, make sure migration classes live in a PSR-4 namespace Composer knows about.
3. Where to look first. Open vendor/phpcr/phpcr-migrations/src/ — the MigrationInterface (or AbstractMigration) and the MigrationManager/Factory define the whole contract: up(), an optional down(), and a version string. Then check the bundle's Console/ directory for the exact command names shipped in your version.
4. First use case. Run bin/console list phpcr to confirm the commands, then phpcr:migrations:status (or versions) against your repository. Generate your first migration for a small, real content fix — rename a property, clean orphaned references, move a subtree — implement up(), run phpcr:migrations:migrate, and re-run status to confirm the version was recorded.

Implementation Patterns

• Migration shape. A class implements the library's MigrationInterface (often extending AbstractMigration) with a version/description and up()/down() receiving the migration context. Keep up() idempotent where cheap to do so: re-fetch the node, guard with hasProperty(), and skip if already applied.
• Generation workflow. Use the bundle's generate command to scaffold a timestamped/versioned class, then fill in logic — don't hand-write the version string, since ordering depends on it.
• Content transformations, not schema. PHPCR is schemaless at the node level, so most migrations are data fixes: change a property type, migrate nt:unstructured to a mapped document, rename fields to match updated ODM mappings, move documents between parents, or delete stale nodes. Use the PHPCR session directly for structural ops and the ODM DocumentManager when you need mapped documents.
• Pair with the ODM mapping change. Change the ODM mapping in the same commit as the migration: the migration rewrites existing nodes, the mapping makes the app read them. This keeps the "old code + new data" window small.
• Deploy integration. Add phpcr:migrations:migrate --no-interaction as a post-deploy step, executed exactly once per release (a single deploy job, not every web pod). Gate it behind a successful cache warmup and a reachable repository.
• Tests. Point the bundle at a test migrations directory or run migrations against a dedicated test workspace during fixture setup, so functional tests exercise realistic content.
• Batching for large trees. For migrations touching thousands of nodes, fetch in pages, save() in chunks, and clear() the ODM unit of work between batches rather than one giant save.
• Multiple sets. If the config supports a version/collection name, keep app-data migrations in one set and infrastructure/bootstrap node creation in another so they can be run independently.

Gotchas and Tips

• The version ledger lives in the repository. Applied versions are recorded as a node (e.g. under /jcr:system or a configurable path). Wiping or restoring that node makes migrations re-run or be silently skipped — back it up alongside the content, and never "fix" it by hand without knowing the version strings.
• No universal rollback. down() may exist without a rollback command to invoke it, or the manager may only support forward execution. Treat down() as documentation/emergency tooling, and write forward-only migrations you can trust.
• Session and save semantics. The manager wraps your migration in a session; you still must call save() on changed nodes. Large changesets can be slow or hit Jackalope limits — commit incrementally.
• Ordering is lexical. Versions sort by name/prefix; keep fixed-width numeric or timestamp prefixes so 10 never sorts before 9.
• ODM identity map staleness. After direct session writes, the ODM may return cached documents. Use clear()/refresh() (or run structural reads via the session) before asserting on the result.
• Autoload and namespaces. A migration class that isn't autoloadable produces a confusing "class not found" at runtime, not at config time. Confirm your migrations_path namespace matches the use statements in generated files.
• Deploy concurrency. Two deploy jobs migrating the same workspace will race on the ledger node. Serialize deploys, or use a lock node/flag checked at the start of the command.
• Useful debugging. -vvv on the migrate command, and inspect the ledger node directly (via your PHPCR browser or a quick phpcr:node:dump) to see what the bundle believes is applied. Compare that to the files on disk when status looks wrong.
• Extension points. The manager is a normal Symfony service: decorate or override it to add logging, a lock, or dry-run behavior; add extra migration directories via config; and register custom helper services with the library's tag if it supports one. Check the bundle's Resources/config for the actual service IDs before wiring anything.