PHPackages                             aghfatehi/laravel-meta-conversions - 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. aghfatehi/laravel-meta-conversions

ActiveLibrary[API Development](/categories/api)

aghfatehi/laravel-meta-conversions
==================================

Laravel package for Facebook Pixel and Meta Conversion API (CAPI) with event deduplication, queue support, and ecommerce tracking.

v1.0.0(1mo ago)01↓80%MITPHPPHP ^8.2CI passing

Since Jun 10Pushed 1mo agoCompare

[ Source](https://github.com/aghfatehi/laravel-meta-conversions)[ Packagist](https://packagist.org/packages/aghfatehi/laravel-meta-conversions)[ Docs](https://fsoftdev.com)[ RSS](/packages/aghfatehi-laravel-meta-conversions/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (9)Versions (2)Used By (0)

[![Total Downloads](https://camo.githubusercontent.com/88914db8da1e6840314bdb8a2fa3b000bfbf31583375ae9df1be2a8573f1b5fa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6167686661746568692f6c61726176656c2d6d6574612d636f6e76657273696f6e732e7376673f7374796c653d666c61742d737175617265266c6162656c3d446f776e6c6f616473)](https://packagist.org/packages/aghfatehi/laravel-meta-conversions)[![Latest Version](https://camo.githubusercontent.com/1872b5cf8ea74556dcf3d47a7e7db8b2493ddaa69461012819bf8cc5ce7a3f1b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6167686661746568692f6c61726176656c2d6d6574612d636f6e76657273696f6e732e7376673f7374796c653d666c61742d737175617265266c6162656c3d4c6174657374)](https://packagist.org/packages/aghfatehi/laravel-meta-conversions)[![PHP Version](https://camo.githubusercontent.com/691df96ab37f507b7f8580f69741202172292a584f30c8fa5e421abad4ec4397/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6167686661746568692f6c61726176656c2d6d6574612d636f6e76657273696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aghfatehi/laravel-meta-conversions)[![Tests](https://camo.githubusercontent.com/0469f8950bb1d957bde7f5e24ffd9be633ef94a43e70e33ba2400f7634db6a34/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6167686661746568692f6c61726176656c2d6d6574612d636f6e76657273696f6e732f74657374732e796d6c3f7374796c653d666c61742d737175617265266c6162656c3d5465737473)](https://github.com/aghfatehi/laravel-meta-conversions/actions)[![License](https://camo.githubusercontent.com/76f1afdccb16f934395390b8ede79dcd27c4a0547a0d4763b06a38a96f5dd890/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6167686661746568692f6c61726176656c2d6d6574612d636f6e76657273696f6e733f7374796c653d666c61742d737175617265)](LICENSE)

---

Laravel Meta Conversions — Meta Pixel & Facebook CAPI Package
=================================================================

[](#laravel-meta-conversions--meta-pixel--facebook-capi-package)

> The complete Meta Pixel & Facebook Conversions API solution for Laravel.

**Laravel Meta Conversions** is a complete **Meta Pixel Laravel Package** and **Facebook Pixel Laravel Package** that integrates **Laravel Facebook Pixel** browser tracking with **Laravel Meta Conversions API (CAPI)** server-side tracking. It delivers accurate **Server Side Tracking Laravel** for reliable **Meta Conversion Tracking** and **Facebook Conversion Tracking** across your entire ecommerce funnel.

> **Goal**: High-precision **Laravel Ecommerce Tracking** with event deduplication via unified `event_id` across browser + server for maximum **Meta Advanced Matching** quality. Built for **Laravel Marketing Analytics** and data-driven ad optimization.

---

Features
--------

[](#features)

### General

[](#general)

- **Laravel Meta Pixel** + CAPI in a single package — full **Laravel CAPI** support
- Laravel 10.x / 11.x / 12.x and PHP 8.2+
- Auto-Discovery (install and run)
- Compatible with official Meta requirements

### Client-side (Laravel Meta Pixel)

[](#client-side-laravel-meta-pixel)

- `` — ready-to-use Blade component for **Laravel Facebook Pixel**
- `@include('facebook-conversion::pixel')` — alternative include approach
- Auto `fbq('init')` with your Pixel ID
- Auto `fbq('track', 'PageView')` on every page
- Pass `event_id` from backend to frontend for unified deduplication

### Server-side (Laravel Meta Conversions API)

[](#server-side-laravel-meta-conversions-api)

- Send events via **Laravel Facebook Conversions API** → `graph.facebook.com/{version}/{pixel_id}/events`
- 12 standard events: PageView, ViewContent, Search, AddToWishlist, AddToCart, RemoveFromCart, InitiateCheckout, AddPaymentInfo, **Meta Purchase Event**, Lead, CompleteRegistration, Contact
- Fluent API: `FacebookConversion::event()->name('...')->value(...)->send()`

### User Data & Meta Advanced Matching

[](#user-data--meta-advanced-matching)

- Automatic SHA-256 hashing as required by **Meta Conversion Tracking**
- `em`, `ph`, `fn`, `ln`, `ct`, `st`, `zp`, `country`, `external_id`
- Auto-extract `client_ip_address` and `client_user_agent`
- Auto-read `_fbp`, `_fbc` cookies
- Auto-fill from `auth()->user()` when available

### Queue & Performance

[](#queue--performance)

- Queue support via `FACEBOOK_QUEUE=true` for non-blocking **Server Side Tracking Laravel**
- Events dispatched through `SendFacebookEventJob`
- Auto-retry on failure: 3 attempts with 100ms delay
- Configurable HTTP timeout

### Testing & Logging

[](#testing--logging)

- Artisan command: `php artisan facebook:test-event` to verify **Laravel CAPI** integration
- Test Event Code support for validation in **Meta Events Manager**
- Dedicated `facebook_conversion` log channel with 30-day rotation
- Access token is masked in all logs

### Security & Error Handling

[](#security--error-handling)

- Master switch: `FACEBOOK_ENABLED=false` disables all tracking
- Graceful failure — never breaks your application
- Configuration validation before sending
- GDPR-compliant: easy opt-out

---

Installation
------------

[](#installation)

### Step 1: Install the package

[](#step-1-install-the-package)

```
composer require aghfatehi/laravel-meta-conversions
```

> Laravel auto-discovers the Service Provider. If you disable auto-discovery, register manually:

```
// config/app.php
'providers' => [
    Aghfatehi\LaravelMetaConversions\FacebookConversionServiceProvider::class,
],
'aliases' => [
    'FacebookConversion' => Aghfatehi\LaravelMetaConversions\Facades\FacebookConversion::class,
],
```

### Step 2: Publish config

[](#step-2-publish-config)

```
php artisan vendor:publish --tag=facebook-conversion-config
```

Config file published to `config/facebook-conversion-service.php`.

### Step 3: Publish views (optional)

[](#step-3-publish-views-optional)

```
php artisan vendor:publish --tag=facebook-conversion-views
```

Views published to `resources/views/vendor/facebook-conversion/pixel.blade.php`.

---

Setup
-----

[](#setup)

### 1. Get your Facebook Pixel ID

[](#1-get-your-facebook-pixel-id)

1. Open [Facebook Events Manager → **Meta Events Manager**](https://business.facebook.com/events_manager)
2. Select an existing pixel or create a new one for **Laravel Meta Pixel**
3. Copy the **Pixel ID** from the top
4. Set in your `.env`:

```
FACEBOOK_PIXEL_ID=123456789012345
```

### 2. Get your CAPI Access Token

[](#2-get-your-capi-access-token)

1. In **Meta Events Manager** → **Settings**
2. Scroll to **Conversion API**
3. Click **Generate Access Token**
4. Copy the token (starts with `EAA...`)
5. Set in your `.env`:

```
FACEBOOK_PIXEL_API=EAAJjmXXfkp8BAMZCDLWDZB6ZCk4yUmMbITZBk...
```

> Tokens may expire. Regenerate periodically. Enable domain verification in Business Manager.

### 3. Configure additional variables

[](#3-configure-additional-variables)

```
# ─── Core ───
FACEBOOK_PIXEL_ID=123456789012345       # Required
FACEBOOK_PIXEL_API=EAA...               # Required
FACEBOOK_ENABLED=true                   # Master toggle

# ─── Testing ───
FACEBOOK_TEST_EVENT_CODE=TEST12345      # Test code (dev only)

# ─── Performance ───
FACEBOOK_QUEUE=true                     # Enable queue (recommended in production)
FACEBOOK_QUEUE_CONNECTION=redis         # Queue connection (optional)

# ─── Logging ───
FACEBOOK_LOGGING=true                   # Enable logging
FACEBOOK_LOG_CHANNEL=facebook_conversion

# ─── API ───
FACEBOOK_API_VERSION=v21.0              # Graph API version
FACEBOOK_TIMEOUT=5                      # HTTP timeout (seconds)
FACEBOOK_RETRY_ATTEMPTS=3               # Retry count
FACEBOOK_RETRY_DELAY=100                # Retry delay (ms)
```

---

Usage
-----

[](#usage)

### Add Pixel to your layout

[](#add-pixel-to-your-layout)

Insert this in your `` tag:

```
{{-- === [Laravel Meta Pixel + CAPI] === --}}

{{-- =================================== --}}
```

Or using `@include`:

```
@include('facebook-conversion::pixel')
```

> The pixel automatically fires `fbq('track', 'PageView')` on every page load.

### Real-world Examples from an Ecommerce Store

[](#real-world-examples-from-an-ecommerce-store)

#### View Content (Product Page)

[](#view-content-product-page)

Use in `HomeController@product` when a visitor views a product page:

```
// When a visitor lands on a product page — triggers Laravel Ecommerce Tracking
FacebookConversion::viewContent(
    productId: $product->id,
    productName: $product->name,
    category: $product->category->name,
    value: $product->price,
    currency: 'SAR'
);
```

#### Add to Cart

[](#add-to-cart)

Use in `CartController@addToCart` after adding a product:

```
// When a visitor adds a product to cart
FacebookConversion::addToCart(
    productId: $product->id,
    productName: $product->name,
    quantity: $request->quantity,
    value: $price,
    currency: 'SAR'
);
```

#### Add to Wishlist

[](#add-to-wishlist)

Use in `WishlistController@store`:

```
// When a visitor adds a product to wishlist
FacebookConversion::addToWishlist(
    productId: $product->id,
    productName: $product->name,
    value: $product->price,
    currency: 'SAR'
);
```

#### Purchase (most important event)

[](#purchase-most-important-event)

Use in `OrderController@store` after order creation:

```
// When a visitor completes a purchase — the Meta Purchase Event
FacebookConversion::purchase(
    value: $order->grand_total,
    currency: 'SAR',
    productIds: $order->orderDetails->pluck('product_id')->toArray()
);
```

### Complete Event List

[](#complete-event-list)

```
// 1. PageView
FacebookConversion::pageView();

// 2. ViewContent
FacebookConversion::viewContent(
    productId: 100,
    productName: 'iPhone 15',
    category: 'Phones',
    value: 999,
    currency: 'SAR'
);

// 3. Search
FacebookConversion::search('iphone 15');

// 4. AddToWishlist
FacebookConversion::addToWishlist(
    productId: 100,
    productName: 'iPhone 15',
    value: 999,
    currency: 'SAR'
);

// 5. AddToCart
FacebookConversion::addToCart(
    productId: 100,
    productName: 'iPhone 15',
    quantity: 1,
    value: 999,
    currency: 'SAR'
);

// 6. RemoveFromCart
FacebookConversion::removeFromCart(
    productId: 100,
    productName: 'iPhone 15',
    quantity: 1,
    value: 999,
    currency: 'SAR'
);

// 7. InitiateCheckout
FacebookConversion::initiateCheckout(
    value: 999,
    currency: 'SAR',
    productIds: ['100', '101']
);

// 8. AddPaymentInfo
FacebookConversion::addPaymentInfo(
    value: 999,
    currency: 'SAR'
);

// 9. Purchase (the Meta Purchase Event — highest priority)
FacebookConversion::purchase(
    value: 999,
    currency: 'SAR',
    productIds: ['100', '101']
);

// 10. Lead
FacebookConversion::lead(
    value: 50,
    currency: 'USD'
);

// 11. CompleteRegistration
FacebookConversion::completeRegistration(method: 'email');

// 12. Contact
FacebookConversion::contact();
```

---

Event Builder (Fluent API)
--------------------------

[](#event-builder-fluent-api)

For full control over your **Laravel CAPI** event payload:

```
FacebookConversion::event()
    ->name('Purchase')
    ->value(100)
    ->currency('SAR')
    ->contentIds(['product-1', 'product-2'])
    ->contentType('product')
    ->eventId('custom-id-123')
    ->send();
```

Or build the event object and send it later:

```
$event = FacebookConversion::event()
    ->name('ViewContent')
    ->value(599)
    ->currency('SAR')
    ->build();

// ... do some processing ...

FacebookConversion::sendEvent($event);
```

---

Event Deduplication — Core of Meta Conversion Tracking
------------------------------------------------------

[](#event-deduplication--core-of-meta-conversion-tracking)

Meta requires a unified `event_id` sent from both **Laravel Facebook Pixel** (browser) and **Laravel CAPI** (server) to identify duplicate events. This is the foundation of accurate **Facebook Conversion Tracking**.

### How it works

[](#how-it-works)

```
Single event (e.g. Purchase)
       │
       ├── Browser: fbq('track', 'Purchase', {...}, { eventID: 'uuid-123' })
       │
       └── Server:  CAPI → { "event_name": "Purchase", "event_id": "uuid-123", ... }

Meta compares (event_id + event_name) and removes the duplicate

```

The package generates a UUID v4 automatically for every event. You can customize it:

```
// Custom event_id
FacebookConversion::event()
    ->name('Purchase')
    ->eventId('order_456_' . time())
    ->send();
```

To pass `event_id` from server to Pixel (e.g., from an API response):

```

```

---

User Data with Meta Advanced Matching
-------------------------------------

[](#user-data-with-meta-advanced-matching)

### Automatic Data Collection — for Meta Advanced Matching

[](#automatic-data-collection--for-meta-advanced-matching)

Whenever you fire an event, the package automatically collects user data to enhance **Meta Events Manager** with **Meta Advanced Matching**:

```
// Auto-collected data for better Server Side Tracking Laravel
// 1. From auth()->user() → email, phone, name, last_name
// 2. From request() → ip, user_agent
// 3. From cookies → _fbp, _fbc
```

### SHA-256 Hashing per Meta Requirements

[](#sha-256-hashing-per-meta-requirements)

All data is hashed with SHA-256 as required by **Meta Conversion Tracking**:

```
// Pass custom UserData for better Facebook Conversion Tracking:
$userData = new UserData()
    ->email('user@example.com')
    ->phone('+966551234567')
    ->firstName('Ahmed')
    ->lastName('Ghfatehi')
    ->city('Riyadh')
    ->state('Riyadh Province')
    ->zip('12345')
    ->country('SA')
    ->fbp(request()->cookie('_fbp'))
    ->fbc(request()->cookie('_fbc'));

FacebookConversion::purchase(
    value: 999,
    currency: 'SAR',
    userData: $userData
);
```

### Hashing Reference

[](#hashing-reference)

FieldOriginalHashed`em``user@example.com``SHA-256(lowercase(trim(email)))``ph``+966 55 123 4567``SHA-256(strip non-numeric)``fn``Ahmed``SHA-256(lowercase(trim))``ln``Ghfatehi``SHA-256(lowercase(trim))``ct``Riyadh``SHA-256(lowercase(trim))``st``Riyadh Province``SHA-256(lowercase(trim))``zp``12345``SHA-256(lowercase(trim))``country``SA``SHA-256(lowercase(trim))``external_id``user_123``SHA-256`---

Queue Support
-------------

[](#queue-support)

In production, enable the queue to avoid blocking HTTP requests when using **Laravel CAPI**:

```
FACEBOOK_QUEUE=true
FACEBOOK_QUEUE_CONNECTION=redis
```

Make sure a queue worker is running:

```
php artisan queue:work
```

How it works with `FACEBOOK_QUEUE=true`:

```
Controller → FacebookConversion::purchase(...)
                  ↓
            SendFacebookEventJob (dispatch)
                  ↓
            Queue Worker → MetaConversionApiClient → Facebook CAPI

```

The controller returns immediately. The event is processed in the background.

---

Middleware
----------

[](#middleware)

### TrackFacebookPageView

[](#trackfacebookpageview)

Automatically sends `PageView` via **Server Side Tracking Laravel** on every GET request:

```
// App\Http\Kernel.php
protected $middlewareGroups = [
    'web' => [
        \Aghfatehi\LaravelMetaConversions\Http\Middleware\TrackFacebookPageView::class,
    ],
];
```

Or on specific routes:

```
Route::middleware('track-facebook-pageview')->group(function () {
    Route::get('/', [HomeController::class, 'index']);
});
```

> The middleware sends the PageView after the response is sent (terminate method) to avoid slowing down the page.

---

Testing Events via Meta Events Manager
--------------------------------------

[](#testing-events-via-meta-events-manager)

### 1. Using Test Event Code

[](#1-using-test-event-code)

In development, use Meta's test code to validate your **Laravel CAPI** integration:

```
FACEBOOK_TEST_EVENT_CODE=TEST12345
```

Open **Meta Events Manager** → **Test Events** and watch your **Laravel Meta Conversions API** events arrive in real time.

### 2. Using Artisan Command

[](#2-using-artisan-command)

```
# Send a test PageView event
php artisan facebook:test-event

# Send a Purchase event with value
php artisan facebook:test-event "Purchase" --value=99.99 --currency=SAR

# Send a ViewContent event
php artisan facebook:test-event "ViewContent" --value=599 --currency=SAR
```

### 3. Verify in Meta Events Manager

[](#3-verify-in-meta-events-manager)

After sending events:

1. Open [Meta Events Manager → **Meta Events Manager**](https://business.facebook.com/events_manager)
2. Go to **Test Events** tab (if using Test Event Code)
3. Or go to **Diagnostics** to see real events
4. Check **Event Match Quality** for each event

---

Logging
-------

[](#logging)

Logs are written to `storage/logs/facebook-conversion.log` with daily rotation (30 days).

```
[2026-06-10 12:00:00] facebook_conversion.INFO: Sending event to Facebook Conversion API {"event_name":"Purchase","event_id":"uuid-123"}
[2026-06-10 12:00:01] facebook_conversion.INFO: Facebook Conversion API event sent successfully {"response":{"events_received":1}}
[2026-06-10 12:00:02] facebook_conversion.ERROR: Facebook Conversion API request failed {"status":401,"response":{"error":{"message":"Invalid token"}}}

```

> Access token is masked: `EAAJjm****`

---

Production Checklist
--------------------

[](#production-checklist)

- `FACEBOOK_PIXEL_ID` and `FACEBOOK_PIXEL_API` are set
- `FACEBOOK_ENABLED=true`
- `FACEBOOK_TEST_EVENT_CODE` is **empty** (remove in production!)
- `FACEBOOK_QUEUE=true` and queue is running
- `php artisan queue:work` (or Supervisor) is active
- Domain is verified in Facebook Business Manager
- **Laravel Facebook Pixel** fires on all pages
- Events appear in **Meta Events Manager**
- Event Match Quality > 90%

---

Troubleshooting
---------------

[](#troubleshooting)

ProblemSolutionEvents not appearingCheck `FACEBOOK_ENABLED=true` and valid Pixel ID401 UnauthorizedRegenerate Access Token in **Meta Events Manager**Low match qualitySend more user data (email, phone, fbp, fbc) for **Meta Advanced Matching**Duplicate eventsEnsure `event_id` is unique per event (package generates UUID automatically)Queue not workingCheck `php artisan queue:work` and queue connectionConfig errorCheck `storage/logs/facebook-conversion.log`Token expiredRegenerate in **Meta Events Manager** → Settings → Conversion API---

Testing
-------

[](#testing)

```
composer test
```

```
Tests:    50 passed (113 assertions)
Duration: 2.50s

```

---

Architecture
------------

[](#architecture)

```
Controller / Middleware / Artisan
         │
         ▼
FacebookConversionService  ←  Interface (Contract)
         │
         ├── EventBuilder (Fluent API)
         │
         ├── SendFacebookEventJob (Queue)
         │
         └── MetaConversionApiClient (HTTP)
                    │
                    ▼
         Facebook Graph API (CAPI)

```

### Data flow:

[](#data-flow)

```
[User] → [Browser Pixel] ─── fbq('track', ..., {eventID}) ──┐
                                                              ├── → [Meta] ← Dedup
         ↓ [Server] → [Service] → [CAPI] ─── {event_id: same} ──┘

```

---

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

---

 Built by [Ahmed Ghfatehi](https://fsoftdev.com) · [fsoftdev.com](https://fsoftdev.com)

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance90

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

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

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7c0d20683d29aa61fca6b1f9a47a754b2d3e177750f1e8d66975979f2ae8813f?d=identicon)[aghfatehi](/maintainers/aghfatehi)

---

Tags

capiconversion-trackingconversions-apiecommerce-analyticsevent-trackingfacebookfacebook-capifacebook-conversions-apifacebook-pixellaravellaravel-packagemetameta-capimeta-conversions-apimeta-pixelphpserver-side-tracking

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/aghfatehi-laravel-meta-conversions/health.svg)

```
[![Health](https://phpackages.com/badges/aghfatehi-laravel-meta-conversions/health.svg)](https://phpackages.com/packages/aghfatehi-laravel-meta-conversions)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.6k](/packages/simplestats-io-laravel-client)[flarum/core

Delightfully simple forum software.

211.4M2.4k](/packages/flarum-core)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)