Bfc Client Laravel Package

Getting Started

Install the client-only package and let Laravel discover its provider:

composer require artisan-build/built-for-cloud:^0.2.0

Start with these files/areas:

1. config/built-for-cloud.php — client ID, contract version, persisted identity path, and install-file settings.
2. The package service provider — confirm BuiltForCloudServiceProvider is registered. In v0.2.0 the cross-package dont-discover exclusion was removed, so co-installed hosts now discover it normally.
3. The unified auth client contract — this is the main entry point for outbound requests to the Built for Cloud P6 wire.

First use case: make a single authenticated client request and verify it with the proof-of-life route. Use the package’s client contract rather than hand-building headers. The client sets one canonical client-ID and contract-version header per request; it strips case variants before sending.

Minimal smoke test:

use ArtisanBuild\BuiltForCloud\Contracts\BuiltForCloudClient;

$client = app(BuiltForCloudClient::class);

$response = $client->get('/proof-of-life');

$response->assertOk();

If the proof-of-life route is exposed by the package, hit it through your app to confirm identity persistence and header construction are working.

Implementation Patterns

Use the contract, not raw HTTP. Resolve BuiltForCloudClient from the container and let it own header construction, client identity, and contract version. Avoid adding Client-ID, client-id, or contract headers manually; v0.2.0 normalises and removes case variants before send.

Treat identity as package-managed state. Client identity is persisted race-safely. Do not read/write the identity file directly in normal application code. If you need to inspect it for debugging, read it only; let the package create or repair it.

Use the install-file utility for local setup. The install-file utility is pure local file handling. Use it for local developer bootstrap, CI setup, or test fixtures — not as a remote provisioning mechanism. Keep generated install files out of version control unless your workflow explicitly requires them.

Wire the proof-of-life route into health checks. The proof-of-life route is the quickest way to verify that the client can reach the P6 wire with a valid contract version and identity. Add it to local smoke tests or a non-production health check.

Co-installation pattern. If you also run the server-side artisan-build/built-for-cloud provider, v0.2.0 expects both providers to be discovered normally. Do not add a dont-discover entry for BuiltForCloudServiceProvider unless you deliberately want to suppress it.

Integration tip: one client per request lifecycle. Because the client enforces one canonical header set per request, avoid reusing a client instance across requests with mutated identity. Resolve it per request/job as you would any Laravel singleton with request-scoped state.

Gotchas and Tips

• Discovery behaviour changed in v0.2.0. The package no longer excludes the server provider via dont-discover. Hosts that relied on that exclusion will now discover BuiltForCloudServiceProvider. If you need the old behaviour, add an explicit dont-discover entry in your application’s composer.json and test provider boot order.
• Header case is normalised for you. Do not add client-ID, Client-Id, or similar variants. The client removes case variants before sending; duplicate or conflicting headers are a common source of wire failures.
• Client identity follows the byte-stable HTTP field-value rule. Avoid trimming, re-encoding, or rewriting the persisted identity. If you see identity mismatches, check for code that is reading and re-writing the identity file.
• Race-safe persistence is not a licence to edit the file. Concurrent workers are handled by the package. Manual edits during runtime can still corrupt state. Clear and regenerate identity through package tooling if needed.
• The install-file utility is local-only. It is useful for local onboarding and CI, but it does not provision remote hosts. Do not ship generated install files as secrets.
• Proof-of-life route exposure. If the route is registered publicly, restrict it in production or rely on network controls. It is intended as a connectivity/identity check, not an authenticated business endpoint.
• Debugging checklist: confirm the provider is discovered, confirm the config has a canonical client ID and contract version, inspect the outbound request headers (exactly one client-ID and one contract-version header), then hit the proof-of-life route. If co-installed with the server package, confirm both providers boot without conflict.
• Minor version, real behaviour change. Although v0.2.0 is a minor bump, the discovery change is behavioural. Review composer.json discovery config and provider registration before upgrading production hosts.