Flink Sdk Php Laravel Package

Getting Started

• Install with composer require mohemian/flink-sdk-php:0.1.0 and pin the exact version — this is the first tagged release, so treat the public API as unstable.
• Look first at PR #1 ("verify an embedded journey's signed ID Austria prefill") and the package's tests. As of v0.1.0 there is no long-form documentation beyond the release notes, so the verification class/method and its test cases are the de facto spec.
• Check whether the package ships a service provider with auto-discovery (composer.json → extra.laravel.providers). If so, expect a publishable config: php artisan vendor:publish --tag=flink-config. If not, you will likely construct the client manually or bind it yourself.
• Populate environment variables before first use. Expect something along the lines of FLINK_BASE_URL, FLINK_API_KEY/client credentials, and a signing/secret value used for prefill verification. Confirm the exact names in the config file or constructor signature.
• First use case: receiving an embedded Flink journey callback containing an ID Austria–signed prefill, verifying that signature via the SDK, and persisting the verified identity data. Start by writing a failing feature test that feeds a captured signed payload through the SDK's verify method, then wire the controller.

Implementation Patterns

• Adapter, not direct calls. Bind a FlinkClient interface in a service provider and implement it with a thin wrapper around the SDK. This package is at 0.1.x; you want one file to change when the API shifts, not every controller.
• Verify raw, then parse. The signed prefill should be verified against the exact bytes received. In Laravel, read $request->getContent() (or the raw body captured by middleware) and hand that to the SDK before any casting, validation, or JSON re-encoding. Only after verification succeeds should you hydrate a DTO.
• Callback flow: route → form request (light validation only) → VerifySignedPrefill action → domain event (IdAustriaPrefillVerified) → listener persists profile data. Keep the controller to a few lines.
• Idempotency. Embedded journeys and identity callbacks can be retried. Store the signed payload's identifier/jti (if present) or a hash of the raw body and short-circuit duplicates in the action.
• Testing. Fake the SDK behind your interface for feature tests. For the SDK's own HTTP calls, use Http::fake() if it is built on the Laravel HTTP client; otherwise register a Guzzle MockHandler. Keep at least one contract test using a real captured payload so a dependency bump cannot silently break signature verification.
• Queue the network work. If verification performs a remote call (JWKS fetch, token exchange), dispatch it on a queue and respond to the callback quickly; upstream identity providers tend to have short timeout budgets.
• Environment separation. Keep sandbox and production base URLs/credentials in separate config keys and never share the signing secret between them.

Gotchas and Tips

• No BC guarantee at 0.1.0. Pin "mohemian/flink-sdk-php": "0.1.0" and read the changelog before every bump. The release only covers prefill verification plus packaging, so broader client surface is not yet proven.
• Signature verification is byte-sensitive. JSON re-serialization, TrimStrings/ConvertEmptyStringsToNull middleware, or a proxy that rewrites the body will invalidate signatures. Verify in middleware or read the raw content early, and exclude the callback route from body-mutating middleware if needed.
• Personal data. ID Austria prefill payloads contain identity data. Do not log raw payloads, do not put them in exception messages, and scrub them from failed-job payloads — GDPR applies.
• Clock skew and key rotation. If the signed prefill includes a timestamp or is verified with a public key, allow a small leeway and cache keys with a TTL rather than fetching per request.
• Error surface is thin. Expect generic exceptions from a 0.1.x SDK. Catch at the adapter boundary and map to domain exceptions (PrefillVerificationFailed, FlinkUnavailable) so callers and monitoring stay meaningful.
• No facade assumption. If there is no Flink facade or config publishing, resolve the client through the container yourself; do not reach for app() inside domain code.
• Debugging. If the SDK exposes a logger or debug flag, route it to a dedicated channel. Otherwise attach Http::globalMiddleware() or a Guzzle middleware to observe outgoing requests without touching vendor code.
• Extension points are minimal by design. Prefer composition (your adapter, your DTOs, your events) so upstream additions are additive rather than invasive.