Phpcr Migrations Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dantleech/phpcr-migrations-bundle
   

   Enable it in config/bundles.php (Symfony):

   return [
       // ...
       Dantleech\PhpcrMigrationsBundle\DantleechPhpcrMigrationsBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console dantleech:phpcr-migrations:init
   

   Edit config/packages/dantleech_phpcr_migrations.yaml to match your PHPCR session (e.g., DoctrinePHPCRBundle).

3. First Migration Create a migration file in migrations/ (e.g., 20240101000000_AddRootNode.php):

   <?php
   namespace App\Migrations;
   
   use Dantleech\PhpcrMigrationsBundle\Migration\Migration;
   
   class AddRootNode extends Migration
   {
       public function up()
       {
           $this->createNode('/root', 'nt:unstructured');
       }
   
       public function down()
       {
           $this->removeNode('/root');
       }
   }
   

   Run the migration:

   php bin/console dantleech:phpcr-migrations:migrate
   

Key Commands

First Use Case

Problem: You need to version-control your PHPCR repository structure (e.g., for a Symfony + DoctrinePHPCR project). Solution:

1. Use phpcr-migrations:create to generate a migration for your root node.
2. Define up()/down() methods to create/remove nodes.
3. Run phpcr-migrations:migrate to apply changes to your repository.

Implementation Patterns

Workflows

1. Schema Evolution

   • Use migrations to incrementally build your repository structure (e.g., /content, /config).
   • Example: Migrate from flat structure to hierarchical:

     public function up()
     {
         $this->createNode('/content', 'nt:folder');
         $this->moveNode('/old-root', '/content');
     }
     

2. Data Migration

   • Combine with PHPCR queries to transform existing data:

     public function up()
     {
         $session = $this->getSession();
         $query = $session->createQuery(
             'SELECT [jcr:path] FROM [nt:base] WHERE ISDESCENDANTNODE("/old")',
             Query::JCR_SQL2
         );
         // Process results and migrate to new structure.
     }
     

3. Environment-Specific Migrations

   • Use Symfony’s %kernel.environment% to conditionally apply migrations:

     # config/packages/dantleech_phpcr_migrations.yaml
     dantleech_phpcr_migrations:
         environments:
             - dev
             - staging
     

Integration Tips

1. DoctrinePHPCRBundle

   • Ensure your doctrine_phpcr config includes the migrations table:

     doctrine_phpcr:
         session:
             workspace: default
             repository_class: Doctrine\ODM\PHPCR\DocumentManager\PHPCRDocumentManager
         migrations_table: phpcr_migrations
     

2. Custom Node Types

   • Register node types in migrations:

     public function up()
     {
         $this->createNodeType('my:custom', [
             'mix:title' => 'Title',
             'mix:description' => 'Description',
         ]);
     }
     

3. Dependency Management

   • Chain migrations to ensure order:

     public function up()
     {
         $this->createNode('/dependencies/base');
         $this->createNode('/dependencies/feature', ['parent' => '/dependencies/base']);
     }
     

4. Testing

   • Reset migrations in tests:

     public function tearDown(): void
     {
         $this->container->get('dantleech_phpcr_migrations.migration_service')->rollback();
     }
     

Gotchas and Tips

Pitfalls

1. Session Management

   • Issue: Migrations fail if the PHPCR session is not properly configured.
   • Fix: Verify doctrine_phpcr is set up before running migrations. Use:

     php bin/console doctrine:phpcr:session:list
     

2. Transaction Isolation

   • Issue: PHPCR migrations may conflict with concurrent writes.
   • Fix: Wrap migrations in transactions or run during low-traffic periods.

3. Node Existence Checks

   • Issue: createNode() fails if the parent doesn’t exist.
   • Fix: Use ensureNodeExists() or check manually:

     if (!$this->nodeExists('/parent')) {
         $this->createNode('/parent');
     }
     

4. Down Migration Gaps

   • Issue: down() methods may not cover all up() changes.
   • Fix: Test rollbacks thoroughly. Use phpcr-migrations:status to verify.

Debugging

1. Enable Verbose Output

   php bin/console dantleech:phpcr-migrations:migrate --verbose
   

2. Check Migration Table

   • Inspect phpcr_migrations in your PHPCR workspace to verify applied migrations:

     SELECT * FROM [phpcr_migrations];
     

3. PHPCR Logging

   • Enable DoctrinePHPCR logging in config/packages/dev/doctrine.yaml:

     doctrine:
         phpcr:
             logging: true
     

Extension Points

1. Custom Migration Service

   • Override the migration service to add pre/post hooks:

     # config/services.yaml
     Dantleech\PhpcrMigrationsBundle\Migration\MigrationService:
         arguments:
             $preMigrationCallback: [@your_service, 'preMigration']
     

2. Dynamic Migration Paths

   • Extend the migration loader to support custom paths:

     // src/Migration/MigrationLoader.php
     class CustomLoader extends \Dantleech\PhpcrMigrationsBundle\Migration\MigrationLoader
     {
         public function getMigrationFiles(): array
         {
             return array_merge(
                 parent::getMigrationFiles(),
                 glob(__DIR__ . '/../CustomMigrations/*.php')
             );
         }
     }
     

3. PHPCR Event Listeners

   • Attach listeners to PHPCR events (e.g., nodeAdded) for real-time validation:

     $eventManager = $this->getSession()->getWorkspace()->getEventManager();
     $eventManager->registerListener(
         \PHPCR\Event\NodeAddedEvent::class,
         [$this, 'onNodeAdded']
     );
     

Configuration Quirks

1. Workspace Isolation

   • Migrations default to the default workspace. Specify another in config:

     dantleech_phpcr_migrations:
         workspace: custom_workspace
     

2. Migration Table Location

   • Change the table path if using a non-standard workspace:

     doctrine_phpcr:
         session:
             workspace: custom
         migrations_table: /var/workspaces/custom/phpcr_migrations
     

3. Case Sensitivity

   • PHPCR paths are case-sensitive. Ensure consistency in migration paths (e.g., /Root vs /root).