Cli Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in a Laravel project (note: this is a Symfony bundle, so use cautiously):

   composer require doctrine/dbal-util/cli-bundle
   

   Register the bundle in config/bundles.php (if using Symfony components) or wrap in a Laravel service provider.

2. First Use Case Run a basic DBAL command (e.g., schema inspection) via Artisan:

   php artisan dbal:schema:inspect --connection=mysql
   

   (Note: Laravel may require aliasing the command in app/Console/Kernel.php.)

3. Prerequisites

   • Ensure doctrine/dbal is installed (Laravel includes it by default).
   • Configure your database connection in .env (e.g., DB_CONNECTION=mysql).

Implementation Patterns

Workflows

1. Schema Management

   • Inspect: Use dbal:schema:inspect to dump a database schema as SQL or JSON.

     php artisan dbal:schema:inspect --format=json --output=schema.json
     

   • Update: Apply migrations via dbal:migration:execute (if using DBAL migrations).

     php artisan dbal:migration:execute --path=migrations
     

2. Data Operations

   • Query Execution: Run raw SQL with dbal:query (useful for one-off scripts).

     php artisan dbal:query "SELECT * FROM users LIMIT 10"
     

   • Data Dumping: Export tables to SQL files.

     php artisan dbal:data:export --table=users --output=users.sql
     

3. Integration with Laravel

   • Service Provider: Bind DBAL connections to Laravel’s container in AppServiceProvider:

     use Doctrine\DBAL\Connection;
     public function register()
     {
         $this->app->singleton(Connection::class, function ($app) {
             return \Doctrine\DBAL\DriverManager::getConnection($app['config']['database.connections.mysql']);
         });
     }
     

   • Artisan Commands: Extend existing commands or create custom ones by extending Symfony\Component\Console\Command\Command.

4. Configuration

   • Override default DBAL config in config/database.php under doctrine (if using Symfony-style config).
   • Example:

     'doctrine' => [
         'dbal' => [
             'driver' => 'pdo_mysql',
             'url' => env('DATABASE_URL'),
         ],
     ],
     

Gotchas and Tips

Pitfalls

1. Symfony Dependency

   • The bundle assumes Symfony’s autowiring and console components. In Laravel, you may need to:
     • Manually register the bundle in AppServiceProvider.
     • Alias commands in app/Console/Kernel.php:

       protected $commands = [
           \Doctrine\DBALUtil\CLIBundle\Command\SchemaInspectCommand::class,
           // Add other commands as needed
       ];
       

2. Connection Handling

   • Laravel’s connection naming differs from DBAL’s. Ensure --connection flags match your .env (e.g., mysql vs. pgsql).
   • Debug connection issues with:

     php artisan dbal:connection:info --connection=mysql
     

3. Migration Quirks

   • DBAL migrations are not Laravel migrations. Use dbal:migration:execute for DBAL-specific migrations, not Eloquent migrations.
   • Schema updates may conflict with Laravel’s migrations. Coordinate changes carefully.

4. Output Formatting

   • JSON output may require json_decode() in PHP:

     $schema = json_decode(file_get_contents('schema.json'), true);
     

Debugging

• Verbose Mode: Add -v or -vv to commands for debug output.

  php artisan dbal:schema:inspect -vv
  

• Log Configuration: Enable DBAL logging in config/database.php:

  'logging' => true,
  'logging_format' => '%%timestamp%% %%connection%% %%sql%%',
  'logging_level' => \Doctrine\DBAL\Logging\Logger::DEBUG,
  

Extension Points

1. Custom Commands Extend Doctrine\DBALUtil\CLIBundle\Command\AbstractCommand to add domain-specific logic:

   namespace App\Console\Commands;
   use Doctrine\DBALUtil\CLIBundle\Command\AbstractCommand;
   
   class CustomExportCommand extends AbstractCommand
   {
       protected function configure()
       {
           $this->setName('dbal:custom:export');
       }
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           // Custom logic
       }
   }
   

2. Event Listeners Hook into DBAL events (e.g., postConnect) via Symfony’s event dispatcher:

   $dispatcher->addListener(ConnectionEvents::POST_CONNECT, function (ConnectionEventArgs $args) {
       $args->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping(...);
   });
   

3. Laravel-Eloquent Bridge Use DBAL for raw queries while keeping Eloquent for ORM:

   $dbalConnection = app(Connection::class);
   $results = $dbalConnection->fetchAll("SELECT * FROM users WHERE active = 1");