Pirsch for Laravel

https://github.com/pirsch-analytics/laravel-pirsch
Admin
Official Laravel integration for Pirsch Analytics that enables automatic and manual pageview...
Tokens:5,507
Snippets:36
Trust Score:8
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Pirsch Configuration and Environment Setup (PHP/INI)

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Details the configuration file for Pirsch, primarily focusing on setting the API token via environment variables. It shows how to publish the configuration and provides examples for setting the token in production and development environments.

```php
// config/pirsch.php
return [
    'token' => env('PIRSCH_TOKEN'),
];

```

```env
# .env - Production
PIRSCH_TOKEN=pa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# .env - Development/Testing (leave empty to disable tracking)
PIRSCH_TOKEN=

```

```bash
# Publish configuration (optional, config is auto-loaded)
php artisan vendor:publish --tag=laravel-pirsch-config

```

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

### Install Pirsch Analytics for Laravel

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Installs the Pirsch Analytics Laravel package via Composer and configures the access token in the .env file. This is the initial setup step for integrating Pirsch Analytics.

```bash
composer require pirsch-analytics/laravel-pirsch

PIRSCH_TOKEN=pa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

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

### Install Pirsch Laravel Package

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Installs the Pirsch Analytics Laravel package using Composer. This is the first step to integrate Pirsch tracking into your Laravel application.

```bash
composer require pirsch-analytics/laravel-pirsch
```

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

### Custom Middleware for Global Exclusions

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

This section explains how to create a custom middleware that extends Pirsch's `TrackPageview` middleware. You can define global URL patterns and headers to be excluded from tracking, centralizing your exclusion rules and enabling header-based filtering.

```APIDOC
## Custom Middleware with Global Exclusions

Create a custom middleware extending `TrackPageview` to define global URL and header exclusion patterns. This approach centralizes exclusion rules and allows for header-based filtering, useful for excluding requests from specific clients or internal services.

```php
<?php

namespace AppHttpMiddleware;

use Pirsch\Http\Middleware\TrackPageview as Middleware;

class TrackPageview extends Middleware
{
    /**
     * The URIs that should be excluded from tracking.
     *
     * @var array<int,string>
     */
    protected array $except = [
        'admin/*',
        'api/*',
        'health-check',
        'telescope/*',
        'horizon/*',
        '_debugbar/*',
    ];

    /**
     * The Headers that should be excluded from tracking.
     * Requests containing any of these headers will not be tracked.
     *
     * @var array<int,string>
     */
    protected array $exceptHeaders = [
        'X-Livewire',
        'X-Inertia-Partial-Data',
        'X-Health-Check',
        'X-Internal-Request',
    ];
}

// bootstrap/app.php - Use custom middleware instead of default
return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(append: [
            \App\Http\Middleware\TrackPageview::class,
        ]);
    })
    ->create();
```
```

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

### Manual Pageview and Event Tracking with Pirsch::track()

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Provides programmatic control for tracking pageviews and custom events using the Pirsch Facade. The `track()` method can be called without arguments for pageviews or with a name and optional metadata for custom events. Tracking is queued to execute during application termination.

```php
<?php

use Pirsch\Facades\Pirsch;

// Track a simple pageview for the current request
Pirsch::track();

// Track a custom event without metadata
Pirsch::track(name: 'Signup Completed');

// Track a custom event with metadata
Pirsch::track(
    name: 'Button clicked',
    meta: [
        'Label' => 'Get started',
        'Position' => 'Header',
    ],
);

// Example in a controller
class CheckoutController extends Controller
{
    public function complete(Order $order)
    {
        // Track the purchase event with order details
        Pirsch::track(
            name: 'Purchase Completed',
            meta: [
                'Order ID' => (string) $order->id,
                'Total' => (string) $order->total,
                'Items' => (string) $order->items->count(),
            ],
        );

        return view('checkout.complete', compact('order'));
    }
}
```

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

### Automatic Pageview Tracking with TrackPageview Middleware

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Automatically tracks pageviews for requests passing through the `TrackPageview` middleware. It intelligently skips redirects, Livewire AJAX requests, and specified exclusion patterns. The middleware can be applied globally or to specific route groups.

```php
<?php

// bootstrap/app.php - Apply globally to all web routes
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(append: [
            \Pirsch\Http\Middleware\TrackPageview::class,
        ]);
    })
    ->create();

// routes/web.php - Apply to specific route groups
use Pirsch\Http\Middleware\TrackPageview;

Route::middleware(TrackPageview::class)->group(function () {
    Route::get('/', function () {
        return view('welcome');
    });

    Route::get('/about', function () {
        return view('about');
    });

    Route::get('/contact', [ContactController::class, 'index']);
});

// Apply to a single route
Route::get('/pricing', function () {
    return view('pricing');
})->middleware(TrackPageview::class);
```

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

### Test Pirsch Analytics with Mocked HTTP in Laravel

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

This snippet demonstrates how to test Pirsch analytics functionality within a Laravel application by faking HTTP client requests. It covers manual pageview tracking, custom event tracking with metadata, and automatic tracking via middleware. Dependencies include Laravel's HTTP client and the Pirsch facade.

```php
<?php

use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Route;
use Pirsch\Facades\Pirsch;
use Pirsch\Http\Middleware\TrackPageview;

// Test manual pageview tracking
it('tracks a pageview', function () {
    config(['pirsch.token' => 'test_token']);
    Http::fake([
        'https://api.pirsch.io/api/v1/hit' => Http::response(),
    ]);

    Pirsch::track();
    $this->get('/');

    Http::assertSent(function (Request $request): bool {
        expect($request->url())->toBe('https://api.pirsch.io/api/v1/hit');
        expect($request->hasHeader('Authorization', 'Bearer test_token'))->toBeTrue();
        return true;
    });
});

// Test custom event tracking
it('tracks a custom event with metadata', function () {
    config(['pirsch.token' => 'test_token']);
    Http::fake([
        'https://api.pirsch.io/api/v1/event' => Http::response(),
    ]);

    Pirsch::track('Button Clicked', ['Label' => 'Sign Up']);
    $this->get('/');

    Http::assertSent(function (Request $request) {
        expect($request->url())->toBe('https://api.pirsch.io/api/v1/event');
        expect($request->data()['event_name'])->toBe('Button Clicked');
        expect($request->data()['event_meta'])->toBe(['Label' => 'Sign Up']);
        return true;
    });
});

// Test middleware tracking
it('automatically tracks via middleware', function () {
    Pirsch::shouldReceive('track')->once();

    Route::middleware(TrackPageview::class)
        ->get('/test', fn () => 'Hello World');

    $this->get('/test');
});

// Test middleware skips redirects
it('does not track redirects', function () {
    Pirsch::spy();

    Route::middleware(TrackPageview::class)
        ->get('/redirect', fn () => redirect('/destination'));

    $this->get('/redirect');

    Pirsch::shouldNotHaveReceived('track');
});

```

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

### Exclude URLs from Tracking with TrackPageview Middleware

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Configures the `TrackPageview` middleware to exclude specific URL patterns from tracking. Exclusions can be defined inline as middleware parameters (single or comma-separated) or globally via a custom middleware class. Laravel Telescope and Horizon routes are excluded by default.

```php
<?php

// routes/web.php - Exclude URLs via middleware parameters
use Pirsch\Http\Middleware\TrackPageview;

// Exclude a single URL pattern
Route::middleware(TrackPageview::class.':admin/*')->group(function () {
    Route::get('/', fn () => view('welcome'));
    Route::get('/admin/dashboard', fn () => view('admin.dashboard')); // Not tracked
});

// Exclude multiple URL patterns (comma-separated)
Route::middleware(TrackPageview::class.':admin/*,api/*,health-check')->group(function () {
    Route::get('/', fn () => view('welcome'));         // Tracked
    Route::get('/admin/users', fn () => 'users');      // Not tracked
    Route::get('/api/data', fn () => 'data');          // Not tracked
    Route::get('/health-check', fn () => 'OK');        // Not tracked
});
```

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

### API Request Structure for Pageview Tracking

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Illustrates the structure of data sent to the Pirsch API for pageview tracking. This includes comprehensive request metadata like client hints for accurate device detection. Tracking is performed at application termination to avoid blocking responses, with automatic retry logic.

```APIDOC
## API Request Structure

The package sends tracking data to the Pirsch API with comprehensive request metadata including client hints for accurate device detection. The tracking is executed during application termination to avoid blocking the response, with automatic retry logic for failed requests.

```php
<?php

// Data sent to Pirsch API for pageview tracking (POST https://api.pirsch.io/api/v1/hit)
$pageviewData = [
    'url' => 'https://example.com/page',          // Full URL of the request
    'ip' => '192.168.1.1',                        // Client IP address
    'user_agent' => 'Mozilla/5.0...',             // User agent string
    'accept_language' => 'en-us,en;q=0.5',        // Accept-Language header
    'sec_ch_ua' => '"Chromium";v="120"...',       // Client hint: browser
    'sec_ch_ua_mobile' => '?0',                   // Client hint: mobile
    'sec_ch_ua_platform' => '"macOS"',            // Client hint: platform
    'sec_ch_ua_platform_version' => '"14.0"',     // Client hint: platform version
    'sec_ch_width' => '1920',                     // Client hint: width
    'sec_ch_viewport_width' => '1920',            // Client hint: viewport width
    'referrer' => 'https://google.com',           // Referer header
];
```
```

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

### Configuration

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Details on how to configure the Pirsch API token for your Laravel application. The token should be a write-only access key from the Pirsch dashboard. It's recommended to leave the token empty in non-production environments to disable tracking.

```APIDOC
## Configuration

The package publishes a configuration file to set the Pirsch API token. The token should be a write-only access key obtained from the Pirsch dashboard. Leave the token empty in non-production environments to disable tracking.

```php
<?php

// config/pirsch.php
return [
    'token' => env('PIRSCH_TOKEN'),
];

// .env - Production
PIRSCH_TOKEN=pa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// .env - Development/Testing (leave empty to disable tracking)
PIRSCH_TOKEN=

// Publish configuration (optional, config is auto-loaded)
php artisan vendor:publish --tag=laravel-pirsch-config
```
```

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

### Replace Middleware with Custom Exclusion Middleware

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Replaces the default Pirsch TrackPageview middleware with a custom one in bootstrap/app.php to apply global exclusion rules. This ensures that pages and headers defined in the custom middleware are not tracked.

```php
use Illuminate\Support\Facades\Middleware;
use Illuminate\Foundation\Application;

// ...

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \App\Http\Middleware\TrackPageview::class,
    ]);
})
```

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

### Custom Middleware for Pirsch Tracking Exclusions (PHP)

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Extends the default Pirsch `TrackPageview` middleware to define custom URL patterns and headers that should be excluded from tracking. This allows for centralized management of exclusion rules, enhancing flexibility for specific application needs.

```php
<?php

namespace App\Http\Middleware;

use Pirsch\Http\Middleware\TrackPageview as Middleware;

class TrackPageview extends Middleware
{
    /**
     * The URIs that should be excluded from tracking.
     *
     * @var array<int,string>
     */
    protected array $except = [
        'admin/*',
        'api/*',
        'health-check',
        'telescope/*',
        'horizon/*',
        '_debugbar/*',
    ];

    /**
     * The Headers that should be excluded from tracking.
     * Requests containing any of these headers will not be tracked.
     *
     * @var array<int,string>
     */
    protected array $exceptHeaders = [
        'X-Livewire',
        'X-Inertia-Partial-Data',
        'X-Health-Check',
        'X-Internal-Request',
    ];
}

// bootstrap/app.php - Use custom middleware instead of default
return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(append: [
            \App\Http\Middleware\TrackPageview::class,
        ]);
    })
    ->create();

```

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

### Automatically Track Pageviews with Middleware

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Applies the TrackPageview middleware globally to all web routes in bootstrap/app.php to automatically track pageviews. This middleware intercepts requests and sends pageview data to Pirsch.

```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Pirsch\Http\Middleware\TrackPageview::class,
    ]);
})
```

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

### Globally Exclude URLs and Headers from Tracking

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Creates a custom middleware extending Pirsch's TrackPageview to globally exclude specific URI paths and headers from tracking. This provides a centralized way to manage exclusion rules for all tracked pages.

```php
namespace App\Http\Middleware;

use Pirsch\Http\Middleware\TrackPageview as Middleware;

class TrackPageview extends Middleware
{
    /**
     * The URIs that should be excluded from tracking.
     *
     * @var array<int,string>
     */
    protected array $except = [
        'url/to/exclude/*',
    ];

    /**
     * The Headers that should be excluded from tracking.
     *
     * @var array<int,string>
     */
    protected array $exceptHeaders = [
        'X-ExcludedHeader',
    ];
}
```

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

### Configure Pirsch Token in .env

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Adds the Pirsch access token to your Laravel application's .env file. Obtain the token from the Pirsch dashboard integration settings. Tracking is disabled in non-production environments if the token is empty.

```dotenv
PIRSCH_TOKEN=pa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

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

### Manually Track Pageviews

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Manually tracks a pageview for the current HTTP request using the Pirsch::track() facade method. This is an alternative to using the middleware for tracking pageviews.

```php
use Pirsch\Facades\Pirsch;

Pirsch::track();
```

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

### Exclude Multiple URLs from Tracking (Route Level)

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Configures the TrackPageview middleware to exclude multiple URL patterns from being tracked on a per-route basis by separating them with commas. This provides flexibility in defining exclusion rules.

```php
use Pirsch\Http\Middleware\TrackPageview;

Route::middleware(TrackPageview::class.':url/to/exclude/*,url/to/exclude2/*')->group(function () {
    Route::get('/', function () {
        return view('welcome');
    });
});
```

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

### API Request Structure for Event Tracking

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Shows the data structure for sending custom event tracking data to the Pirsch API. This includes standard request metadata along with a custom event name and optional metadata for richer event analysis.

```APIDOC
// Data sent for event tracking (POST https://api.pirsch.io/api/v1/event)
$eventData = [
    'url' => 'https://example.com/checkout',
    'ip' => '192.168.1.1',
    'user_agent' => 'Mozilla/5.0...',
    'accept_language' => 'en-us,en;q=0.5',
    'sec_ch_ua' => '"Chromium";v="120"...',
    'sec_ch_ua_mobile' => '?0',
    'sec_ch_ua_platform' => '"macOS"',
    'sec_ch_ua_platform_version' => '"14.0"',
    'sec_ch_width' => '1920',
    'sec_ch_viewport_width' => '1920',
    'referrer' => 'https://example.com/cart',
    'event_name' => 'Purchase Completed',          // Custom event name
    'event_meta' => [
        'Order ID' => '12345',
        'Total' => '99.99',
    ],                                            // Optional metadata
];
```
```

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

### Manually Track Custom Events

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Tracks custom events with an optional name and metadata using the Pirsch::track() facade method. This allows for measuring specific user interactions beyond pageviews.

```php
use Pirsch\Facades\Pirsch;

Pirsch::track(
    name: 'Button clicked',
    meta: [
        'Label' => 'Get started',
    ],
);
```

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

### Track Pageviews on Specific Routes

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Applies the TrackPageview middleware to specific routes or route groups. This allows for more granular control over which pages are tracked by Pirsch Analytics.

```php
use Pirsch\Http\Middleware\TrackPageview;

Route::middleware(TrackPageview::class)->group(function () {
    Route::get('/', function () {
        return view('welcome');
    });
});
```

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

### Pirsch API Request Data Structures (PHP)

Source: https://context7.com/pirsch-analytics/laravel-pirsch/llms.txt

Illustrates the structure of data payloads sent to the Pirsch API for tracking pageviews and custom events. Includes comprehensive request metadata and optional event-specific details for detailed analytics.

```php
// Data sent to Pirsch API for pageview tracking (POST https://api.pirsch.io/api/v1/hit)
$pageviewData = [
    'url' => 'https://example.com/page',          // Full URL of the request
    'ip' => '192.168.1.1',                        // Client IP address
    'user_agent' => 'Mozilla/5.0...',             // User agent string
    'accept_language' => 'en-us,en;q=0.5',        // Accept-Language header
    'sec_ch_ua' => '"Chromium";v="120"...',       // Client hint: browser
    'sec_ch_ua_mobile' => '?0',                   // Client hint: mobile
    'sec_ch_ua_platform' => '"macOS"',            // Client hint: platform
    'sec_ch_ua_platform_version' => '"14.0"',     // Client hint: platform version
    'sec_ch_width' => '1920',                     // Client hint: width
    'sec_ch_viewport_width' => '1920',            // Client hint: viewport width
    'referrer' => 'https://google.com',           // Referer header
];

// Data sent for event tracking (POST https://api.pirsch.io/api/v1/event)
$eventData = [
    'url' => 'https://example.com/checkout',
    'ip' => '192.168.1.1',
    'user_agent' => 'Mozilla/5.0...',
    'accept_language' => 'en-us,en;q=0.5',
    'sec_ch_ua' => '"Chromium";v="120"...',
    'sec_ch_ua_mobile' => '?0',
    'sec_ch_ua_platform' => '"macOS"',
    'sec_ch_ua_platform_version' => '"14.0"',
    'sec_ch_width' => '1920',
    'sec_ch_viewport_width' => '1920',
    'referrer' => 'https://example.com/cart',
    'event_name' => 'Purchase Completed',          // Custom event name
    'event_meta' => [                              // Optional metadata
        'Order ID' => '12345',
        'Total' => '99.99',
    ],
];

```

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

### Exclude Specific URLs from Tracking (Route Level)

Source: https://github.com/pirsch-analytics/laravel-pirsch/blob/master/README.md

Configures the TrackPageview middleware to exclude specific URL patterns from being tracked on a per-route basis. This is useful for preventing tracking of sensitive or irrelevant pages.

```php
use Pirsch\Http\Middleware\TrackPageview;

Route::middleware(TrackPageview::class.':url/to/exclude/*')->group(function () {
    Route::get('/', function () {
        return view('welcome');
    });
});
```
Tokens:
Raw