Laravel Pixel

https://github.com/jeffersongoncalves/laravel-pixel
Admin
Laravel Pixel is a Laravel package that integrates Meta (Facebook) Pixel into Blade templates using...
Tokens:4,923
Snippets:59
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Laravel Pixel via Composer

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-pixel
```

--------------------------------

### Add new setting: property and migration

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Shows the two steps required to add a new setting: declare the property in PixelSettings and create a migration to add it to the 'pixel' group. The example uses track_page_view with a default of true.

```php
public bool $track_page_view = true;
```

```php
return new class extends SettingsMigration
{
    public function up(): void
    {
        $this->migrator->add('pixel.track_page_view', true);
    }
};
```

--------------------------------

### Read pixel_id setting via container or helper

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Shows how to read the pixel_id setting using the container or the pixel_settings() helper. The comment shows an example value.

```php
use JeffersonGoncalves\Pixel\Settings\PixelSettings;

// Via container
$settings = app(PixelSettings::class);
echo $settings->pixel_id; // e.g., "123456789012345"

// Via helper
echo pixel_settings()->pixel_id;
```

--------------------------------

### Publish and Run Pixel Settings Migration

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Publish and run the pixel settings migration.

```bash
php artisan vendor:publish --tag="pixel-settings-migrations"
php artisan migrate
```

--------------------------------

### Publish and Run Spatie Settings Migrations

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Publish and run the spatie/laravel-settings migrations if not already done.

```bash
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
php artisan migrate
```

--------------------------------

### Run Tests

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Run the package tests.

```bash
composer test
```

--------------------------------

### Test pixel_settings() helper

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Pest tests for the pixel_settings() helper function. Confirms it returns a PixelSettings instance and reads the saved pixel_id value.

```php
it('pixel_settings() returns PixelSettings instance', function () {
    $settings = pixel_settings();

    expect($settings)->toBeInstanceOf(PixelSettings::class);
});

it('pixel_settings() reads the pixel_id', function () {
    $settings = app(PixelSettings::class);
    $settings->pixel_id = '999888777666555';
    $settings->save();

    expect(pixel_settings()->pixel_id)->toBe('999888777666555');
});
```

--------------------------------

### PixelServiceProvider Class

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Registers the package with views, auto-registers PixelSettings into the settings config, loads migrations, and publishes them under the 'pixel-settings-migrations' tag.

```php
class PixelServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package->name('laravel-pixel')
            ->hasViews();
    }

    public function packageRegistered(): void
    {
        /** @var array<int, class-string> $settings */
        $settings = Config::get('settings.settings', []);
        $settings[] = PixelSettings::class;

        Config::set('settings.settings', $settings);
    }

    public function packageBooted(): void
    {
        $migrationPath = __DIR__.'/../database/settings';

        $this->loadMigrationsFrom($migrationPath);

        $this->publishes([
            $migrationPath => database_path('settings'),
        ], 'pixel-settings-migrations');
    }
}
```

--------------------------------

### pixel_settings() Helper Function

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Global helper function that returns the PixelSettings instance from the container.

```php
use JeffersonGoncalves\Pixel\Settings\PixelSettings;

if (! function_exists('pixel_settings')) {
    function pixel_settings(): PixelSettings
    {
        return app(PixelSettings::class);
    }
}
```

--------------------------------

### Run tests, coverage, analysis, and formatting

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Run the package's test suite, coverage, static analysis, and code formatting. Requires Pest with pestphp/pest-plugin-laravel and orchestra/testbench.

```bash
composer test
composer test-coverage
composer analyse
composer format
```

--------------------------------

### Directory Structure of Laravel Pixel Package

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Shows the file and folder layout of the package, including the service provider, settings class, facade, helper, migration, and Blade view.

```text
src/
  PixelServiceProvider.php          # Package service provider
  Settings/
    PixelSettings.php               # Spatie Settings class (group: pixel)
  Facades/
    PixelSettings.php               # Laravel Facade for PixelSettings
  helpers.php                       # Global pixel_settings() helper function
database/
  settings/
    2026_02_20_000000_create_pixel_settings.php  # Settings migration
resources/
  views/
    script.blade.php                # Facebook Pixel tracking script Blade view
```

--------------------------------

### PixelSettings Facade

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Provides a Laravel facade that resolves to the PixelSettings class.

```php
namespace JeffersonGoncalves\Pixel\Facades;

use Illuminate\Support\Facades\Facade;
use JeffersonGoncalves\Pixel\Settings\PixelSettings as PixelSettingsClass;

class PixelSettings extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return PixelSettingsClass::class;
    }
}
```

--------------------------------

### Test PixelSettings defaults and group

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Pest tests for PixelSettings defaults and group. Verifies pixel_id is null by default and the settings group is 'pixel'.

```php
it('has the correct default values', function () {
    $settings = app(PixelSettings::class);

    expect($settings->pixel_id)->toBeNull();
});

it('belongs to the pixel group', function () {
    expect(PixelSettings::group())->toBe('pixel');
});
```

--------------------------------

### Set Pixel ID with Facade

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Set the Pixel ID using the PixelSettings facade.

```php
use JeffersonGoncalves\Pixel\Facades\PixelSettings;

$settings = PixelSettings::getFacadeRoot();
$settings->pixel_id = '123456789';
$settings->save();
```

--------------------------------

### Test PixelSettings facade resolution

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Pest test for the PixelSettings facade. Verifies that the facade root resolves to the PixelSettings class.

```php
use JeffersonGoncalves\Pixel\Facades\PixelSettings;

it('facade resolves to PixelSettings class', function () {
    expect(PixelSettings::getFacadeRoot())
        ->toBeInstanceOf(\JeffersonGoncalves\Pixel\Settings\PixelSettings::class);
});
```

--------------------------------

### Update pixel_id setting via container or helper

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Shows how to update the pixel_id setting using the container or the pixel_settings() helper. Both methods require calling save() to persist the change.

```php
$settings = app(PixelSettings::class);
$settings->pixel_id = '123456789012345';
$settings->save();

// Or via helper
$settings = pixel_settings();
$settings->pixel_id = '123456789012345';
$settings->save();
```

--------------------------------

### PixelSettings Class

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Defines the settings class using spatie/laravel-settings with group 'pixel' and a nullable pixel_id property.

```php
use Spatie\LaravelSettings\Settings;

class PixelSettings extends Settings
{
    public ?string $pixel_id = null;

    public static function group(): string
    {
        return 'pixel';
    }
}
```

--------------------------------

### Track custom events in Blade templates

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Shows how to track standard and custom events in Blade templates after including the Pixel script. Standard events use fbq('track', ...) and custom events use fbq('trackCustom', ...).

```blade
{{-- Standard events --}}
<script>
    fbq('track', 'Purchase', {value: 29.99, currency: 'USD'});
    fbq('track', 'Lead');
    fbq('track', 'CompleteRegistration');
</script>

{{-- Custom events --}}
<script>
    fbq('trackCustom', 'MyCustomEvent', {category: 'landing'});
</script>
```

--------------------------------

### Settings migration for pixel_id

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Migration that creates the pixel_id setting in the 'pixel' group with a null default value.

```php
return new class extends SettingsMigration
{
    public function up(): void
    {
        $this->migrator->add('pixel.pixel_id', null);
    }
};
```

--------------------------------

### Set Pixel ID via Container Resolution

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Set the Pixel ID using container resolution.

```php
use JeffersonGoncalves\Pixel\Settings\PixelSettings;

$settings = app(PixelSettings::class);
$settings->pixel_id = '123456789';
$settings->save();
```

--------------------------------

### Set Pixel ID with Helper Function

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Set the Pixel ID using the helper function.

```php
$settings = pixel_settings();
$settings->pixel_id = '123456789';
$settings->save();
```

--------------------------------

### Include pixel tracking script in layout

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Include the tracking script in your layout's head section using the Blade directive.

```blade
<head>
    @include('pixel::script')
</head>
```

--------------------------------

### Include Pixel Script in Layout

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Include the Blade component in your layout's <head> tag. The script only renders when a valid Pixel ID is configured; if null or empty, nothing is rendered.

```blade
@include('pixel::script')
```

--------------------------------

### Test pixel script rendering with Pest

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Pest tests for the pixel script blade view. Verifies that the Facebook Pixel script renders when pixel_id is set, is omitted when null, and includes the noscript fallback image.

```php
use JeffersonGoncalves\Pixel\Settings\PixelSettings;

it('renders the facebook pixel when pixel_id is set', function () {
    $settings = app(PixelSettings::class);
    $settings->pixel_id = '123456789012345';
    $settings->save();

    $view = $this->blade('@include("pixel::script")');

    $view->assertSee("fbq('init', '123456789012345')");
    $view->assertSee("fbq('track', 'PageView')");
    $view->assertSee('connect.facebook.net/en_US/fbevents.js');
});

it('does not render the script when pixel_id is null', function () {
    $settings = app(PixelSettings::class);
    $settings->pixel_id = null;
    $settings->save();

    $view = $this->blade('@include("pixel::script")');

    $view->assertDontSee('fbq');
    $view->assertDontSee('facebook');
});

it('renders the noscript fallback image', function () {
    $settings = app(PixelSettings::class);
    $settings->pixel_id = '123456789012345';
    $settings->save();

    $view = $this->blade('@include("pixel::script")');

    $view->assertSee('https://www.facebook.com/tr?id=123456789012345');
    $view->assertSee('<noscript>', false);
});
```

--------------------------------

### Read Pixel ID

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/README.md

Read the Pixel ID using the helper function. Returns string|null.

```php
$pixelId = pixel_settings()->pixel_id; // returns string|null
```

--------------------------------

### Blade View for Facebook Pixel

Source: https://github.com/jeffersongoncalves/laravel-pixel/blob/master/resources/boost/skills/pixel-development/SKILL.md

Conditionally renders the Facebook Pixel script and noscript fallback when pixel_id is set.

```blade
@if(!empty(pixel_settings()->pixel_id))
    <!-- Facebook Pixel Code -->
    <script>
        !function(f,b,e,v,n,t,s)
        {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
            n.callMethod.apply(n,arguments):n.queue.push(arguments)};
            if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
            n.queue=[];t=b.createElement(e);t.async=!0;
            t.src=v;s=b.getElementsByTagName(e)[0];
            s.parentNode.insertBefore(t,s)}(window, document,'script',
            'https://connect.facebook.net/en_US/fbevents.js');
        fbq('init', '{{ pixel_settings()->pixel_id }}');
        fbq('track', 'PageView');
    </script>
    <noscript>
        <img height="1" width="1" style="display:none"
             src="https://www.facebook.com/tr?id={{ pixel_settings()->pixel_id }}&ev=PageView&noscript=1"/>
    </noscript>
    <!-- End Facebook Pixel Code -->
@endif
```
Tokens:
Raw