README

A Laravel module for Plausible Analytics. It serves the Plausible script and events through your own domain (a first-party proxy), so they aren't blocked by ad-blockers that block the Plausible domain.

Requirements

PHP 8.3+
Laravel 11, 12 or 13

Installation

The package isn't published on Packagist, add one of the following repositories to your composer.json first.

GitLab package registry

Tagged releases are published to the GitLab Composer package registry, which is accessed at the group level:

"repositories": [
    {
        "type": "composer",
        "url": "https://gitlab.com/api/v4/group/<group_id>/-/packages/composer/packages.json"
    }
]

The registry requires authentication, use a personal access token (read_api scope) or a deploy token (read_package_registry scope):

composer config gitlab-token.gitlab.com <token>

Git repository

"repositories": [
    {
        "type": "vcs",
        "url": "https://gitlab.com/Justin991q/laravel-plausible-tracking.git"
    }
]

Then require it:

composer require justin991q/plausible-tracking

The PlausibleServiceProvider is registered automatically via package discovery.

Configuration

Add the following variables to your .env file:

PLAUSIBLE_ENABLED=true
PLAUSIBLE_URL=https://plausible.io
PLAUSIBLE_TRACKING_ID=XXXXXX

Variable	Required	Default	Description
`PLAUSIBLE_ENABLED`	No	`false`	Enable tracking and register the proxy routes
`PLAUSIBLE_URL`	No	`https://plausible.io`	Base URL of Plausible, or of your self-hosted instance
`PLAUSIBLE_TRACKING_ID`	Yes	—	The ID from your site's script URL: `https://plausible.io/js/pa-XXXXXX.js`

To customise the config file, publish it:

php artisan vendor:publish --tag=plausible-config

Usage

Include the tracking snippet in your layout. It renders nothing when PLAUSIBLE_ENABLED is false:

@include('plausible::tracking', ['init' => []])

The init array is required, its options are passed to plausible.init(), for example custom properties:

@include('plausible::tracking', [
    'init' => [
        'customProperties' => [
            'plan' => auth()->user()?->plan ?? 'guest',
        ],
    ],
])

The endpoint option is always set to the proxy's event route. Pass a CSP nonce to add it to both <script> tags:

@include('plausible::tracking', ['init' => [], 'csp' => app('csp-nonce')])

Custom events work as described in the Plausible documentation, they are sent through the proxy as well:

plausible('Signup', { props: { method: 'email' } });

Proxy Routes

When PLAUSIBLE_ENABLED=true, the module registers two routes:

Method	URI	Name	Description
`GET`	`/pl/js/script.js`	`plausible.script`	Your site's Plausible script, cached for 24 hours
`POST`	`/pl/api/event`	`plausible.event`	Forwards events to `{PLAUSIBLE_URL}/api/event`

Events are forwarded with the visitor's user agent and IP (X-Forwarded-For), so Plausible counts unique visitors correctly. Make sure $request->ip() returns the real client IP when your app runs behind a load balancer or CDN (trusted proxies).

The routes are registered without middleware groups, so the event route has no session or CSRF protection, as the Plausible script doesn't send a CSRF token.

If fetching the script fails, an empty script is served and cached for 24 hours. Clear it with:

php artisan cache:forget plausible-script

Testing

composer install
composer test

The GitLab CI pipeline runs the test suite on PHP 8.3, 8.4 and 8.5 against Laravel 11 (PHP 8.3 and 8.4 only), 12 and 13.

Releasing

Push a semver tag, after the tests pass the pipeline publishes it to the GitLab package registry:

git tag v1.0.0
git push origin v1.0.0

License

The MIT License (MIT). See LICENSE for details.

justin991q / plausible-tracking

Package info

Security

Statistics