Download the PHP package setono/meta-conversions-api-php-sdk without Composer

Meta (Facebook) Conversions API PHP SDK

A small, typed PHP library for sending server-side events to Meta's (Facebook's) Conversions API, and for generating the matching browser-side fbq() snippets.

It gives you plain, well-typed objects (Event, User, Custom, …) and takes care of the fiddly parts for you:

• Automatic normalization & hashing of customer information — you pass raw emails, phone numbers, names, etc. and the SDK normalizes and SHA-256 hashes them the way Meta requires. Never hash this data yourself.
• Server + browser deduplication — every event gets an eventId you can reuse on both sides so Meta counts it once.
• Bring your own HTTP client — built on PSR-18/PSR-17 with auto-discovery, so it works with any compliant client.

Requirements

• PHP 8.1+
• A PSR-18 HTTP client and PSR-17 factories (see Installation)

Installation

The SDK talks to the API through a PSR-18 client and PSR-17 factories, which it discovers automatically. The simplest way is to install it together with an implementation:

symfony/http-client works just as well if you prefer it:

If your project already ships a PSR-18 client and PSR-17 factories you only need the SDK itself (composer require setono/meta-conversions-api-php-sdk); see Using your own HTTP client.

Quick start

An Event is created with a random eventId and the current eventTime already set, and defaults to the website action source. Pass a different source as the second constructor argument if needed (e.g. new Event(Event::EVENT_PURCHASE, Event::ACTION_SOURCE_PHYSICAL_STORE)).

Sending a richer event

Event::$customData holds the event-specific data (value, currency, contents, …) and Event::$userData holds the customer-matching data:

Multiple pixels

Add more than one Pixel and the event is sent to each of them (every pixel carries its own access token):

Test events

While integrating, set a test event code so the event shows up in the Test events tool in Events Manager instead of counting as real traffic:

Error handling

sendEvent() throws a ClientException if Meta returns a non-2xx response. The message contains Meta's error message, code, trace id and the raw response (including the user-facing explanation when Meta provides one):

Browser-side tracking with deduplication

To get the best match quality Meta recommends sending events both server-side (this SDK) and from the browser, using the same eventId so they are deduplicated. FbqGenerator produces the matching JavaScript:

Both methods wrap the output in a <script> tag by default; pass false as the last argument to get the raw JavaScript instead (e.g. to combine several calls into one tag).

Custom events

Any event name that isn't one of the standard Event::EVENT_* constants is treated as a custom event. FbqGenerator will emit trackCustom instead of track for these:

fbc / fbp cookies

The _fbc and _fbp cookies improve attribution. Assign them to the user data either as raw strings or as the typed value objects, which validate the format:

Using your own HTTP client

By default the client auto-discovers a PSR-18 client and PSR-17 factories. To inject your own (e.g. a preconfigured Guzzle client with timeouts and retries), use the setters:

Logging

Client is LoggerAware. Pass any PSR-3 logger and the SDK will, for example, warn you when you try to send an event that has no pixels associated:

Extending events

Event is intentionally not final, so you can build domain-specific events with sensible defaults:

Development

License

This library is released under the MIT License.