Akeneo Migrations Manager Bundle Laravel Package

Getting Started

First Steps

1. Installation Run composer require clickandmortar/akeneo-migrations-manager-bundle in your Akeneo (v2.3+ or v3.1+) project. Ensure PHP ≥7.1 is used.

2. Enable the Bundle Add the bundle to AppKernel.php under registerProjectBundles():

   new ClickAndMortar\AkeneoMigrationsManagerBundle\ClickAndMortarAkeneoMigrationsManagerBundle(),
   

3. Create a Migration Job Generate a batch job to execute migrations via CLI:

   php bin/console akeneo:batch:create-job internal execute_migration migration execute_migration_by_version '{"migrationVersion":null}' 'Execute migration by version'
   

   This creates a job (execute_migration) to run migrations programmatically.

4. First Use Case Run a migration manually:

   php bin/console akeneo:batch:execute execute_migration
   

   Check the Akeneo dashboard for a new "Migrations" widget listing available migrations.

Implementation Patterns

Daily Workflows

1. Migration Development

   • Extend the bundle’s migration system by creating custom migration classes in src/Akeneo/Migration/ (or a custom namespace).
   • Example structure:

     src/
     └── Akeneo/
         └── Migration/
             ├── Version20230101000000.php
             └── Version20230102000000.php
     

   • Follow Akeneo’s migration naming convention: VersionYYYYMMDDHHMMSS.php.

2. Running Migrations

   • Via CLI: Execute all pending migrations:

     php bin/console akeneo:batch:execute execute_migration
     

   • Via Dashboard: Use the "Migrations" widget to trigger migrations manually or track progress.

3. Version-Specific Execution

   • Pass a specific migration version to the job:

     php bin/console akeneo:batch:execute execute_migration --parameters='{"migrationVersion":"20230101000000"}'
     

4. Integration with Custom Logic

   • Override the default migration executor by extending the bundle’s services (e.g., migration.executor).
   • Example: Add pre/post-migration hooks:

     # config/services.yaml
     services:
         App\Migration\CustomMigrationExecutor:
             decorates: 'migration.executor'
             arguments: ['@App\Migration\CustomMigrationExecutor.inner']
     

5. Automated Migration Runs

   • Schedule migrations via Akeneo’s cron system or external tools (e.g., Jenkins, GitHub Actions) by calling the batch job endpoint:

     php bin/console akeneo:batch:execute execute_migration --env=prod
     

Gotchas and Tips

Pitfalls and Debugging

1. Bundle Compatibility

   • Akeneo v2.x vs. v3.x: Ensure you use the correct bundle version (v1.0.* for v2.3, v1.1.* for v3.1/3.2).
   • PHP Version: The bundle requires PHP ≥7.1. Downgrading may break dependencies.

2. Migration Execution Issues

   • Job Not Found: If execute_migration job is missing, recreate it:

     php bin/console akeneo:batch:create-job internal execute_migration migration execute_migration_by_version '{"migrationVersion":null}' 'Execute migration by version'
     

   • Permission Errors: Ensure the Akeneo user running the job has write access to the var/ directory and database.

3. Dashboard Widget Missing

   • Clear Akeneo’s cache after installation:

     php bin/console cache:clear
     

   • Verify the bundle is enabled in AppKernel.php.

4. Migration Ordering

   • Migrations are executed chronologically by filename. Avoid naming conflicts (e.g., Version20230101000000.php vs. Version20230101000001.php).
   • Use up() and down() methods in your migration classes for reversible changes:

     public function up()
     {
         // Apply changes
     }
     public function down()
     {
         // Revert changes
     }
     

5. Logging and Rollbacks

   • Check logs for migration failures:

     tail -f var/log/akeneo_migrations.log
     

   • To rollback a migration, manually call down() or recreate the migration with a higher timestamp.

Extension Points

1. Custom Migration Classes

   • Extend Akeneo\Migration\AbstractMigration for reusable logic:

     namespace App\Migration;
     use Akeneo\Migration\AbstractMigration;
     
     class CustomMigration extends AbstractMigration {
         protected function execute(AkeneoMigrationContext $context) {
             // Custom logic
         }
     }
     

2. Override Job Configuration

   • Customize the batch job in config/packages/akeneo_migrations_manager.yaml:

     akeneo_migrations_manager:
         job_name: 'custom_migration_job'
         job_parameters: '{"timeout": 3600, "memory_limit": "1G"}'
     

3. Add Migration Metadata

   • Store migration metadata (e.g., author, description) in the migration class:

     class Version20230101000000 extends AbstractMigration {
         public function getDescription() {
             return "Add new product attribute";
         }
         public function getAuthor() {
             return "John Doe";
         }
     }
     

4. Event Listeners

   • Listen to migration events (e.g., akeneo_migrations_manager.migration.pre_execute) to add pre-flight checks:

     // src/EventListener/MigrationListener.php
     public static function getSubscribedEvents() {
         return [
             'akeneo_migrations_manager.migration.pre_execute' => 'onPreExecute',
         ];
     }