Php Laravel Package

Technical Evaluation

Architecture fit. Whisperr is a server-side event SDK for Laravel, and v0.3.0 aligns it to the Whisperr spec contract v2 — the same contract that presumably governs the other server SDKs. The changes are additive and sit cleanly in the SDK's existing surface: track() and publish() gain two reserved context keys (sdk_name, sdk_version), a new app-level app_version option is threaded through both the Laravel config/env path and per-event context, and a new Whisperr\BillingEvent helper introduces typed constants plus a validated property builder for the reserved billing fallback names defined in the playbook engine spec §3.8. Nothing in the release changes delivery semantics, transport, or the public method signatures that existing callers rely on.

Integration feasibility. Low effort for consumers. sdk_name/sdk_version are automatic and require no application change. app_version is opt-in via WHISPERR_APP_VERSION; when unset, the key is omitted rather than sent as null, which keeps payloads clean and avoids downstream schema churn. Per-event $context continues to take precedence, so teams with bespoke version tagging are not forced onto the new config. The BillingEvent constants are the highest-leverage addition: they replace hand-typed string literals (a recurring source of drift between product, billing, and analytics) with named symbols, and BillingEvent::properties() enforces currency shape (ISO 4217, three letters, upper-cased) and price sanity (non-negative, finite, major units) at the call site rather than in the warehouse. The validation is fail-fast with InvalidArgumentException, which is the right default for billing telemetry but does mean an unguarded call can now throw inside a request path.

Technical risk. Three areas to watch. First, exception surface: any code path that constructs billing properties from externally supplied values (store callbacks, webhook handlers, admin tooling) must be prepared to catch InvalidArgumentException; previously, malformed data may have been passed through silently. Second, version-skew: emitting sdk_version from Whisperr::VERSION means downstream consumers can now segment by SDK version — useful, but it exposes release cadence to analytics and may reveal older pinned installs. Third, conformance coupling: tests executing the server sections of whisperr-spec conformance/v2.json tie the package's release quality to an external spec artifact; that is a strength for cross-SDK consistency but an external dependency for CI stability if the spec repo is fetched rather than vendored.

Key questions. (1) Is conformance/v2.json vendored or fetched at test time, and is the spec version pinned? (2) Is there a config-publish/cache-clear path for WHISPERR_APP_VERSION, or is it read directly from env() (a known footgun under config:cache)? (3) Does BillingEvent::properties() accept extra properties without colliding with reserved keys, and what is the precedence rule? (4) Are the billing fallback events documented as fallbacks — i.e., emitted only when the playbook engine has not named the event — or as canonical names? Misreading that in implementation would create duplicate event streams. (5) Is price in major units consistent with what the existing event pipeline and warehouse expect, and is there a migration note for anyone sending minor units today?

Integration Approach

Stack fit. The package targets Laravel's standard configuration idioms: an env-driven option (WHISPERR_APP_VERSION) surfaced through a config file, plus service-container resolution implied by Whisperr::VERSION. That is idiomatic and integrates without adapters. The BillingEvent helper is framework-agnostic PHP, so it is equally usable from queued jobs, console commands, and webhook controllers — the three places billing events are actually emitted.

Migration path. This is a non-breaking, additive release. Recommended sequencing: (1) upgrade the dependency and run the existing test suite to confirm the new sdk_name/sdk_version context keys do not break snapshot or contract assertions; (2) set WHISPERR_APP_VERSION in each environment's deploy configuration (CI/CD variable, not committed .env), then verify the key appears on events and that it is absent — not null — where unset; (3) adopt BillingEvent constants incrementally, starting with the highest-volume paths (trial lifecycle, renewals) and only then the rarer ones (refund, billing recovery); (4) adopt BillingEvent::properties() on new code first, backfilling existing call sites as they are touched. No data migration, no schema change, no coordination window with other teams.

Compatibility. Requires the spec v2 contract on the receiving side; teams pointing at a v1-only ingestion endpoint should confirm the server tolerates the two new context keys before rollout (most implementations ignore unknown keys, but validate). The app_version omission-when-empty behavior is the compatibility-friendly choice and should be explicitly preserved in any downstream schema. Existing $context overrides keep working. The one behavioral change to flag in release notes for app teams is the new throwing validation on billing properties.

Sequencing against the broader platform. If sibling SDKs (Node, Python, Go) are rolling to spec v2 in the same window, sequence this package early — it is low-risk and gives the platform team a reference implementation against the conformance fixtures. Hold any dashboards or alerts keyed on plan_id/price until the major-units convention is confirmed and backfilled, and coordinate the reserved billing names with the playbook engine owners so fallback emission and canonical emission cannot both fire for the same lifecycle transition.

Operational Impact

Maintenance. Ongoing cost is low but non-zero: the package now carries an external contract dependency (spec v2, conformance/v2.json) and a reserved-name surface (BillingEvent constants) that must track the playbook engine spec. Establish a named owner for spec bumps; when §3.8 gains or renames a fallback event, this package needs a released constant and a conformance update. Treat the billing constant list as a published API — deprecate, do not delete.

Support. Expect two categories of tickets. First, "why is app_version missing from our events" — almost always an unset env var or a config:cache staleness issue; document the cache-clear step prominently. Second, InvalidArgumentException from BillingEvent::properties() surfacing in production after a bad upstream value (a non-ISO currency code from a payment provider, a negative price after a credit). The message should name the offending field and value; if it does not, that is worth a follow-up. Because the exception fires in the request path, ensure the failure is logged and alerted rather than swallowed, and that a dropped billing event does not silently break reconciliation.

Scaling. No scaling concern from these changes — no new I/O, no additional network calls, and the added context is a handful of bytes per event. The only scale-adjacent consideration is cardinality: sdk_version and app_version become new dimensions in the analytics store. Both are bounded and low-cardinality per deploy, so this is safe, but confirm the ingestion pipeline does not auto-explode unknown context keys into high-cardinality indexes.

Failure modes. (1) Unset or stale WHISPERR_APP_VERSION → silent absence of a key the team believes is being sent; mitigate with a smoke assertion in staging. (2) Unguarded BillingEvent::properties() call on webhook input → uncaught exception in a payment callback; wrap and fall back to emitting the event without the enriched properties, or defer enrichment. (3) Reserved-name drift between the playbook engine and the constants → duplicate or missing billing lifecycle events; the highest-impact failure mode here and the one requiring cross-team coordination. (4) Conformance fixture drift → CI red on an unrelated spec commit; pin the fixture. (5) Mixed SDK versions across services → inconsistent context during the rollout window, temporarily limiting cross-service segmentation; bounded and self-resolving.

Ramp-up. Minimal for application developers — the release is additive and the README now documents the app_language trait and the billing fallback events, which is the right place for it. Budget roughly half a day per service for upgrade, env configuration, and a staging verification pass; a further one to two days for teams electing to migrate existing billing call sites to BillingEvent and validated properties. The real ramp-up is organizational: the playbook engine owners, the analytics/schema owners, and the SDK maintainer need a shared, written understanding of the fallback-event contract before adoption spreads.