Laravel Plugin Laravel Package

Product Decisions This Supports

• Roadmap sequencing for integration-heavy features. If the next two quarters depend on third-party APIs (payments, CRM/ERP sync, logistics, KYC, LLM providers), this package is the scaffolding decision that determines whether each integration is a 2-week story or a 6-week one. php artisan saloon:connector / saloon:request / saloon:response / saloon:auth generate the class skeleton (including --oauth and selectable HTTP verbs), so the team starts at the connector contract rather than at Guzzle boilerplate.
• Build vs. buy on integration plumbing. The real question a PM faces is "do we own an internal HTTP abstraction?" With Saloon the answer is no for ~80% of cases: connectors, request/response classes, auth, retries, pagination, and rate limiting come from the base package. The Laravel plugin is the cheap adapter that makes it native to the framework (config, container, mocking). Decide not to build a homegrown API client layer.
• Testability as a release-gating strategy. Saloon::fake() / global mock client support means external-API features can be covered in CI without hitting sandboxes or burning provider rate limits. That's a direct lever on release confidence and flakiness in the pipeline — a PM-visible quality metric, not just an engineering nicety.
• Observability roadmap for outbound traffic. The plugin ships first-party Telescope and Pulse integrations plus Nightwatch middleware and a fix for correctly rendering HAL+JSON responses. Outbound API calls are usually invisible in Laravel monitoring today; adopting this makes them traceable in the same dashboards the team already watches. That is a MTTR and incident-comms decision, and it should be scoped as an observability workstream, not bundled silently into feature work.
• Onboarding and AI-assisted development. The package ships Laravel Boost guidelines and a saloon-development agent skill, and v3.11+/v4 added an ide.json for IDE code generation. Concretely: new hires and AI pair-programming tools produce idiomatic connector code from day one instead of a fifth hand-rolled HTTP wrapper. Weigh this against documentation debt in the platform team's roadmap.
• Reducing "integration inventory" risk. saloon:list enumerates integrations, and saloon:connector now suggests existing integrations plus resolves the configured integrations_path. That's the seed of a discoverable integration catalog — useful for audits, vendor-deprecation planning, and answering "what third parties can see our customer data?" in a security review.
• Breaking-change budget on the roadmap. Release history shows v2 → v3 → v3.x → v4 → v5 in a compressed window, with Laravel 10/11/12/13 compatibility chases. Every major Saloon bump is a scheduled engineering line item. Approve adoption only with an explicit "upgrade tax" allowance per year (see next section).

When to Consider This Package

Adopt when all of these hold:

• You are on Laravel 10+ with a current PHP version (8.5 support landed in 3.6.1; minimum was raised to Laravel 10 in v3.1.0) and the framework is already the team's default.
• You have three or more distinct external APIs in the next 12 months, or one that is business-critical and needs auth, retries, pagination, and rate limiting. Below that threshold the abstraction cost outweighs the payoff.
• You want outbound calls to appear in Telescope/Pulse the team already operates, rather than building bespoke logging.
• Your testing strategy depends on deterministic mocking of third-party responses in CI.
• You accept semantic-versioning churn: the plugin tracks Saloon majors closely, so pin versions, read changelogs, and budget upgrade time.
• You're standardizing on a convention over configuration style — one folder of app/Http/Integrations/* that any engineer can navigate.

Look elsewhere when:

• Non-Laravel or polyglot backend. Saloon is PHP-first; the plugin adds nothing outside Laravel. Use the provider's official SDK or a language-neutral gateway.
• You need only one or two trivial API calls. A thin Guzzle wrapper or the vendor SDK is cheaper than introducing a new architectural convention.
• Strict vendor-SDK parity is required. If the provider publishes a first-party PHP SDK with features Saloon must emulate (webhook signature verification, complex streaming, generated models), the official SDK wins.
• You need a managed integration platform (iPaaS, connector marketplaces, non-engineer-authored flows). This is a code-level tool for engineers; it does not remove integration ops work.
• Adoption signal is a hard gate. The plugin repo shows a modest star count and thin dependent footprint — that is not a proxy for base-package health, but it does mean fewer blog posts, Stack Overflow answers, and third-party tutorials than mainstream Laravel packages. If your team relies on external references over reading source, factor in the ramp-up.
• You need long-term-support guarantees. This is a volunteer-maintained MIT package with no commercial SLA. If the integration layer is on a regulated or revenue-critical path, plan for a named internal owner and a fork-or-replace exit.

How to Pitch It (Stakeholders)

For executives — one paragraph: We're proposing a small, MIT-licensed Laravel plugin that standardizes how our application talks to third-party APIs. It doesn't add a new vendor or cost; it replaces hand-written HTTP code with a consistent, testable pattern, generates the boilerplate for each new integration via Artisan commands, and pipes outbound calls into the monitoring tools we already run. The business impact is delivery speed on integration-heavy roadmap items, fewer production incidents from poorly instrumented API calls, and lower onboarding cost — with the main trade-off being a recurring maintenance cadence as the underlying library ships new major versions.

For engineering — the practical case:

• One pattern, not five. Connectors and request/response classes become the only sanctioned way to call an external service. Code review gets a checklist instead of an argument.
• Scaffolding is free. saloon:connector, saloon:request (with HTTP-method selection), saloon:response, saloon:plugin, saloon:auth (--oauth), plus saloon:list for inventory. integrations_path is honored, including paths outside app/.
• Testing is first-class. Global mock client via Saloon::fake(); note the legacy MockClient path is deprecated in favor of the global mock client. Plan the test-suite migration accordingly.
• Observability is included, not bolted on. Telescope and Pulse integrations, Nightwatch middleware (with a guard against double-registration), and correct rendering of HAL+JSON and integer-body-with-JSON-content-type edge cases.
• AI/IDE support. Laravel Boost guidelines, a saloon-development agent skill, and ide.json — relevant if we're investing in AI-assisted development.
• Risk to own explicitly: volunteer maintenance, no SLA, fast major-version cadence (v2 → v5 across the release history, with Laravel 10/11/12/13 compatibility churn). Mitigation: pin to a tested minor, assign a named owner, and treat Saloon upgrades as planned work in each half rather than reactive firefighting.

Decision requested: approve a time-boxed pilot on the next integration (target: one connector end-to-end with Telescope/Pulse visibility and mocked CI tests), then a go/no-go on standardizing the pattern repo-wide — measured by time-to-first-working-connector, incident MTTR on outbound calls, and integration test flakiness.