Bfc Client Laravel Package

Product Decisions This Supports

• Build vs. buy for cloud identity plumbing: this package is the client half of a two-sided contract (artisan-build/built-for-cloud server, ^0.12.3 wire). It removes from your roadmap the work of defining, versioning, and debugging a client-ID / contract-version handshake — you inherit a canonical contract instead of inventing one.
• Feature work that depends on verified client identity: anything gated on "which app/instance is calling us" — entitlement checks, per-tenant provisioning, metered usage, instance health dashboards — can now assume a single canonical client ID per request rather than case-variant header duplicates.
• Co-installation as a first-class architecture decision: because the cross-package dont-discover of the server provider is gone, a host can run both the client and the server in one Laravel app and get normal provider discovery. That unlocks the "single deployable, both roles" topology without custom service-provider surgery — a genuine roadmap option that previously required a fork or manual registration.
• Diagnostics and support-cost budgeting: the proof-of-life route gives support and on-call a one-request "is the client wired up at all?" check, which shrinks the class of tickets that arrive as "the integration is broken" but are actually misconfiguration.
• Race-safe persisted identity as a reliability commitment: identity that survives concurrent bootstraps means you can run this under Octane, horizon workers, or multi-pod scale-out without a "two clients, two identities" incident class. It raises the ceiling on how aggressively you can autoscale the client side.
• Deprecation/migration line item: the discovery exclusion removal is a behavior change on a minor bump. For any host that leaned on that exclusion — e.g. to intentionally suppress the server provider — this becomes a small but mandatory upgrade task in the next sprint, not a drop-in.

When to Consider This Package

Consider it when:

• You are building against the Built for Cloud platform and need the client side of the auth contract; the server package alone doesn't give you a conforming caller.
• You need canonicalized, contract-versioned outbound requests — one client ID, one contract version, no case-variant duplicate headers — and you'd rather not hand-roll that normalization.
• Your host co-installs client and server roles in a single Laravel application. This release specifically fixes that topology.
• You need identity that is safe under concurrency (shared hosting is fine; Octane, queue workers, and horizontally scaled replicas are the real justification).
• You want a cheap liveness signal (proof-of-life route) for smoke tests and post-deploy verification, plus a local install-file utility you can run without network dependencies.
• You are comfortable pinning to a paired server version (^0.12.3) and tracking that pin as a coupled upgrade.

Look elsewhere when:

• You are not on the Built for Cloud wire at all — the whole value proposition is contract conformance; standalone there is nothing here.
• You need a server-side auth authority; this is explicitly client-only.
• You require a stable 1.0 API surface. At v0.2.0 with behavior changes shipped as a minor bump, the contract and its packaging are still settling; if your release cadence can't absorb "minor version, changed behavior," wait.
• You have a host that deliberately relied on the old discovery exclusion to keep the server provider unregistered, and you cannot change that. Upgrading breaks you; stay pinned and plan the migration.
• You need multi-language or non-PHP clients — this is a Laravel/PHP-shaped solution.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, focused dependency that lets our Laravel services talk to the Built for Cloud platform using a shared, versioned contract instead of a bespoke integration we'd own and maintain. The v0.2.0 release hardens identity handling — one canonical client identity per request, safe under concurrent and scaled deployments — and removes a discovery conflict so a single application can act as both client and server. That last point widens our deployment options and reduces the number of moving parts in our architecture. Cost is low; the main obligation is that we treat upgrades as coupled to the server package version and budget a short migration for the discovery change.

For engineering: Two things to know. First, this is a client-only package pinned to the built-for-cloud ^0.12.3 wire; treat the pair as one upgrade unit and version-lock them together. Second, the minor bump contains a behavior change: the cross-package dont-discover of the server provider has been removed, so co-installed hosts now register BuiltForCloudServiceProvider through normal discovery. If any environment depended on that provider staying suppressed, it will start booting after upgrade — audit for it before rolling out. Upside: canonical header emission (case variants stripped pre-send), byte-stable field-value handling for the client identity, race-safe persisted identity, a pure-local install-file utility, and a proof-of-life route you can wire into smoke tests. Net: less custom auth plumbing, one less bespoke contract to own, and a known, small migration.