# laravel-plausible-proxy

[![Latest Version on Packagist](https://img.shields.io/packagist/v/mattitja/laravel-plausible-proxy.svg?style=flat-square)](https://packagist.org/packages/mattitja/laravel-plausible-proxy)
[![Tests](https://git.mattitja.se/Github/laravel-plausible-proxy/actions/workflows/ci.yml/badge.svg?branch=main)](https://git.mattitja.se/Github/laravel-plausible-proxy/actions?workflow=ci.yml)
[![Code Style](https://git.mattitja.se/Github/laravel-plausible-proxy/actions/workflows/fix-php-code-style-issues.yml/badge.svg?branch=main)](https://git.mattitja.se/Github/laravel-plausible-proxy/actions?workflow=fix-php-code-style-issues.yml)
[![Total Downloads](https://img.shields.io/packagist/dt/mattitja/laravel-plausible-proxy.svg?style=flat-square)](https://packagist.org/packages/mattitja/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:
   ```sh
   composer require mattitja/laravel-plausible-proxy
   ```

2. Publish the configuration file:
   ```sh
   php artisan vendor:publish --tag=plausible-proxy-config
   ```

3. Add the following environment variable to your `.env` file:
   ```env
   PLAUSIBLE_DOMAIN=https://plausible.io
   ```

## Configuration

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

```php
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:

```html
<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`:

```env
PLAUSIBLE_SCRIPT=js/pa-12345ABCDE.js
```

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

```html
<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:

```env
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](https://laravel.com/docs/requests#configuring-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:
   ```sh
   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

```sh
composer test
```

## Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

## Security Vulnerabilities

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

## Credits

- [Mathias Palmqvist](https://github.com/mathiaspalmqvist)

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.