PHPackages setono/meta-conversions-api-php-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. setono/meta-conversions-api-php-sdk ActiveLibrary[API Development](/categories/api) setono/meta-conversions-api-php-sdk =================================== PHP library with basic objects and more for working with Facebook/Metas Conversions API v1.0.0(2w ago)16123.4k↓39.9%41MITPHPPHP >=8.1CI passing Since Jul 26Pushed 2w ago2 watchersCompare [ Source](https://github.com/Setono/meta-conversions-api-php-sdk)[ Packagist](https://packagist.org/packages/setono/meta-conversions-api-php-sdk)[ GitHub Sponsors](https://github.com/Setono)[ RSS](/packages/setono-meta-conversions-api-php-sdk/feed)WikiDiscussions master Synced 2d ago READMEChangelog (8)Dependencies (36)Versions (9)Used By (1) Meta (Facebook) Conversions API PHP SDK ======================================= [](#meta-facebook-conversions-api-php-sdk) [![Latest Version](https://camo.githubusercontent.com/5c7004956464b90f7ad4e07dd48b62216f6f78368705bd95a018287fccf82399/68747470733a2f2f706f7365722e707567782e6f72672f7365746f6e6f2f6d6574612d636f6e76657273696f6e732d6170692d7068702d73646b2f762f737461626c65)](https://packagist.org/packages/setono/meta-conversions-api-php-sdk)[![Software License](https://camo.githubusercontent.com/4622ee01f719711a9f6061b9387e58e32e6cd45b15a2365348153a3d271fbfe5/68747470733a2f2f706f7365722e707567782e6f72672f7365746f6e6f2f6d6574612d636f6e76657273696f6e732d6170692d7068702d73646b2f6c6963656e7365)](LICENSE)[![Build Status](https://github.com/Setono/meta-conversions-api-php-sdk/actions/workflows/build.yaml/badge.svg)](https://github.com/Setono/meta-conversions-api-php-sdk/actions)[![Code Coverage](https://camo.githubusercontent.com/b6ab6e5e5000636a211076b770529bdc43ff09a37eb797f87a93a479dfc217e4/68747470733a2f2f636f6465636f762e696f2f67682f5365746f6e6f2f6d6574612d636f6e76657273696f6e732d6170692d7068702d73646b2f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/Setono/meta-conversions-api-php-sdk)[![Mutation testing](https://camo.githubusercontent.com/9accb5237631a1d3e6ae4ace78f11c546759498f6a532eaf0a3c12034032fe7f/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742675726c3d687474707325334125324625324662616467652d6170692e737472796b65722d6d757461746f722e696f2532466769746875622e636f6d2532465365746f6e6f2532466d6574612d636f6e76657273696f6e732d6170692d7068702d73646b2532466d6173746572)](https://dashboard.stryker-mutator.io/reports/github.com/Setono/meta-conversions-api-php-sdk/master) A small, typed PHP library for sending server-side events to Meta's (Facebook's) [Conversions API](https://developers.facebook.com/docs/marketing-api/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 ------------ [](#requirements) - PHP 8.1+ - A [PSR-18](https://www.php-fig.org/psr/psr-18/) HTTP client and [PSR-17](https://www.php-fig.org/psr/psr-17/) factories (see [Installation](#installation)) 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: ``` composer require setono/meta-conversions-api-php-sdk kriswallsmith/buzz nyholm/psr7 ``` `symfony/http-client` works just as well if you prefer it: ``` composer require setono/meta-conversions-api-php-sdk symfony/http-client nyholm/psr7 ``` 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](#using-your-own-http-client). Quick start ----------- [](#quick-start) ``` use Setono\MetaConversionsApi\Client\Client; use Setono\MetaConversionsApi\Event\Event; use Setono\MetaConversionsApi\Pixel\Pixel; $event = new Event(Event::EVENT_VIEW_CONTENT); $event->eventSourceUrl = 'https://example.com/products/blue-jeans'; $event->userData->clientUserAgent = $_SERVER['HTTP_USER_AGENT']; $event->userData->clientIpAddress = $_SERVER['REMOTE_ADDR']; $event->userData->email[] = 'johndoe@example.com'; // hashed for you before sending // A pixel carries the id and the access token used to authenticate the request $event->pixels[] = new Pixel('YOUR_PIXEL_ID', 'YOUR_ACCESS_TOKEN'); $client = new Client(); $client->sendEvent($event); ``` 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 ---------------------- [](#sending-a-richer-event) `Event::$customData` holds the event-specific data (value, currency, contents, …) and `Event::$userData` holds the customer-matching data: ``` use Setono\MetaConversionsApi\Client\Client; use Setono\MetaConversionsApi\Event\Content; use Setono\MetaConversionsApi\Event\Event; use Setono\MetaConversionsApi\Pixel\Pixel; $event = new Event(Event::EVENT_PURCHASE); $event->eventSourceUrl = 'https://example.com/checkout/complete'; // Customer information — pass raw values, the SDK normalizes and hashes them $event->userData->email[] = 'johndoe@example.com'; $event->userData->phoneNumber[] = '+1 (555) 123-4567'; $event->userData->firstName[] = 'John'; $event->userData->lastName[] = 'Doe'; $event->userData->clientUserAgent = $_SERVER['HTTP_USER_AGENT']; $event->userData->clientIpAddress = $_SERVER['REMOTE_ADDR']; // Event data $event->customData->currency = 'USD'; $event->customData->value = 142.52; $event->customData->contents[] = new Content('SKU-1', 1, 99.99); $event->customData->contents[] = new Content('SKU-2', 1, 42.53); // Anything not covered by a typed property can go into customProperties $event->customData->customProperties['membership_level'] = 'gold'; $event->pixels[] = new Pixel('YOUR_PIXEL_ID', 'YOUR_ACCESS_TOKEN'); (new Client())->sendEvent($event); ``` ### Multiple pixels [](#multiple-pixels) Add more than one `Pixel` and the event is sent to each of them (every pixel carries its own access token): ``` $event->pixels[] = new Pixel('PIXEL_ID_1', 'ACCESS_TOKEN_1'); $event->pixels[] = new Pixel('PIXEL_ID_2', 'ACCESS_TOKEN_2'); ``` ### Test events [](#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: ``` $event->testEventCode = 'TEST12345'; ``` ### Error handling [](#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): ``` use Setono\MetaConversionsApi\Exception\ClientException; try { $client->sendEvent($event); } catch (ClientException $e) { $logger->error('Could not send event to Meta', ['exception' => $e]); } ``` Browser-side tracking with deduplication ---------------------------------------- [](#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: ``` use Setono\MetaConversionsApi\Event\Parameters; use Setono\MetaConversionsApi\Generator\FbqGenerator; $generator = new FbqGenerator(); // In your : initialise the pixel(s) and send a PageView echo $generator->generateInit( $event->pixels, $event->userData->getPayload(Parameters::PAYLOAD_CONTEXT_BROWSER), ); // Where the conversion happens: fire the same event in the browser. // Because it reuses $event->eventId, Meta counts the server + browser event once. echo $generator->generateTrack($event); ``` Both methods wrap the output in a `` 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 ------------- [](#custom-events) Any event name that isn't one of the standard `Event::EVENT_*` constants is treated as a [custom event](https://developers.facebook.com/docs/meta-pixel/implementation/conversion-tracking#custom-events). `FbqGenerator` will emit `trackCustom` instead of `track` for these: ``` $event = new Event('SubscribedToNewsletter'); $event->isCustom(); // true ``` `fbc` / `fbp` cookies --------------------- [](#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: ``` use Setono\MetaConversionsApi\ValueObject\Fbc; use Setono\MetaConversionsApi\ValueObject\Fbp; $event->userData->fbc = Fbc::fromString($_COOKIE['_fbc']); $event->userData->fbp = Fbp::fromString($_COOKIE['_fbp']); ``` Using your own HTTP client -------------------------- [](#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: ``` $client = new Client(); $client->setHttpClient($myPsr18Client); $client->setRequestFactory($myPsr17RequestFactory); $client->setStreamFactory($myPsr17StreamFactory); ``` Logging ------- [](#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: ``` $client->setLogger($logger); ``` Extending events ---------------- [](#extending-events) `Event` is intentionally **not** `final`, so you can build domain-specific events with sensible defaults: ``` use Setono\MetaConversionsApi\Event\Event; final class PurchaseEvent extends Event { public function __construct() { parent::__construct(self::EVENT_PURCHASE); } } ``` Development ----------- [](#development) ``` composer phpunit # run the test suite composer analyse # static analysis (PHPStan) composer check-style # coding standard check (ECS) composer fix-style # fix coding standard violations ``` License ------- [](#license) This library is released under the [MIT License](LICENSE). ### Health Score 57 — FairBetter than 98% of packages Maintenance96 Actively maintained with recent releases Popularity41 Moderate usage in the ecosystem Community15 Small or concentrated contributor base Maturity62 Established project with proven stability Bus Factor1 Top contributor holds 99% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~202 days Recently: every ~354 days Total 8 Last Release 18d ago Major Versions v0.2.4 → v1.0.02026-06-15 PHP version history (2 changes)v0.1.0PHP >=7.4 v1.0.0PHP >=8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2412177?v=4)[Joachim Løvgaard](/maintainers/loevgaard)[@loevgaard](https://github.com/loevgaard) --- Top Contributors [![loevgaard](https://avatars.githubusercontent.com/u/2412177?v=4)](https://github.com/loevgaard "loevgaard (99 commits)")[![formatz](https://avatars.githubusercontent.com/u/965595?v=4)](https://github.com/formatz "formatz (1 commits)") --- Tags facebookfacebook-conversion-apimetaphp ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Rector Type Coverage Yes ### Embed Badge ![Health badge](/badges/setono-meta-conversions-api-php-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/setono-meta-conversions-api-php-sdk/health.svg)](https://phpackages.com/packages/setono-meta-conversions-api-php-sdk) ``` ### Alternatives [telnyx/telnyx-php Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 35789.4k2](/packages/telnyx-telnyx-php)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 85036.3k](/packages/flow-php-flow)[tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[openai-php/client OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API 5.8k28.0M318](/packages/openai-php-client)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.9M738](/packages/sylius-sylius)[getbrevo/brevo-php Official Brevo provided RESTFul API V3 php library 1003.9M50](/packages/getbrevo-brevo-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)