Laravel Deploy Operations Laravel Package

Product Decisions This Supports

• Build vs. buy for post-deploy automation. Today every Laravel deployment accumulates the same list of chores: cache clears, config/route/event caching, migrations, queue worker restarts, storage symlinks, feature-flag warmups, sitemap rebuilds. This package turns that list into a versioned, reviewable config file of operation classes executed by one artisan command. The buy decision is roughly a day of integration versus the recurring cost of bespoke shell scripts that only one engineer understands.
• Concurrency safety on overlapping deploys. 7.3.0 aligns --isolated presence semantics with Laravel core, so two releases firing operations at the same time are guarded the same way core guards overlapping commands. Combined with the now-configurable uniqueness lock duration for queued operation jobs, this turns "hope the hotfix deploy doesn't collide with the rolling deploy" into a tunable guard. Product decision: make overlap-safety an explicit requirement for release steps and set the lock TTL above our longest-running operation.
• Deploy-time budget vs. queue-time budget. The new ability to dispatch operations as queued jobs (with the dispatched job class overridable via queue.job) lets us move slow steps — search index warmups, sitemap rebuilds, external webhook fan-out — off the deploy critical path. Trade-off to decide consciously: a queued step is only as reliable as workers being up at deploy time, so anything an operation restarts (queue workers) must be ordered after the dispatch, and operations must stay idempotent because a queued step can be retried by the queue.
• Roadmap input: "release reliability" as a workstream. If we see failed releases, stale caches after deploy, or migrations run out of order, this is a cheap first lever before investing in a larger deployment platform. It gives us a place to put release steps and a shared vocabulary ("operations") that engineers and support can point at during an incident.
• Feature and use-case fit. Strongest for self-hosted/VM/Forge/Envoyer/Deployer/CI-driven Laravel apps where the team owns the release script. Weak for anything already orchestrated by Kubernetes jobs or a managed platform with native post-deploy hooks.
• Time-to-first-value and scope of change. Adoption is additive: one composer dependency, one config file, one extra line in the CI/deploy script. No data model changes, no infrastructure changes, no re-architecture — which makes it a low-risk item to slot into a sprint alongside other work.
• Self-serve deploys. Codifying release steps in PHP classes we can unit-test and code-review lowers the bar for letting more of the team ship, instead of routing every release through the one person who remembers the checklist.
• Deployment observability groundwork. If the package's release-metadata helpers are surfaced (release identifier/timestamp on a status page or in an ops endpoint), we get a cheap "what's actually running in prod?" answer — a prerequisite for support triage and for later rollback tooling. The queue.job override is a natural seam for wrapping dispatched operations with our own tracing/logging.
• Vendor/exit hygiene decision. MIT, no hosted service, no data lock-in; the main decision to make up front is to wrap it behind our own internal interface so operations remain ours and the dependency is swappable. The job-class override (rather than a fixed internal class) reinforces this: the execution mechanism is substitutable, not just the config.

When to Consider This Package

Consider adoption when all of the following hold:

• The product is a Laravel app whose deploy path we control (GitHub Actions/GitLab CI + SSH, Deployer, Envoyer, Forge, or a scripted release).
• We have a repeating post-deploy checklist that is currently prose, tribal knowledge, or shell snippets — especially if it has already caused a bad release.
• We have either long-running post-deploy steps worth queueing, or deploys that can overlap (hotfix during a rolling release) and want a supported isolation/locking story rather than hand-rolled flock files.
• The team is small enough that a formal deployment platform is overkill, and engineers are comfortable writing small PHP classes.
• We want release steps under code review and test coverage rather than a shell file outside the repo.
• We can pin a version and accept a single-maintainer dependency (243 stars, no tracked dependents) with a documented fallback.

Look elsewhere when:

• Zero-downtime orchestration is the actual problem. This package runs actions; it does not do atomic symlink swaps, health-gated cutovers, or rollback orchestration. Buy or build that layer, then call operations from it.
• The platform already owns post-deploy hooks. Envoyer, Forge, Kubernetes init/jobs, or a pipeline with artisan steps may already solve 90% of this; adding a package then buys us little beyond tidiness.
• We need fan-out, ordering guarantees across services, retries with backoff policies we control, or per-tenant releases. Queued operations give us per-app isolation and the queue's own retry behaviour — not a release orchestrator. At multi-service scale, buy that layer.
• There is no queue worker guaranteed to be running after deploy. The queued-operations path is only useful if workers are available when operations dispatch; otherwise we're adding a failure mode, not removing one.
• Multi-runtime estate. Non-PHP services in the same release need one coordinated story; a Laravel-specific tool fragments it.
• The team has no appetite for maintaining the operations themselves. The package is a runner, not a library of solutions — the work of deciding what to run and making each step idempotent stays with us.
• Compliance or support requirements demand a vendor with SLAs. Single-maintainer OSS is a real, if modest, risk to log in the dependency register.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can cut a category of "the deploy broke prod" incidents for roughly a day of engineering and zero licence cost. This is a small, MIT-licensed Laravel package that lets us define every post-deployment step — cache rebuilds, migrations, queue restarts — as reviewed, testable code instead of a shell script only one engineer understands, and run them with a single command from our existing pipeline. The latest release also means two deploys firing at once can't stomp each other, and slow steps can be pushed onto our queue so releases don't stall on a sitemap rebuild. It changes no infrastructure and no customer-facing behaviour; it reduces the chance that a release leaves the app in an inconsistent state and shortens the time to answer "what's actually running in production?" The main risk is that it's a small open-source project with one maintainer, so we'll pin the version and keep our release steps in our own code so it can be swapped out in a day if needed. Recommendation: pilot on one service next sprint, measure failed-release rate before and after.

For engineering (the short version): One composer dependency, one config file listing operation classes with a handle() method, and one artisan call appended to our deploy script. Each operation is plain PHP — unit-testable, lintable, code-reviewable — and should be written idempotent so re-runs are safe, which now matters more because operations can be dispatched as queued jobs and retried by the queue. Two new knobs to be deliberate about: queue.job (swap in our own job class to wrap operations with tracing/metrics) and the uniqueness lock duration (set it above our longest operation so an overlapping hotfix deploy can't start a second copy of a slow step). Note the --isolated behaviour fix in 7.3.0: it now matches Laravel core's presence semantics, so if any pipeline currently passes an explicit --isolated value, verify the effective behaviour before and after the upgrade rather than assuming it's unchanged. We keep our operations in our own namespace and treat the package as a runner behind an internal interface, so we're not married to it. It composes with Deployer/Envoyer/CI as a final step rather than replacing them; if we later need zero-downtime cutover or rollback orchestration, that's a separate layer and this still fits underneath it.