laravel-plausible-proxy/README.md

laravel-plausible-proxy

A Laravel package for proxying Plausible Analytics, improving performance and privacy.

Requirements

• Laravel 12 or 13
• PHP 8.3, 8.4 or 8.5

Installation

1. Install the package via Composer:

   composer require mattitja/laravel-plausible-proxy
   

2. Publish the configuration file:

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

3. Add the following environment variable to your .env file:

   PLAUSIBLE_DOMAIN=https://plausible.io
   

Configuration

The config/plausible-proxy.php file allows you to customize the Plausible domain:

return [
    'domain' => env('PLAUSIBLE_DOMAIN', 'https://plausible.io'),
    'script' => env('PLAUSIBLE_SCRIPT', 'js/script.js'),
];

PLAUSIBLE_SCRIPT is the path of the script on your Plausible instance. Whatever script you choose, it is always served locally from /js/script.js.

Usage

1. Proxying the JavaScript file

This package proxies Plausible's script.js while caching it to improve performance and reduce external requests.

After installation, you can include the script like this:

<script defer data-domain="example.com" src="/js/script.js"></script>

The route /js/script.js is handled automatically and caches the script for 6 hours.

Site-specific script (pa-XXXXX.js)

Plausible's current installation instructions use a site-specific script such as https://plausible.io/js/pa-12345ABCDE.js, where optional measurements (outbound links, file downloads, etc.) are configured in the Plausible dashboard. To use it, set the script path in your .env:

PLAUSIBLE_SCRIPT=js/pa-12345ABCDE.js

Then load it locally and tell it to send events through the proxy with the endpoint option:

<script async src="/js/script.js"></script>
<script>
  window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};
  plausible.init({ endpoint: '/api/event' })
</script>

Legacy script extensions

Legacy script variants work the same way, for example:

PLAUSIBLE_SCRIPT=js/script.outbound-links.js

2. Sending events to Plausible

The script loaded from /js/script.js sends events to /api/event on your own domain, which forwards them to Plausible. This helps prevent blocking by ad blockers.

Only the visitor's User-Agent and IP address (as X-Forwarded-For) are forwarded to Plausible, which is what Plausible needs to count unique visitors. Cookies and other request headers are never forwarded.

If your application runs behind a load balancer or reverse proxy, make sure Laravel's trusted proxies are configured so the correct visitor IP is resolved.

Upgrading from mattitjaab/laravel-plausible-proxy

Version 2.0 renames the package and its namespace:

1. Replace the package:

   composer remove mattitjaab/laravel-plausible-proxy
   composer require mattitja/laravel-plausible-proxy
   

2. If you reference any package classes directly, change the namespace from MattitjaAB\LaravelPlausibleProxy to Mattitja\LaravelPlausibleProxy.
3. Laravel 10 is no longer supported.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please report security vulnerabilities by email to hej@mattitja.se.

Credits

• Mathias Palmqvist

License

The MIT License (MIT). Please see License File for more information.