README

This package was originally created by @njoguamos - njoguamos/laravel-plausible

I had to make this adaptation because the original project only supports Plausible.io and not self-hosted analytics, I made a change so that the base address of the plausible can be manipulated both by configuration and by method, so we can manage several self-hosted Plausible in a single Apis system

Plausible is intuitive, lightweight and open source web analytics. Plausible has no cookies and fully compliant with GDPR, CCPA and PECR.

Plausible Self Hosting Docs Plausible Analytics is designed to be self-hosted through Docker. You don't have to be a Docker expert to launch your own instance of Plausible Analytics. You should have a basic understanding of the command-line and networking to successfully set up your own instance of Plausible Analytics.

Installation

You can install the package via composer:

   composer require tallesairan/laravel-plausible

You can initialise the package with:

  php artisan plausible:install

Install command will publish the config file.

Ensure that you have updated your application .env with credentials from Plausible i.e.

#.env file

BASE_URL=https://your-self-hosted-address.io
PLAUSIBLE_SITE_ID=
PLAUSIBLE_API_KEY=

Optional baseUrl or siteId over facade

Develop these methods to help manage multiple plausible self-hosted remotely

default url base is "https://plausible.io" to ensure the operation enter the url without the slash at the end

use Airan\Plausible\Facades\Plausible;

Plausible::setBaseUrl('https://your-self-hosted-address.io');
Plausible::setSiteId('newera.com');
Plausible::setApiKey('eg-nw88131238128jj9213u1h3h1hh13h2h31200x1h5hh5')
/**
* Practical example
*/
# Let's assume that the Site Model has a belongs to many relationship with a model called Plausible

$sites = Site:with('plausible')->get();

foreach ($sites as $site){
    Plausible::setBaseUrl($site->plausible->base_url); // eg https://stats.newera.com
    Plausible::setApiKey($site->plausible->api_key); // set default api key
    Plausible::setSiteId($site->plausible_slug); // eg newera.com 
    
    $visitors = Plausible::realtime();
    $aggregates = Plausible::aggregates();
    ...
    
}

Usage

1. Getting Realtime Visitors

To get the current visitors on your default site, run a request as follows.

use Airan\Plausible\Facades\Plausible;

$visitors = Plausible::realtime();

The response in a single digit number

12

If you prefer using facades, then you can do as follows.

use Airan\Plausible\Facades\Plausible;

$all = Plausible::aggregates();

2. Getting Aggregates

To get the aggregates, run a request as follows.

use Airan\Plausible\Facades\Plausible;

// Simple with default
$aggregates = Plausible::aggregates();

// Or with optional custom parameters
$aggregates = Plausible::aggregates(
        period: 'custom',
        metrics: ['visitors', 'visits', 'pageviews'],
        filters: ['event:page==/blog**', 'visit:country==KE'],
        date: '2023-01-01,2023-01-31'
    );

A successful response will be a json. Example;

{
    "bounce_rate": {
        "change": 4,
        "value": 71
    },
    "events": {
        "change": -24,
        "value": 1166
    },
    "pageviews": {
        "change": -24,
        "value": 1166
    },
    "views_per_visit": {
        "change": -26,
        "value": 3
    },
    "visit_duration": {
        "change": -37,
        "value": 132
    },
    "visitors": {
        "change": 1,
        "value": 360
    },
    "visits": {
        "change": 3,
        "value": 389
    }
}

Aggregates parameters explained expand to view more details.

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::aggregates(period: '7d')

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::aggregates(metrics: ['visitors', 'visits'])

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::aggregates(compare: false )

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::aggregates(filters: ['event:page==/blog**', 'visit:country==KE|DE'])

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::aggregates(period: 'custom', date: '2023-01-01,2023-01-31')

3. Getting Time Series

To get the timeseries data over a certain time period, run a request as follows.

use Airan\Plausible\Facades\Plausible;

// Simple with default
$aggregates = Plausible::timeSeries();

// Or with optional custom parameters
$aggregates = Plausible::timeSeries(
        period: 'custom',
        metrics: ['visitors', 'visits', 'pageviews', 'views_per_visit', 'bounce_rate', 'visit_duration'],
        filters: ['event:page==/blog**'],
        interval: 'month',
        date: '2023-01-01,2023-01-31'
    );

A successful response will be a json. Example;

[
    {
        "bounce_rate": 17,
        "date": "2023-01-01",
        "pageviews": 60,
        "views_per_visit": 19,
        "visit_duration": 525,
        "visitors": 6,
        "visits": 6
    },
    {
        "bounce_rate": 12,
        "date": "2023-01-02",
        "pageviews": 22,
        "views_per_visit": 4,
        "visit_duration": 149,
        "visitors": 6,
        "visits": 8
    },
    {
        "bounce_rate": 57,
        "date": "2023-01-03",
        "pageviews": 9,
        "views_per_visit": 2.57,
        "visit_duration": 48,
        "visitors": 7,
        "visits": 7
    },
    {
        "bounce_rate": 71,
        "date": "2023-01-04",
        "pageviews": 48,
        "views_per_visit": 8.43,
        "visit_duration": 301,
        "visitors": 7,
        "visits": 7
    }
]

Timeseries parameters explained expand to view more details.

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::timeSeries(period: '6mo')

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::timeSeries(metrics: ['visits', 'pageviews', 'views_per_visit'])

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::timeSeries(filters: ['event:page==/blog**', 'visit:browser==Firefox'])

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::timeSeries(interval: 'month')

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::timeSeries(period: 'custom', date: '2023-01-01,2023-01-31')

4. Getting Breakdowns

To get a breakdown of your stats by some property, run a request as follows.

use \Airan\Plausible\Facades\Plausible;

// Simple with defaults
$visitors = Plausible::breakdown();

// With optional parameters
$aggregates = Plausible::breakdown(
        property: 'event:page',
        period: '12mo',
        metrics: ['visitors', 'visits', 'pageviews'],
        filters: 'event:page==/blog**',
        limit: 500
    );

The response in a single digit number

[
    {
        "bounce_rate": 71,
        "page": "/",
        "pageviews": 146,
        "visit_duration": 126,
        "visitors": 87,
        "visits": 77
    },
    {
        "bounce_rate": 54,
        "page": "/articles",
        "pageviews": 179,
        "visit_duration": 206,
        "visitors": 71,
        "visits": 50
    },
    {
        "bounce_rate": 81,
        "page": "/blog/about-laravel-plausible",
        "pageviews": 42,
        "visit_duration": 27,
        "visitors": 35,
        "visits": 37
    },
    {
        "bounce_rate": 52,
        "page": "/pricing",
        "pageviews": 72,
        "visit_duration": 147,
        "visitors": 31,
        "visits": 27
    },
    {
        "bounce_rate": 76,
        "page": "/aquatadas",
        "pageviews": 22,
        "visit_duration": 82,
        "visitors": 21,
        "visits": 21
    }
]

Breakdown parameters explained expand to view more details.

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::breakdown(property: '6mo')

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::breakdown(period: '6mo')

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::breakdown(date: '2023-01-01')

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::breakdown(metrics: ['visits', 'pageviews', 'views_per_visit'])

use Airan\Plausible\Facades\Plausible;;

$aggregates = Plausible::breakdown(limit: 200)

use Airan\Plausible\Facades\Plausible;;

$aggregates = Plausible::breakdown(page: 2)

use Airan\Plausible\Facades\Plausible;

$aggregates = Plausible::breakdown(filters: 'event:page==/blog**')

5. Caching Response

To increased performance of your application and reduce reliance to plausible api, all requests are cached for 3 minutes. You can specify cache duration (in seconds) and driver using the following env variables.

PLAUSIBLE_CACHE_DURATION=300
PLAUSIBLE_CACHE_DRIVER=redis

If for some reason you don't want to cache response, you can turn off caching entirely by adding the following env variable.

PLAUSIBLE_CACHE=false

Testing

Info To test this package, run the following command.

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Njogu Amos
• All Contributors

License

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