Configuration

Two values control everything: the canonical domain every URL is built from, and whether trailing slashes are trimmed. Both read from the environment, so publishing the config file is optional.

CANONICAL_DOMAIN=https://example.com
CANONICAL_TRIM_TRAILING_SLASH=true

return [
    'domain' => 'https://example.com',
    'trim_trailing_slash' => true,
];

The service provider merges its own config, so the package runs without publishing anything. Publish only to keep the defaults in your repo:

php artisan vendor:publish --tag="canonical-config"

return [
    // The domain every canonical URL is built from. Falls back to APP_URL,
    // then http://localhost, when CANONICAL_DOMAIN is unset.
    'domain' => env('CANONICAL_DOMAIN', env('APP_URL', 'http://localhost')),

    // Trim trailing slashes from generated URLs (/blog/ → /blog). @since 1.1.0
    'trim_trailing_slash' => env('CANONICAL_TRIM_TRAILING_SLASH', true),
];

Every generated URL is built from this value, never from the host the request arrived on:

CANONICAL_DOMAIN=https://example.com

Unset, it falls back to APP_URL, then to http://localhost.

Trailing slashes are trimmed by default, so /blog/ and /blog collapse to one URL. Turn it off when the two are distinct routes:

CANONICAL_TRIM_TRAILING_SLASH=false

Query parameters are preserved under both settings.

The domain is validated on first use. It must be a valid URL, use the http or https scheme, and include a host:

CANONICAL_DOMAIN=https://example.com
CANONICAL_DOMAIN=http://localhost:8000
CANONICAL_DOMAIN=https://example.com/

A trailing slash on the domain is stripped before validation, so the third form behaves like the first. These throw CanonicalConfigurationException:

CANONICAL_DOMAIN=example.com
CANONICAL_DOMAIN=ftp://example.com
CANONICAL_DOMAIN=