
Production Preflight for Laravel
A misconfigured production application rarely fails. APP_DEBUG=true serves pages, QUEUE_CONNECTION=sync works through every job, MAIL_MAILER=log accepts every message, and a key set twice in .env is valid syntax. Nothing turns red, and the problem shows when someone goes looking for it, or when a customer calls.
This package checks for those states twice: once in the deploy, so they never go live, and then on a schedule, because half of them appear after the go-live. A value changed on the server without config:cache, workers that never heard queue:restart, a migration nobody ran.
The checks are laravel-health checks, so they report through what the application already runs: its result store, its notifications and its monitoring endpoint. The deploy gets its own command, with an exit code that stops it.
Installation
composer require pushery/production-preflight-for-laravel
The service provider is registered automatically through package discovery. The package requires spatie/laravel-health, which Composer installs alongside.
Quick start
Stop a deploy on a finding. In the deploy script, after composer install and before the application goes live:
php artisan preflight --deploy
It exits with 0 when no check failed, 1 when one did, and 2 when a check could not look. A warning is printed and lets the deploy through. Deploying has the complete script for Forge.
Report in operation. Register the checks with laravel-health, in the boot method of a service provider:
use Pushery\ProductionPreflight\Preflight;
use Spatie\Health\Facades\Health;
Health::checks(Preflight::healthChecks());
laravel-health then runs them with health:check, which the application schedules. In operation covers the schedule and the checks that need more than the defaults.
Look yourself. On the server, without --deploy, the command runs every check and prints the report:
php artisan preflight
What it checks
Twenty-eight checks in three groups, sorted by what they need in order to answer. The checks page lists each with its verdict.
| Group | Needs | Runs |
|---|---|---|
The .env file | the file, read as text | in a pipeline, in the deploy, on a schedule |
| The configuration | the loaded configuration | in the deploy and on a schedule |
| The installation | the server itself | on a schedule only |
Each check answers with one of four verdicts: pass, warning, fail, or not checked. "Not checked" is never a pass. A check that could not look, a missing file or a fact the command line cannot see, says so, and the deploy command exits with 2 for it.
Configuration
Publish the configuration file, where every option is documented inline:
php artisan vendor:publish --tag=production-preflight-config
| Tag | Publishes |
|---|---|
production-preflight | everything below, in one command |
production-preflight-config | the configuration file |
production-preflight-lang | the translation files |
The checks report in the application's locale, in English, German, Spanish, French, Italian,
Dutch or Portuguese. A regional locale reads the catalog of its language: pt-BR and pt-PT
read pt, de-AT reads de. A file you publish for the region under
lang/vendor/production-preflight/pt-BR/ wins over the language key by key.
A setting that reads an environment variable changes without publishing the file:
| Environment variable | Setting | Default |
|---|---|---|
PRODUCTION_ | production-preflight. | the .env in the base path |
PRODUCTION_ | production-preflight. | the .env.example in the base path |
PRODUCTION_ | production-preflight. | off |
PRODUCTION_ | production-preflight. | 5 seconds |
PRODUCTION_ | production-preflight. | none |
PRODUCTION_ | production-preflight. | 10 seconds |
PRODUCTION_ | production-preflight. | 15 minutes |
The probe switch is on only for true, 1, yes and on, in any case. A timeout that is no number, or one below 1, keeps its default. The grace of config-cache-fresh may be 0, which reports at once, and one that is no number, or below 0, keeps its default.
Stages
The production rules apply in production and on staging. A staging installation often holds real customer data, and a check that listened to production alone would stay quiet exactly there. The stage is read from app.env, against the names in production-preflight.stages:
'stages' => [
'production' => ['production', 'prod', 'live'],
'staging' => ['staging', 'stage', 'preprod', 'uat'],
'development' => ['local', 'testing', 'test', 'dev', 'development', 'ci'],
],
A name on none of the lists is undetermined, never development, so a server that declares a name nobody mapped is not taken for a laptop. Add the name to the right list.
A server can still declare a development stage: Laravel's .env.example sets APP_ENV=local, and an environment that began as a copy of it keeps that, and every production check then passes. development-stage-server reads a development stage against the host of app.url and fails where it is no host a machine for development is served under: localhost, a loopback or private address, or a name ending in one of development_hosts.
'development_hosts' => ['.test', '.localhost', '.local'],
Acknowledging a check
Some findings are decisions. QUEUE_CONNECTION=sync on an installation one person uses is one. Acknowledge such a check by its key, with the reason:
'acknowledged' => [
'queue-connection' => 'One person uses this installation; jobs run in the request on purpose.',
],
An acknowledged check passes, and its summary names the reason and what was found, in the console, in the result laravel-health stores, and in every notification. The decision stays visible instead of turning into silence. An acknowledgement also covers a check that could not look, such as the file checks on a platform that sets the environment without a .env.
Keys a server may leave out
env-example-keys fails for every key of .env.example that .env lacks, because env() reads null
for it. Where your code reads a default of its own for a key, name the key, or a prefix that ends in
*, and a server may leave it out:
'optional_env_keys' => ['MAIL_FROM_NAME', 'SENTRY_*'],
The check then passes and names the keys that were left out. Every other missing key still fails.
An endpoint a monitor pulls
health-notifications warns while mail is the only road an alert takes. An endpoint of your own that
a monitor pulls the results from counts as a second road, as the endpoint of Oh Dear does:
'health_endpoint' => '/health/state',
Commands
| Command | Runs | Exit codes |
|---|---|---|
php artisan preflight --deploy | the file and configuration checks, and records the deploy | 0 nothing failed, 1 a check failed, 2 a check could not look |
php artisan preflight | every check | the same |
php artisan env: | the file checks, against .env or the file named | 0 clean, 1 any finding, warnings included, 2 nothing could be checked |
env:lint is the strict one: two lines with equal values are harmless today and one edit away from a setting that does not apply. --quiet-when-clean prints nothing when nothing was found, for a schedule.
Both commands print values only with --show-values, which --deploy refuses: a deploy keeps its output. What reaches which channel explains why.