Envoyer Deploy Commands Laravel Package

Getting Started

This package is a small, focused set of Artisan commands designed to be invoked from Envoyer deployment hooks rather than from a developer's terminal — think cache clearing, migrations, queue restarts, and similar release-time chores.

Minimal path from zero to first deploy:

1. composer require log1x/envoyer-deploy-commands
2. Confirm the service provider was auto-discovered and the commands are live: php artisan list | grep -i envoyer (the package is small enough that php artisan list is the fastest ground truth — no publish step, no config file to hunt for).
3. Open the README's hook list, but treat the provider's commands() array as authoritative if the two ever disagree; this package has few moving parts and the source is quicker to read than the docs.
4. In Envoyer, open your project → Deployment Hooks and paste a single command into Activate New Release (or Deploy New Release, depending on which the README specifies for that command).
5. Deploy once and watch the output in Envoyer's deployment log. That log is the only feedback loop you get — there's no local "dry run" equivalent.

First use case: put the package's cache/optimization command in the post-activate hook, deploy a trivial change, and confirm from the log that it ran and that the app still boots. That one loop teaches you everything else about the package.

v1.1.4 is purely a compatibility release — it bumps dependencies to support Laravel 12. There are no new commands, no config changes, and nothing to migrate beyond your lockfile.

Implementation Patterns

Treat Envoyer hooks as a pipeline, not a checklist. The order that works reliably:

• Deploy New Release (code is cloned, .env and storage are symlinked in): run migrations and any build steps.
• Activate New Release (symlink swap): keep this near-instant; do not run long tasks here or you widen the window where the old and new release disagree.
• Post-activate / after activation: clear and rebuild caches, restart queue workers, ping anything that needs to know the release changed.

Run everything release-scoped. Hooks fire from {{release}}, so php artisan resolves the new code and the symlinked .env correctly. If a command needs an explicit cd, write cd {{release}} && php artisan ... rather than relying on the working directory — it costs nothing and removes a class of "worked locally, wrong release in prod" bugs.

Prefer the package's commands over hand-rolled shell. The value proposition is that someone already got the flags and exit codes right for Envoyer's non-interactive, no-TTY SSH session. Rolling php artisan cache:clear 2>&1 | tee in the hook panel re-introduces exactly the portability problems the package exists to solve.

Pair with Envoyer's built-in behaviour instead of duplicating it. Envoyer already handles the symlink swap, .env linking, and optional queue restarts. Wire the package's commands around those, not instead of them.

Keep a checked-in copy of your hook script. Envoyer's hook text lives in the UI and is invisible in code review. Mirror it in deploy/hooks.sh (or similar) in the repo and diff it when the package ships a release that changes command names.

For multi-environment setups, maintain separate Envoyer projects per environment and keep the hook text identical apart from the environment-specific bits. Divergent hooks between staging and production are the most common source of "staging deployed fine" surprises.

Gotchas and Tips

• Non-zero exit codes are the only failure signal. Envoyer marks a deployment failed on a non-zero exit. Commands piped into tee, or suffixed with || true, will silently green-light a broken release. Don't add either without a comment.
• Permissions are the number-one failure. Hooks run as the deploy user; if storage/framework/* or bootstrap/cache ends up root-owned (usually from a badly-behaved earlier step), cache commands fail in ways that only surface on the next request. Check ownership first when a deploy "succeeds" but the app 500s.
• config:cache timing is a trap. Caching config before .env is linked bakes in the wrong values — and it survives until the next cache clear. Cache config only in the post-activate hook, after the symlink swap.
• Queue workers don't reload. Old workers keep executing the previous release's code indefinitely. Always restart workers post-activate, otherwise you're testing two versions of your app in production simultaneously.
• No output doesn't mean no-op. Several Artisan commands print nothing on success. Read the exit code in the log, not the text.
• Debug by replaying over SSH. Before trusting a hook, SSH in, cd to the current release, and run the exact command by hand. If it works there but not during deploy, the difference is almost always the working directory or an unlinked .env.
• Laravel 12 note (v1.1.4): the only change is the dependency bump. After upgrading the framework, verify the provider still auto-registers (php artisan about or php artisan list) — package discovery regressions from a Laravel major are silent and only show up as a missing command at deploy time, which is the worst possible moment.
• Extension points are deliberately thin. There's no config file worth publishing and no event surface; the intended extension is to write your own Artisan command in the app and call it from the same hook alongside the package's commands. That keeps your logic version-controlled and reviewable, which is strictly better than growing the hook panel.
• Pin loosely, upgrade deliberately. ^1.1 is right here; this package's releases track Laravel's major versions rather than introducing API churn, so a routine composer update is usually safe — but always deploy once to staging after a framework major before touching production.