Deployment Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require disparity/deployment-bundle:>=0.1
   

   Add the bundle to AppKernel.php (Symfony 2.x):

   new Disparity\DeploymentBundle\DisparityDeploymentBundle(),
   

2. First Use Case: Migrate to a specific commit/tag/branch:

   php app/console disparity:deployment:migrate v1.0.0
   

   • Verify the working directory reflects the target state.
   • Check display-sql flag for debugging migrations.

Where to Look First

• Command Reference: php app/console help disparity:deployment:migrate
• Configuration: Check app/config/config.yml for bundle-specific settings (if any).
• Git Hooks Alternative: Since the project is abandoned, review Disparity’s Git Hooks for modern alternatives.

Implementation Patterns

Core Workflows

1. Deployment Migration:

   • Branch/Tag/Commit: Specify target (e.g., main, v2.3.1, abc1234).
   • Flags:
     • --display-sql: Log SQL queries (useful for debugging Doctrine migrations).
     • --clean-working-copy: Reset working directory before migration (caution: destructive).
   • Example:

     php app/console disparity:deployment:migrate feature/xyz --clean-working-copy
     

2. Integration with Laravel (Symfony Bridge):

   • Use Symfony’s Process component to call the command from Laravel:

     use Symfony\Component\Process\Process;
     $process = new Process(['php', 'artisan', 'disparity:deployment:migrate', 'v1.2.0']);
     $process->run();
     echo $process->getOutput();
     

   • Note: Laravel lacks native Symfony console support; wrap commands in a custom Artisan command.

3. Post-Migration Hooks:

   • Extend the bundle’s MigrateCommand (if source is available) to trigger Laravel events (e.g., Deployed).
   • Example (hypothetical extension):

     // app/Console/Commands/Deploy.php
     use Disparity\DeploymentBundle\Command\MigrateCommand;
     class Deploy extends MigrateCommand {
         protected function execute(InputInterface $input, OutputInterface $output) {
             parent::execute($input, $output);
             event(new DeploymentCompleted($this->getTarget()));
         }
     }
     

4. Dependency Management:

   • The bundle auto-installs Composer dependencies for the target commit. Verify composer.json updates post-migration.

Best Practices

• Backup First: Always back up the working directory before --clean-working-copy.
• Dry Runs: Use --display-sql to validate migrations without applying them.
• CI/CD Pipelines: Integrate the command in deployment scripts (e.g., GitHub Actions):

  - name: Deploy to commit
    run: php artisan disparity:deployment:migrate ${{ github.sha }}
  

Gotchas and Tips

Pitfalls

1. Abandoned Project:

   • No active maintenance; expect bugs or compatibility issues with modern Symfony/Laravel.
   • Mitigation: Fork the repo or use Disparity’s Git Hooks as a replacement.

2. Doctrine Migrations:

   • The bundle runs migrations after Git checkout. If migrations fail, the working copy may be in an inconsistent state.
   • Tip: Test migrations locally first with --display-sql.

3. Composer Lock Conflicts:

   • Migrating to a commit with a different composer.lock may cause dependency conflicts.
   • Fix: Run composer update post-migration if needed.

4. Laravel-Specific Issues:

   • Artisan Compatibility: The bundle assumes Symfony’s console. For Laravel, create a wrapper command:

     // app/Console/Commands/DisparityDeploy.php
     public function handle() {
         $symfonyProcess = new Process(['php', 'app/console', 'disparity:deployment:migrate', $this->argument('target')]);
         $symfonyProcess->run();
         $this->output->write($symfonyProcess->getOutput());
     }
     

   • Namespace Collisions: Ensure Disparity\DeploymentBundle doesn’t conflict with Laravel’s autoloader.

5. Git Configuration:

   • The bundle requires a valid .git directory. Verify with:

     git rev-parse --is-inside-work-tree
     

Debugging Tips

• Verbose Output: Add -vvv to the command for detailed logs.
• Git Status: Check the working tree after migration:

  git status
  git diff HEAD
  

• Doctrine Events: Listen for postMigration events to debug migration failures.

Extension Points

1. Custom Migration Logic:

   • Override the MigrateCommand class to add pre/post-migration steps (e.g., cache clearing).
   • Example:

     // app/Disparity/DeploymentBundle/Command/CustomMigrateCommand.php
     class CustomMigrateCommand extends MigrateCommand {
         protected function postMigration() {
             Artisan::call('cache:clear');
         }
     }
     

2. Configuration:

   • The bundle may support disparity_deployment config keys (check Resources/config/config.yml if available).
   • Example:

     # app/config/config.yml
     disparity_deployment:
         clean_before_migrate: true
     

3. Event Listeners:

   • If the bundle dispatches events (e.g., disparity.deployment.migrated), create listeners in Laravel’s EventServiceProvider:

     protected $listen = [
         'disparity.deployment.migrated' => [
             \App\Listeners\LogDeployment::class,
         ],
     ];
     

---
```markdown
## **WARNING**
This package is **abandoned**. For production use, consider:
1. **Git Hooks**: [Disparity’s Git Hooks](https://github.com/Disparity/git-hooks) (recommended).
2. **Alternatives**:
   - Laravel: Use [`deployer`](https://deployer.org/) or custom Artisan commands.
   - Symfony: [`symfony/lock`](https://symfony.com/doc/current/components/lock.html) + Git scripts.