Laravel Envoyer Sdk Laravel Package

Product Decisions This Supports

Build vs. buy for release automation. This package is the cheapest possible answer to "do we need to build our own deployment tooling?" If we already deploy through Envoyer, a thin Composer dependency covers trigger-and-monitor workflows that would otherwise be scoped as an internal platform. It converts a potential roadmap item into an afternoon of integration work — or proves quickly that it can't, which is equally valuable.

Self-service release workflows as a product-adjacent feature. Concretely enabled: an admin "Deploy now" control, a per-project release status widget, deploy triggers from Slack or internal ops tooling, and post-deploy hook visibility — all without handing out Envoyer dashboard access or account-level tokens to teammates. These are small features that remove recurring support requests, and they belong in the backlog as such.

Roadmap validation for deployment visibility. If "show deployment status inside our product" is a candidate roadmap item, this is the cheapest spike available. It surfaces what Envoyer's API can and cannot express — rollbacks, approval gates, audit trails, multi-stage promotion — before we commit engineering time to a platform. The constraint it reveals is the scope boundary.

Feature triage and expectation-setting. Because the SDK is a resource wrapper and nothing more, it correctly frames deployment visibility as a small enabling feature rather than a CI/CD program. It caps scope honestly: anything Envoyer's API doesn't expose is out of scope for this approach, and stakeholders should hear that before, not after, the sprint starts.

Dependency posture as an explicit decision. v2.0.0 is a major bump driven solely by PHP 8 support — a runtime floor change, not new capability. That's an upgrade-and-pin decision for PHP 8 estates and a hold-at-1.4.x decision for PHP 7 ones. No feature negotiation involved, which makes it a fast, low-drama call.

Risk acceptance with a named boundary. Low adoption (39 stars, 0 dependents), single maintainer, last release 2022-05-31. Acceptable for convenience automation behind our own service class; not acceptable as an unmonitored path where production releases depend on it. Making that boundary explicit is itself a product decision, and one worth recording.

When to Consider This Package

Adopt when:

• You already deploy via Envoyer (or have it in active evaluation) and want deployments triggerable from a Laravel app, an Artisan command, a CI job, or an internal tool.
• You're on PHP 8.x on a supported Laravel line — pin ^2.0. On PHP 7.x, stay on ^1.4 until the runtime upgrade lands; don't combine both upgrades in one release.
• Your need is a narrow integration surface: list projects/servers, trigger a deployment, poll status, manage hooks. That is exactly the SDK's depth.
• You're prototyping internal deploy tooling and are comfortable wrapping a single-maintainer community package behind your own interface.
• The use case is low criticality — a manual deploy button, a status dashboard, a chat-ops trigger. Not an unattended release pipeline.

Look elsewhere when:

• You don't use Envoyer. Forge, Vapor, GitHub Actions, or a bespoke pipeline means zero value here on every axis.
• You need orchestration beyond Envoyer's API: rollback policies, approval gates, multi-stage promotion, audit trails. That's a platform build, not a wrapper.
• You require a vendor SLA or broad contributor base. 39 stars, zero dependents, last release 2022-05-31, and a v2.0.0 consisting of a single PHP 8 PR from a first-time contributor. Say this plainly in risk discussions rather than burying it.
• You need verified support for the current Laravel major. Roughly three years without a release means framework drift is unverified; a fork or local patch is a realistic outcome at the next upgrade.
• Deployment is already owned end-to-end by CI/CD and there's no product surface that benefits from in-app visibility.

How to Pitch It (Stakeholders)

For executives: This is a small, low-cost integration that lets our Laravel applications trigger and monitor Envoyer deployments directly. It buys us self-service releases and in-product deployment visibility without funding a deployment platform — and it doubles as the cheapest possible test of whether we ever need one. v2.0.0 is a PHP 8 compatibility release: it aligns the dependency with our runtime roadmap and adds no features. Risk is structurally contained: it sits behind our own service class, touches nothing outside deployment actions, is removable in days, and only matters for as long as we stay on Envoyer. Decision needed: confirm Envoyer is our deployment mechanism for the planning horizon, then approve the pin-and-upgrade.

For engineering: v2.0.0 raises the floor to PHP 8; the major version is a runtime break, not an API redesign, and the changelog documents nothing beyond that — read the diff for signature and strict-typing changes, especially in the Saloon/Guzzle layer, and run composer why after the bump. Recommended path: pin ^2.0 on PHP 8 (hold ^1.4 otherwise) and route every call through one injected EnvoyerDeployer service so no controller ever touches the SDK or the Envoyer API contract. Model a trigger as accepted, not deployed — track status as an enum with terminal states, never a boolean. Resolve project and server IDs from config rather than by name lookup, which costs a round trip and breaks silently on rename. Never call the API synchronously in a user-facing request path: queue it, keep triggers out of retried jobs so a timeout can't double-deploy, and guard with Cache::lock(). Cache read-only lists (projects, servers, collaborators) for a few minutes since the API is rate-limited. The token is account-scoped and can deploy every project the account owns — treat it as a production secret with a named owner, a rotation policy, and a revocation runbook. Validate on a branch against a throwaway Envoyer project with a real token; PHP 8 strictness fails at runtime, not at composer update. Ship a short runbook covering token rotation, stuck or failed deploys, rollback, and the upgrade checklist.