Php Laravel Package

Product Decisions This Supports

• Build vs. buy for analytics/billing telemetry. v0.3.0 pins the SDK to Whisperr spec contract v2 and runs the server sections of conformance/v2.json in CI. That gives a concrete, testable answer to "will our events stay compatible with the hosted engine?" — you are buying a contract, not just a client library, which lowers the risk of adopting a vendor for server-side event emission instead of building thin in-house HTTP calls.
• Billing lifecycle instrumentation. Whisperr\BillingEvent names the reserved fallback events (trial_started, trial_converted, renewal_succeeded, auto_renew_disabled, billing_recovered, refund_granted, etc.) that the playbook engine expects. Product can now scope trial-conversion nudges, involuntary-churn interventions, and dunning messaging against a fixed vocabulary rather than inventing event names per squad — this is a roadmap dependency worth closing early.
• Data quality guardrails as product requirements. BillingEvent::properties() rejects non-3-letter currencies, negative prices, and non-finite prices (InvalidArgumentException), and upper-cases ISO 4217 codes. That turns "revenue numbers are wrong in the dashboard" from a recurring support ticket into a caught-at-source exception, and makes currency-normalized revenue reporting a defensible spec rather than a convention.
• Release-train and versioning decisions. Automatic context.sdk_name / context.sdk_version on every event means you can segment behavior, funnel drop-off, and incidents by SDK version post-deploy — useful for staged rollouts and for answering "did last week's regression start before or after the SDK bump?"
• Multi-tenant / multi-app packaging. The optional app_version (env WHISPERR_APP_VERSION, omitted entirely when empty, per-event $context overriding) lets one deployment attribute events to a mobile-app or client release without forking the SDK. That supports decisions like "do we ship a separate environment per white-label tenant, or one deployment with differentiated context?"
• Localization scope. The documented app_language trait plus app_version are the two levers for slicing adoption, retention, and conversion by language and client release — the baseline vocabulary for international roadmap bets.

When to Consider This Package

Adopt when most of the following hold:

• You are on PHP/Laravel and want server-side (not client-side) event emission — signups, subscription transitions, backend-triggered conversions — where a browser SDK cannot see the truth.
• You are already using, or actively evaluating, the Whisperr playbook engine. The BillingEvent constants and spec section 3.8 fallback names are only valuable if something downstream consumes them; standalone they are just strings.
• Revenue analytics matters and you want currency/price validation enforced at emit time rather than in the warehouse.
• You want per-event context enrichment (app version, language, caller-supplied keys) without wrapping or patching the client.
• Your team values conformance testing against a published spec, i.e. you would otherwise be writing your own contract tests.

Look elsewhere or wait when:

• You need an analytics vendor-agnostic abstraction (Segment-style fan-out to multiple destinations). This is a single-destination SDK, and adopting it couples your emit sites to Whisperr's event vocabulary.
• Your billing model is not plan/price/currency/period shaped — usage-based, seat-metered, or credit-bucket pricing will not map cleanly onto plan_id / price / plan_period, and you'll be stuffing semantics into "extra event properties."
• The package is pre-1.0. At v0.3.0 you must accept that BillingEvent constants, context keys, and validation strictness can change between minors; treat it as a bet on a moving spec contract, not a stable API.
• You need the mobile/client SDKs or the playbook engine itself — this release is explicitly the server side of contract v2, so confirm your other surfaces (iOS, Android, web) are at the same contract version before committing to the schema.
• Compliance scoping (PII redaction, data residency, consent gating) is a hard requirement; nothing in these notes speaks to it, so assume it is your responsibility at the call site.

How to Pitch It (Stakeholders)

For executives: This release makes our revenue and lifecycle analytics trustworthy enough to act on. Billing events now use a standardized, spec-tested vocabulary, and malformed prices or currencies throw an error at emit time instead of quietly corrupting a revenue dashboard. Every event is automatically stamped with SDK and app version, so we can attribute metric changes to specific releases and roll back with evidence rather than intuition. The cost is one dependency on a pre-1.0 package — a known, bounded risk that buys us a contract-tested interface we would otherwise have to build and maintain.

For engineering: v0.3.0 implements Whisperr spec contract v2 server-side and runs the spec's conformance/v2.json server sections in the test suite, so contract drift shows up in CI. Two integration points to plan for: (1) set WHISPERR_APP_VERSION in each environment — when it is empty the key is simply absent, and a per-event $context value always wins, so no override plumbing is needed; (2) use BillingEvent::properties() for subscription events so price/currency validation, upper-casing, and the reserved fallback event names (trial_started, renewal_succeeded, billing_recovered, …) are centralized instead of reimplemented per service. Expect argument-validation exceptions on bad currency or price — that is intentional fail-fast, so wire it to your error tracker and alerting rather than swallowing it. Pin the minor version: pre-1.0 semantics may shift, and our conformance coverage only guarantees the version we test against.