Meta Conversions Api Php Sdk Laravel Package

Product Decisions This Supports

• Whether to add server-side conversion tracking as a channel. This SDK is the plumbing for sending events (Purchase, Lead, AddToCart, etc.) from a Laravel backend directly to Meta's Conversions API, complementing or replacing the browser pixel. The decision it unlocks is channel strategy: how much of your measurement mix should be server-originated, and for which events.
• Measurement quality and attribution investment. The package's core value objects (Fbc, Fbp, and the User object that carries them) exist to propagate Meta's click and browser IDs correctly. Match quality — and therefore reported ROAS — depends on getting these right, so this supports a roadmap item like "improve event match quality" rather than being a purely technical choice.
• Event deduplication design. Server-side events must be deduplicated against the browser pixel via a shared event ID. Deciding where that ID is generated (frontend, backend, or both) is a product/analytics decision that this SDK sits downstream of; it does not solve dedup for you.
• Consent and PII posture. Because User carries hashed identifiers and cookie values, adopting this package forces an explicit decision on what customer data leaves your infrastructure, under what consent state, and with what hashing. That is a compliance product decision, not an engineering one.
• Multi-brand / multi-pixel architecture. The known limitation in this release — a rejection from one pixel aborts the remaining pixels — is directly relevant if you operate multiple pixels (multi-store, multi-brand, agency-managed accounts). If so, the build-vs-buy calculus shifts toward wrapping the SDK with per-pixel isolation rather than calling it naively.
• Build vs buy. The realistic comparison is three options: this community SDK, Meta's official PHP Business SDK (heavier, broader API surface, more dependencies), or an in-house HTTP client wrapper. This package is the lightweight option — small surface, typed value objects, no framework lock-in.
• Upgrade timing. v2 is in beta with an explicit warning that exception behavior may still change before stable. This supports a decision to pilot on a non-critical event or a single pixel, and to defer full rollout until 2.0.0 stable and after the multi-pixel issue (#20) is resolved.

When to Consider This Package

Adopt when:

• You are on PHP 8.1+ and already have, or are willing to add, a PSR-18 HTTP client with PSR-17 factories (Guzzle or Symfony HTTP Client both satisfy this). In Laravel this means registering a small service provider and binding the client — a day of work, not a project.
• You want a narrow, typed SDK that does one thing — Conversions API event submission — without pulling in Meta's full Business SDK.
• Your team values immutable, natively typed value objects for cookie-derived identifiers. This release tightens exactly that: Fbp::$randomNumber is now private (so mutation must go through withRandomNumber()), User::$fbc/$fbp are typed Fbc|string|null, and Fb::withCreationTime() accepts int|\DateTimeInterface natively. That is a genuine correctness improvement for data that directly affects attribution.
• You are starting fresh on 2.x (no migration cost) or are already on 1.x and can absorb the changes documented in UPGRADE-2.0.md.

Look elsewhere or wait when:

• You need a stable API contract. This is beta.3. The maintainers explicitly flag that the exception thrown on partial multi-pixel failure may change before stable, and withCreationTime() now throws \TypeError rather than InvalidArgumentException — a TypeError does not implement ExceptionInterface, so generic catch blocks around this call will behave differently. Anything touching your error-handling or retry logic is not settled.
• You rely on multi-pixel delivery. The known limitation means one pixel's rejection silently skips the rest. If multi-pixel is core to your setup, budget for a wrapper that fans out per pixel and aggregates results — or wait for #20.
• You need capabilities beyond event submission — ads management, catalog sync, audience APIs. Meta's official Business SDK covers more ground.
• You require vendor SLA or first-party support. This is a community package from an agency, not Meta.
• You need built-in queueing, retry, or backoff. The SDK sends; it does not schedule. In Laravel you would layer this on the queue yourself.
• You are not on PHP 8.1+ or cannot introduce PSR-18/PSR-17 dependencies.

How to Pitch It (Stakeholders)

For executives: This is a small, focused library that lets our backend report conversions directly to Meta, recovering measurement signal we lose to ad blockers, tracking prevention, and iOS restrictions. It is not a platform commitment — it is a few hundred lines of glue code behind an interface we control, and it can be swapped for Meta's official SDK or an in-house client without changing our product. The current release is a beta, so the recommendation is a scoped pilot on one pixel and one non-critical event, with full rollout gated on the stable 2.0 release. No customer-facing surface changes; the main decision it forces is a deliberate one about what customer data we send and under what consent.

For engineering: It is framework-agnostic and dependency-light — PHP 8.1+, PSR-18 client, PSR-17 factories. Integration in Laravel is a service provider plus a thin adapter around our existing HTTP client. This release is a cleanup: value objects are now properly immutable and natively typed, which removes a class of silent data-corruption bugs in the identifiers that drive attribution. Two things to plan around: (1) the beta.2 → beta.3 changes are near-zero for us, but the 1.x → 2.0 upgrade is documented separately and should be read before we pin a version; (2) the multi-pixel failure mode — the client throws at the first rejecting pixel and does not attempt the rest — means our adapter must fan out per pixel and aggregate outcomes rather than catching-and-logging at the top level. Pin to an exact beta, run the pilot, and revisit on 2.0.0 stable.