Php Deploy Laravel Package

Getting Started

• Install and locate the config. composer require umbrellio/php-deploy then look for the package's config stub under vendor/umbrellio/php-deploy/ (check config/ or a config.php/deploy.php in the package root) and copy it into your project (config/deploy.php or equivalent). The README is thin; the config stub and the example scenarios shipped with the package are the real documentation.
• Fill in the five things every deploy needs: target hosts, SSH user/port and key path, the repository/branch to pull, the base deploy path (which will contain releases/ and current), and the shared paths (.env, storage/, public/uploads, etc.). These map directly to the release-directory + symlink model the package is built around.
• First use case — safe deploy with rollback. Deploy a Laravel app once, confirm you get releases/<timestamp>/ plus a current symlink, then make a trivial migration, deploy again, and run the package's rollback command. Verify the migration is reversed and current points back to the previous release. This one exercise teaches you everything the package is for: rolling back migrations between releases, not just code.
• Read the source before trusting it. With 2 stars and 0 dependents, skim the step classes (Clone, Symlink, RunCommand, migration steps) in vendor/ so you know exactly what each step shells out over SSH. Budget an hour; it saves a lot of guessing later.

Implementation Patterns

• Compose a scenario, don't script a shell file. Build a Laravel-shaped scenario as an ordered list of steps, roughly:
  1. create release dir (timestamped)
  2. git clone / git archive the target ref into it
  3. symlink shared files/dirs (.env, storage, public/storage)
  4. composer install --no-dev --optimize-autoloader
  5. php artisan migrate --force
  6. php artisan config:cache && php artisan route:cache && php artisan view:cache
  7. switch current symlink atomically (ln -sfn)
  8. php artisan queue:restart Keep each step small and idempotent so a failure mid-scenario leaves a clear resume point.
• Separate deploy and rollback scenarios. The rollback scenario should switch the symlink back to the previous release and then run the matching down-migrations — that ordering is the whole point of the package. Roll back the migration before flipping current back if your down() relies on the old code, or after if it doesn't; decide once and encode it.
• Environment-specific configs. Keep one scenario config per environment (staging, production) that differ only in host, branch, and shared paths. Share the step list; vary the parameters. This keeps the risky bits (which host) obvious in review.
• Run it from CI, not laptops. Wire the deploy command into your pipeline after tests pass, using a dedicated deploy key. Keep a manual "rollback" job in the pipeline so an on-call engineer can revert a bad release without shelling into a box at 2 a.m.
• Custom steps for Laravel-specific work. Where the package's built-in steps don't cover you (e.g., php artisan down/up, horizon:terminate, FPM reload), extend the step base class or use the generic "run remote command" step rather than adding pre/post hooks in bash — it keeps everything in one scenario file and reviewable.
• Treat the shared storage/ dir as the source of truth. Everything stateful (logs, sessions, uploaded files, compiled views if you cache them) must be symlinked from the shared dir before the symlink switch, otherwise a rollback silently discards logs you'll want during the postmortem.

Gotchas and Tips

• Rollback migrations are the sharp edge. down() methods must be genuinely reversible and non-destructive. If a migration drops a column, the "rollback" loses data. Audit each migration's down() before relying on the package's rollback flow; add "deploy N-1 → deploy N → rollback → deploy N" to your staging checklist.
• Migrations that changed between releases. Because you're rolling back between releases, the package has to know which migrations belong to which release. Confirm how it tracks this (likely by running migrate:rollback --step=N or comparing migration file sets in releases/). If it derives the step count from a git diff, a squashed or renamed migration file will confuse it — never rename/delete an already-deployed migration.
• .env is not in the release. Laravel reads .env from the release directory on config:cache. Make sure .env is symlinked from shared before the artisan caching steps run, or the deploy will cache an empty config and the site will 500 on the next request.
• Config/cache are per-release, not shared. bootstrap/cache/*.php must live inside each release, not in shared, or rolling back to old code with new cached config causes Class not found errors. Conversely, config:clear before config:cache in the same release.
• Permissions are the classic post-deploy failure. Files created by the SSH user during deploy (composer install, config:cache) may be unreadable by the web user, and storage dirs may be unwritable. Set ownership/perms as an explicit step after the symlink switch, and verify as the FPM user, not your deploy user.
• Symlink swap is not zero-downtime by itself. ln -sfn is atomic, but existing FPM workers keep serving the old release until they recycle. Add systemctl reload php8.x-fpm (or kill -USR2 on the FPM master) and an OPcache reset step, or you'll deploy "successfully" and still run old code for minutes. queue:restart similarly needs the queue supervisor to be running.
• Debugging a failed step: re-run the scenario with maximum verbosity if supported, or SSH in and inspect releases/ — failed releases are usually left behind and visible. Confirm the failure is on your step (e.g., composer) vs. the package's (clone/symlink) before reading further. Check the SSH command it emitted; quoting bugs in remote commands are the most common package-level fault in small deploy tools.
• Version pinning and staleness. With a single maintainer, 2 stars, and a future-dated 5.0.0 release note that only says "bump laravel and php," pin an exact version ("umbrellio/php-deploy": "5.0.0"), read the source, and be ready to vendor/fork it. Don't float ^5.0 in CI without a lock file, and don't expect the changelog to warn you about behavioural changes.
• Extension points to verify after any version bump: the config schema keys, the step base class signature, and the exact names of the rollback/migrate steps. Small packages like this rename config keys between majors without an upgrade guide. Keep your published config in version control and diff it against the new package default after upgrading.