Dami Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require czogori/dami-bundle
   

   Ensure DamiBundle is enabled in config/bundles.php:

   return [
       // ...
       Czogori\DamiBundle\DamiBundle::class => ['all' => true],
   ];
   

2. First Use Case: The bundle appears to be a data migration helper (inferred from the name "Dami" = "Data Migration"). Check the src/Resources/config/services.yaml for default configurations or run:

   php bin/console dami:list
   

   (If the command exists—verify via php bin/console list)

3. Where to Look First:

   • Bundle Documentation: The README is minimal; inspect src/ for core classes (e.g., DamiService, Migration).
   • Commands: Run php bin/console list to check for custom CLI tools (e.g., dami:migrate).
   • Configuration: Override defaults in config/packages/czogori_dami.yaml (if provided).

Implementation Patterns

Core Workflows

1. Data Migration Orchestration:

   • Define Migrations: Create custom migration classes extending DamiBundle\Migration\AbstractMigration (if the bundle follows Laravel’s migrator pattern).

     namespace App\Dami\Migrations;
     
     use Czogori\DamiBundle\Migration\AbstractMigration;
     
     class UpdateUserEmails extends AbstractMigration {
         public function up() {
             DB::table('users')->update(['email_verified' => true]);
         }
     }
     

   • Register Migrations: Use a bundle event (e.g., DamiEvents::REGISTER_MIGRATION) or a service tag (services.yaml):

     services:
         app.dami.migrations.update_emails:
             class: App\Dami\Migrations\UpdateUserEmails
             tags: ['czogori.dami.migration']
     

2. CLI Integration:

   • Run Migrations:

     php bin/console dami:migrate --migration=UpdateUserEmails
     

   • Rollback:

     php bin/console dami:rollback --migration=UpdateUserEmails
     

3. Database-Agnostic Logic:

   • Use the bundle’s query builder wrappers (if provided) to abstract SQL:

     $this->dami->table('users')->where('active', false)->delete();
     

Integration Tips

• Event-Driven Hooks: Listen for DamiEvents::MIGRATION_STARTED/COMPLETED to log or validate migrations.
• Batch Processing: For large datasets, implement chunked queries:

  DB::table('orders')->orderBy('id')->chunk(1000, function ($orders) {
      foreach ($orders as $order) {
          // Process order
      }
  });
  

• Testing: Mock the DamiService in PHPUnit:

  $this->mock(DamiService::class)->shouldReceive('runMigration')->once();
  

Gotchas and Tips

Pitfalls

1. Lack of Documentation:

   • The bundle’s README offers no usage examples. Assume minimal defaults and inspect src/ for undocumented features.
   • Workaround: Use php bin/console debug:container Czogori\DamiBundle to explore services.

2. No Built-in Rollback:

   • If dami:rollback doesn’t exist, implement it manually by storing migration states in a migrations table:

     Schema::create('dami_migrations', function (Blueprint $table) {
         $table->id();
         $table->string('name');
         $table->timestamp('executed_at')->nullable();
     });
     

3. Database Locking:

   • Long-running migrations may cause timeouts. Use transactions:

     DB::transaction(function () {
         // Migration logic
     });
     

Debugging

• Enable Verbose Output:

  php bin/console dami:migrate --verbose
  

• Check Logs: Tail storage/logs/laravel.log for errors during execution.
• SQL Dumps: Use Laravel’s query logging:

  DB::enableQueryLog();
  // Run migration
  dd(DB::getQueryLog());
  

Extension Points

1. Custom Migration Types:

   • Extend AbstractMigration to add pre/post hooks:

     protected function preUp() { /* Validate data */ }
     protected function postDown() { /* Cleanup */ }
     

2. Add CLI Commands:

   • Create a custom command to list pending migrations:

     namespace App\Console\Commands;
     
     use Czogori\DamiBundle\Migration\MigrationRepository;
     use Illuminate\Console\Command;
     
     class ListPendingMigrations extends Command {
         protected $signature = 'dami:pending';
         public function handle(MigrationRepository $repository) {
             foreach ($repository->getPending() as $migration) {
                 $this->info($migration->getName());
             }
         }
     }
     

3. Configuration Overrides:

   • Override the default dami service in config/services.yaml:

     czogori_dami:
         default_connection: pgsql
         batch_size: 500
     

Pro Tips

• Idempotency: Design migrations to be rerunnable (e.g., check executed_at before running).
• Dry Runs: Add a --dry-run flag to simulate migrations without executing:

  if ($this->option('dry-run')) {
      $this->comment("Would execute: " . $query);
      return;
  }
  

• Parallel Migrations: Use Laravel Queues to run migrations in the background:

  RunMigrationJob::dispatch($migrationClass);