Configuration
You can customise Patrol’s settings using a PHP configuration file. This is optional: each setting has a default, so you only need to include the values you want to change.
To override a setting, create patrol.php in your Craft project’s /config directory and return an array of setting names and values. For example, the following will use /maintenance as the maintenance page:
<?php
return [
'maintenanceModePageUrl' => '/maintenance',
];All other settings keep their defaults. Add any further settings you want to change to the same array. The options below explain the available settings and their defaults.
Configuration Options
Type: string · Default: ''
Primary domain to enforce.
Type: int · Default: 302
Redirect status code to use when redirecting.
Type: string · Default: ''
Tells Patrol what base URL to use when redirecting to SSL.
Type: bool · Default: false
Tells Patrol to force requests to be made over https://.
Type: array · Default: ['/']
Tells Patrol where https:// should be enforced.
Type: bool · Default: false
Tells Patrol that your site is on maintenance mode and it should start routing traffic differently. Authorized users will see your site while unauthorized users will see either your offline page or an HTTP response with a custom status code.
Type: array · Default: ['::1', '127.0.0.1']
Exact IP addresses that should be allowed (without being logged in) during maintenance. Wildcards and partial-address prefixes are not supported.
Patrol uses the direct peer address unless the request came from a concrete proxy IP address or CIDR configured in Craft’s trustedHosts setting and the forwarded header is permitted by that proxy entry and Craft’s ipHeaders setting. Craft’s default trustedHosts value of any is not treated as a trusted proxy boundary for maintenance access. Configure the real proxy ranges rather than trusting forwarding headers from every caller.
Type: int · Default: 403
Tells Patrol what kind of HttpException to throw if you do not set a $maintenanceModePageUrl.
Type: array · Default: []
Access tokens that can be used to automatically add an IP to the allowed list.
Access Tokens
Access tokens allow you to give someone access from their current IP address. Generate a unique token from your Craft project directory:
php craft patrol/access-token/generateStore the generated value in an environment variable, then add it to your project’s config/patrol.php file:
<?php
use craft\helpers\App;
return [
'maintenanceModeAccessTokens' => [
App::env('PATROL_MAINTENANCE_TOKEN'),
],
];Send the person a link on the site's canonical HTTPS domain containing the token as the access query parameter. When they visit the link, Patrol adds their IP address to the allowed list and redirects them to the same URL without the token. Links opened over HTTP or on another domain are redirected without granting access.
Treat each token as a reusable password: generate a different token for each site, send it only over a secure channel, and replace it if it has been shared more widely than intended. Removing or replacing a token prevents future use of the link but does not remove IP addresses that were already authorized.
Type: string · Default: '/offline'
The URL of the page shown during maintenance. Set this to the maintenance page you have created for your site.
Control Panel
You can also manage configuration settings through the Control Panel by visiting Settings → Patrol.