Getting Started

Minimal Setup

Installation:

composer require laravel/envoy --dev

Add the envoy.php config file via:

php artisan vendor:publish --provider="Laravel\Envoy\EnvoyServiceProvider"

First Use Case: Create a Envoy.blade.php file in your project root (or specify a custom path in envoy.php). Define a simple task:

@servers(['web' => ['host' => 'your-server.com']])

@task('deploy', ['on' => 'web'])
    cd /path/to/your/app
    git pull origin main
    composer install --no-dev --optimize-autoloader
    php artisan optimize
@endtask

Run it via:

php artisan envoy deploy

Where to Look First:
- Official Documentation (especially the Tasks and Servers sections).
- Example tasks in the Laravel Envoy repo (test files are often great references).
- The envoy.php config file for global settings (e.g., timeout, keep_alive).

Implementation Patterns

Core Workflows

Task Organization:
- Group related tasks into logical blocks (e.g., @task('deploy:database'), @task('deploy:code')).
- Use @servers to define environments (e.g., staging, production) with host-specific configurations:
```
@servers([
    'staging' => ['hosts' => ['staging.example.com']],
    'production' => ['hosts' => ['prod.example.com'], 'options' => ['port' => 2222']]
])
```
Reusable Task Logic:
- Extract common patterns into partials (e.g., _deploy-steps.blade.php):
```
@include('_deploy-steps')
```
- Use @env directives to conditionally include logic:
```
@env('production')
    php artisan cache:clear
@endenv
```

Artisan Integration:

Run Laravel commands remotely:

@task('migrate', ['on' => 'web'])
    php artisan migrate --force
@endtask

Pass arguments dynamically:

php artisan envoy migrate --env=production -- --seed

Parallel Execution:

Run tasks concurrently across servers:

@parallel
    @servers(['web-1' => ['host' => 'server1.com']])
    @task('restart-queue')
        php artisan queue:restart
    @endtask

    @servers(['web-2' => ['host' => 'server2.com']])
    @task('restart-queue')
        php artisan queue:restart
    @endtask
@endparallel

Environment Variables:

Use .env variables in tasks:

@task('deploy')
    cd {{ env('DEPLOY_PATH') }}
    git pull origin {{ env('BRANCH', 'main') }}
@endtask

Hooks for Pre/Post Actions:

Use @before and @after to wrap tasks:

@task('deploy', ['on' => 'web'])
    @before
        echo "Starting deployment..."
    @endbefore

    git pull origin main
    composer install

    @after
        echo "Deployment complete!"
        php artisan down --releases
    @endafter
@endtask

Custom SSH Options:

Override SSH defaults per server or task:

@servers(['web' => ['host' => 'server.com', 'options' => ['user' => 'deploy', 'key' => '~/.ssh/id_rsa']]])

Local Development Proxy:
- Use laravel/valet or laravel/homestead with Envoy for local task execution:
```
@servers(['local' => ['host' => 'homestead.app']])
```

Integration Tips

CI/CD Pipelines:

Trigger Envoy tasks from GitHub Actions, GitLab CI, or CircleCI:

# Example GitHub Actions step
- name: Deploy
  run: php artisan envoy deploy --env=production

Composer Scripts:

Add Envoy tasks to composer.json:

{
    "scripts": {
        "deploy": "envoy deploy --env=production"
    }
}

Run with:

composer deploy

Laravel Forge/Panel:
- Use Envoy to extend Forge/Panel deploy hooks by creating custom scripts in your repo.

Monitoring:

Log task output to a file for debugging:

@task('deploy')
    @before
        echo "=== DEPLOY STARTED ===" >> /tmp/deploy.log
    @endafter

Docker Integration:

Execute tasks inside containers:

@task('docker:restart')
    docker-compose restart web
@endtask

Gotchas and Tips

Pitfalls

Blade Syntax Conflicts:
- Avoid naming tasks/files with Blade-like names (e.g., if.blade.php) to prevent parsing errors.
- Use @verbatim for raw SSH commands with special characters:
```
@verbatim
    echo "This is a literal command with @symbols"
@endverbatim
```
Timeouts:
- Default timeout is 30 seconds. Increase for slow servers:
```
@servers(['slow' => ['host' => 'server.com', 'timeout' => 120]])
```
- Or globally in envoy.php:
```
'timeout' => 60,
```

SSH Key Management:

Ensure SSH keys are properly configured. Use ~/.ssh/id_rsa by default, but specify custom paths:
```
@servers(['web' => ['host' => 'server.com', 'key' => '~/.ssh/custom_key']])
```

For agent forwarding, use:

@servers(['web' => ['host' => 'server.com', 'options' => ['-A']]])

Permission Issues:
- Tasks run as the SSH user (default: current system user). Use sudo carefully:
```
@task('sudo-task')
    sudo chmod -R 755 /path/to/app
@endtask
```
- Prefer setfacl or configure permissions via deployment scripts.

Variable Scope:

Variables defined in @servers are not automatically available in tasks. Pass them explicitly:

@servers(['web' => ['host' => 'server.com', 'deploy_path' => '/var/www/app']])
@task('deploy')
    cd {{ $deploy_path }}
@endtask

Parallel Task Quirks:
- @parallel tasks run independently. Avoid shared state (e.g., modifying the same file).
- Order of execution is not guaranteed.

Debugging:

Enable verbose output with -v:
```
php artisan envoy deploy -v
```

Use @echo for debugging:

@task('debug')
    @echo "Current directory: $(pwd)"
@endtask

Windows Line Endings:
- Ensure tasks use LF line endings (Linux/Unix). Convert files with:
```
dos2unix Envoy.blade.php
```

Tips

Task Templates:

Start with a template for common deployments:

@servers(['web' => ['host' => 'server.com', 'deploy_path' => '/var/www/app']])

@task('deploy', ['on' => 'web'])
    cd {{ $deploy_path }}
    git pull origin {{ env('BRANCH', 'main') }}
    composer install --no-dev --optimize-autoloader
    php artisan config:cache
    php artisan route:cache
    php artisan view:cache
    touch storage/framework/cache/data/cache_tags
@endtask

Dry Runs:

Test tasks locally with ssh flags:

php artisan envoy deploy --env=production --ssh="ssh -vvv"

Environment-Specific Files:
- Use Envoy.blade.staging.php or `Envoy.blade.pro

Envoy Laravel Package