Fregata Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require aymdev/fregata-bundle
   

   Ensure your project meets the requirements: PHP 8.1+, Symfony 4.4/5.x.

2. Configure Database Entities Run Doctrine migrations to create the required tables:

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

3. Configure Messenger Transport Edit config/packages/messenger.yaml to route FregataMessageInterface to your transport (e.g., async):

   framework:
       messenger:
           transports:
               async: '%env(MESSENGER_TRANSPORT_DSN)%'
           routing:
               'Fregata\FregataBundle\Messenger\FregataMessageInterface': async
   

4. Enable UI Routes Create config/routes/fregata.yaml:

   fregata:
       resource: "@FregataBundle/Resources/config/routes.xml"
       prefix: /fregata
   

5. First Migration Run Trigger a migration via CLI or UI:

   php bin/console fregata:migration:execute
   

   Or navigate to /fregata and click "New run".

Implementation Patterns

Workflow: Defining and Running Migrations

1. Define Migrations Use Fregata’s core framework to define migrations (e.g., BeforeTask, Migrator, AfterTask). Example:

   use Fregata\Migration\Migration;
   
   class MyMigration extends Migration
   {
       protected function configure(): void
       {
           $this->addMigrator(new MyMigrator());
           $this->addBeforeTask(new SetupTask());
       }
   }
   

2. Register Migrations Configure migrations in config/packages/fregata.yaml:

   fregata:
       migrations:
           - MyApp\Migration\MyMigration
   

3. Asynchronous Execution

   • Migrations run via Messenger, so they’re non-blocking.
   • Monitor progress via the UI (/fregata/run/{id}) or CLI:

     php bin/console messenger:consume async -vv
     

4. Synchronous Execution (Debugging) Use the --synchronous flag for testing:

   php bin/console fregata:migration:execute --synchronous
   

Integration Tips

1. Dependency Management

   • Fregata handles migrator dependencies automatically (e.g., A must run before B if B depends on A).
   • Visualized in the UI under the "Migrators" tab.

2. UI Features

   • Dashboard: Lists active/past runs with status (e.g., pending, running, completed).
   • Run Details: Shows progress bars for BeforeTasks, Migrators, and AfterTasks.
   • Cancel Runs: Available via the UI while a migration is running.

3. Customizing the UI Extend Twig templates in templates/FregataBundle/ to modify layouts or add fields (e.g., custom run metadata).

4. Logging Use Symfony’s logger in migrators/tasks:

   $this->logger->info('Migration step completed', ['migration' => $this->getName()]);
   

Gotchas and Tips

Pitfalls

1. Messenger Transport Misconfiguration

   • Issue: Migrations hang or fail silently if the transport (e.g., async) isn’t properly configured.
   • Fix: Verify MESSENGER_TRANSPORT_DSN (e.g., doctrine://default) and run:

     php bin/console messenger:setup-transports
     

2. Database Schema Mismatch

   • Issue: If Doctrine migrations aren’t run, the UI will fail with EntityManager errors.
   • Fix: Always run make:migration + migrations:migrate after installing the bundle.

3. Synchronous Mode Limitations

   • Issue: --synchronous bypasses the UI and database tracking.
   • Fix: Use only for testing; prefer async for production.

4. Circular Dependencies

   • Issue: Fregata throws an exception if migrators have circular dependencies.
   • Fix: Review migrator configurations or use dependsOn() explicitly.

Debugging Tips

1. Check Messenger Queue Inspect pending messages:

   php bin/console messenger:failed:list
   php bin/console messenger:failed:retry [message-id]
   

2. Enable Debug Mode Add to config/packages/dev/fregata.yaml:

   fregata:
       debug: true
   

   This logs detailed migration steps to var/log/dev.log.

3. UI Debugging

   • Clear cache if the UI appears broken:

     php bin/console cache:clear
     

   • Check Twig errors in var/log/dev.log.

Extension Points

1. Custom Run Metadata Extend the Run entity (e.g., src/Entity/FregataRunExtension) to add fields like priority or user_id.

2. Custom UI Components Override Twig templates (e.g., templates/FregataBundle/run/index.html.twig) to add buttons or fields.

3. Pre/Post-Hooks Use Symfony events to intercept migration runs:

   // config/services.yaml
   services:
       App\EventListener\FregataListener:
           tags:
               - { name: kernel.event_listener, event: fregata.migration.run.started, method: onRunStarted }
   

4. Custom Transports Route FregataMessageInterface to a custom transport (e.g., Kafka) by modifying messenger.yaml.