Configuration

The published config/plausible.php in full:

<?php

declare(strict_types=1);

return [
    'url' => env('PLAUSIBLE_URL'),

    'key' => env('PLAUSIBLE_API_KEY'),

    'site' => env('PLAUSIBLE_SITE'),

    'timeout' => env('PLAUSIBLE_TIMEOUT', 10),

    'retry' => [
        'times' => env('PLAUSIBLE_RETRY_TIMES', 0),
        'sleep_ms' => env('PLAUSIBLE_RETRY_SLEEP', 100),
    ],

    'rate_limits' => [
        'stats' => [
            'enabled' => env('PLAUSIBLE_STATS_RATELIMIT_ENABLED', true),
            'owner' => env('PLAUSIBLE_RATELIMIT_OWNER', 'app'),
            'limit' => env('PLAUSIBLE_STATS_RATELIMIT', 600),
            'per' => env('PLAUSIBLE_STATS_RATELIMIT_PER', 'hour'),
            'adaptive' => env('PLAUSIBLE_STATS_RATELIMIT_ADAPTIVE', true),
            'max_wait' => env('PLAUSIBLE_STATS_RATELIMIT_MAX_WAIT'),
            'jitter' => env('PLAUSIBLE_STATS_RATELIMIT_JITTER'),
            'per_site' => env('PLAUSIBLE_STATS_RATELIMIT_PER_SITE', false),
        ],

        'events' => [
            'enabled' => env('PLAUSIBLE_EVENTS_RATELIMIT_ENABLED', true),
            'owner' => env('PLAUSIBLE_RATELIMIT_OWNER', 'app'),
            'limit' => env('PLAUSIBLE_EVENTS_RATELIMIT', 6000),
            'per' => env('PLAUSIBLE_EVENTS_RATELIMIT_PER', 'minute'),
            'adaptive' => env('PLAUSIBLE_EVENTS_RATELIMIT_ADAPTIVE', true),
            'max_wait' => env('PLAUSIBLE_EVENTS_RATELIMIT_MAX_WAIT'),
            'jitter' => env('PLAUSIBLE_EVENTS_RATELIMIT_JITTER'),
            'per_site' => env('PLAUSIBLE_EVENTS_RATELIMIT_PER_SITE', true),
        ],

        'sites' => [
            'enabled' => env('PLAUSIBLE_SITES_RATELIMIT_ENABLED', true),
            'owner' => env('PLAUSIBLE_RATELIMIT_OWNER', 'app'),
            'limit' => env('PLAUSIBLE_SITES_RATELIMIT', 60),
            'per' => env('PLAUSIBLE_SITES_RATELIMIT_PER', 'hour'),
            'adaptive' => env('PLAUSIBLE_SITES_RATELIMIT_ADAPTIVE', true),
            'max_wait' => env('PLAUSIBLE_SITES_RATELIMIT_MAX_WAIT'),
            'jitter' => env('PLAUSIBLE_SITES_RATELIMIT_JITTER'),
            'per_site' => env('PLAUSIBLE_SITES_RATELIMIT_PER_SITE', false),
        ],
    ],

    'tracking' => [
        'queue' => env('PLAUSIBLE_TRACKING_QUEUE', true),

        'user_agent' => env('PLAUSIBLE_TRACKING_USER_AGENT', 'PlausibleForLaravel'),

        'ip_address' => env('PLAUSIBLE_TRACKING_IP', '127.0.0.1'),
    ],

    'script' => [
        'domain' => env('PLAUSIBLE_SCRIPT_DOMAIN'),

        'src' => env('PLAUSIBLE_SCRIPT_SRC', 'https://plausible.io/js/script.js'),
    ],
];

Every key

Key	Default	Env	Purpose
`url`	—	PLAUSIBLE_URL	Base URL of your Plausible instance, e.g. https://plausible.io or your self-hosted domain. Required.
`key`	—	PLAUSIBLE_API_KEY	Your Plausible API key, sent as a Bearer token on Stats and Sites requests. Required for those; event capture neither needs nor sends it. See API keys below.
`site`	null	PLAUSIBLE_SITE	Optional default site (domain). Used by stats()->query(), the events helpers, the middleware, the Trackable trait, the script tag (when script.domain is unset) and the health check.
`timeout`	10	PLAUSIBLE_TIMEOUT	Per-request timeout in seconds, at least 1.
`retry.times`	0	PLAUSIBLE_RETRY_TIMES	Automatic retries on transient failures. 0 disables retries.
`retry.sleep_ms`	100	PLAUSIBLE_RETRY_SLEEP	Milliseconds to wait between retries.
`rate_limits.*`	see Rate limiting	PLAUSIBLE__RATELIMIT	Per-surface client-side rate limiting for stats, events and sites.
`tracking.queue`	true	PLAUSIBLE_TRACKING_QUEUE	Queue captures from the middleware and the Trackable trait so they never block the response. Accepts true/false, on/off, yes/no, 1/0; anything else throws an InvalidConfigurationException.
`tracking.user_agent`	PlausibleForLaravel	PLAUSIBLE_TRACKING_USER_AGENT	User-agent for server-side captures when no HTTP request is in scope.
`tracking.ip_address`	127.0.0.1	PLAUSIBLE_TRACKING_IP	IP for server-side captures when no HTTP request is in scope.
`script.domain`	null	PLAUSIBLE_SCRIPT_DOMAIN	data-domain for the tracking script. Uses site when not set (null or blank).
`script.src`	https://plausible.io/js/script.js	PLAUSIBLE_SCRIPT_SRC	URL of the hosted Plausible script — your self-hosted host or a script variant.

A missing url throws RoundlyConsulting\Plausible\Exceptions\MissingConfiguration (a PlausibleException) on the first call, and a missing key on the first Stats or Sites call, rather than sending a broken request. Event capture works without a key. Calls that need a site throw the same exception when none is passed and no default is set.

Every other setting is read strictly. A key that is not set — left out, or blank such as PLAUSIBLE_TIMEOUT= — takes the default above (a blank url, key or site counts as missing); a value of the wrong shape throws RoundlyConsulting\PackageToolkit\Exceptions\InvalidConfigurationException naming the key, and is never cast or replaced by the default. Integers take an int or a whole-number string — PLAUSIBLE_TIMEOUT=15 works, while five or 1.5 throw — and the user agent, IP address and script URL must be strings. The config file therefore passes env values through raw, with no (int) casts.

API keys

Plausible issues two kinds of API key (Settings → API keys → New API key):

a Stats API key — reads stats (stats()); Plausible limits it to 600 requests per hour by default, across every site the key’s team owns;
a Sites API key — provisions sites, goals and shared links (sites(), goals(), sharedLinks()); the Sites API is an Enterprise plan feature.

The package sends the one configured PLAUSIBLE_API_KEY as a Bearer token to the Stats and Sites APIs, so use the key type for the APIs you call. The Events API — events(), the middleware and the Trackable trait — is unauthenticated: it needs only PLAUSIBLE_URL, and the key is never sent there. php artisan plausible:health tells you whether the key works (see Health check).

Environment

Every key except the rate-limit blocks maps to one env variable — the values below are the defaults where one exists:

PLAUSIBLE_URL=https://plausible.io
PLAUSIBLE_API_KEY=your-api-key
PLAUSIBLE_SITE=my-site.com
PLAUSIBLE_TIMEOUT=10
PLAUSIBLE_RETRY_TIMES=0
PLAUSIBLE_RETRY_SLEEP=100
PLAUSIBLE_TRACKING_QUEUE=true
PLAUSIBLE_TRACKING_USER_AGENT=PlausibleForLaravel
PLAUSIBLE_TRACKING_IP=127.0.0.1
PLAUSIBLE_SCRIPT_DOMAIN=my-site.com
PLAUSIBLE_SCRIPT_SRC=https://plausible.io/js/script.js

The about command

The package contributes a Plausible section to php artisan about: the instance URL, whether the API key is SET or MISSING (the key itself is never printed), the default site, which surfaces are rate-limited, and whether tracking is queued.

php artisan about

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages