Deployer Recipes Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alpixel/deployer-recipes
   

   Ensure your project uses Deployer (v4+ recommended) as the base deployment tool.

2. First Use Case: Basic Recipe Integration Add the package to your deploy.php:

   require 'vendor/alpixel/deployer-recipes/recipes.php';
   

   Use a pre-built recipe (e.g., Laravel, Symfony) as a starting point:

   use Alpixel\DeployerRecipes\Recipes\LaravelRecipe;
   
   $recipe = new LaravelRecipe();
   $recipe->deploy();
   

3. Where to Look First

   • Browse vendor/alpixel/deployer-recipes/src/Recipes/ for available recipes.
   • Check vendor/alpixel/deployer-recipes/README.md for quick-start examples.
   • Review the Deployer docs for core deployment concepts.

Implementation Patterns

Workflows

1. Recipe-Based Deployment Extend or override default recipes:

   $recipe = new LaravelRecipe();
   $recipe->set('shared_files', ['app/.env']);
   $recipe->set('shared_dirs', ['storage']);
   $recipe->deploy();
   

2. Custom Recipe Creation Build a new recipe by extending Alpixel\DeployerRecipes\BaseRecipe:

   namespace App\Recipes;
   
   use Alpixel\DeployerRecipes\BaseRecipe;
   
   class CustomRecipe extends BaseRecipe {
       public function deploy() {
           $this->task('deploy:custom')->run();
       }
   }
   

3. Integration with Deployer Tasks Chain recipes with Deployer’s native tasks:

   task('deploy', [
       'deploy:prepare',
       function() {
           $recipe = new LaravelRecipe();
           $recipe->deploy();
       },
       'deploy:cleanup'
   ]);
   

Tips for Daily Use

• Environment-Specific Configs Use Deployer’s set() to override recipe defaults per environment:

  host('prod.example.com')
      ->set('recipe', new LaravelRecipe())
      ->set('recipe->deploy_path', '/var/www/prod');
  

• Shared Assets Leverage shared_files/shared_dirs for persistent files (e.g., .env, node_modules):

  $recipe->set('shared_files', ['app/.env.local']);
  

• Post-Deploy Hooks Attach custom tasks after recipe execution:

  $recipe->after('deploy', function() {
      run('php artisan cache:clear');
  });
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch The package requires PHP ≥5.5.0, but Deployer v4+ works best with PHP ≥7.2. Test locally with your target PHP version.

2. Recipe Overrides Not Persisting Ensure set() is called before deploy():

   // ❌ Won't work
   $recipe->deploy();
   $recipe->set('shared_dirs', ['storage']);
   
   // ✅ Correct
   $recipe->set('shared_dirs', ['storage']);
   $recipe->deploy();
   

3. Missing Dependencies Some recipes (e.g., Laravel) assume tools like composer, npm, or php artisan are available. Add them to your deploy.php:

   set('bin/composer', function() {
       return __DIR__ . '/vendor/bin/composer';
   });
   

Debugging

• Enable Verbose Output Run Deployer with -v to debug recipe execution:

  deploy -v
  

• Check Recipe Logs Inspect vendor/alpixel/deployer-recipes/src/Recipes/ for hardcoded paths or tasks that may fail silently.

Extension Points

1. Custom Tasks in Recipes Override methods like deploy(), rollback(), or warmup() in your extended recipe.

2. Dynamic Recipe Selection Use Deployer’s get() to switch recipes per environment:

$recipe = get('recipe') ?: new LaravelRecipe();

3. Recipe Validation Add pre-deploy checks:

$recipe->before('deploy', function() {
    if (!test("[ -f composer.json ]")) {
        throw new \RuntimeException("composer.json not found!");
    }
});

Config Quirks

• Default Values Some recipes use Deployer’s built-in defaults (e.g., deploy_path). Override them explicitly if needed:

  set('deploy_path', '/custom/path');