Environment variables are a crucial part of any Laravel application. They store sensitive data, API keys, database credentials, and other configuration values that your app relies on. But what happens if one of them is missing or misconfigured? Bugs, failed deployments, or — even worse — security issues.
This is where Laravel Health Env Vars comes in. This package helps you check the presence and validity of your environment variables as part of your application’s health checks.

Why it matters

If you’re a solo developer working on your laptop, it’s unlikely that you’ll forget to add a variable on the production server. But it could happen — and even worse, you might accidentally set the wrong value.
Things get more complicated in a development team: with multiple developers — or even the same developer on different machines — updating an environment variable means everyone needs to be notified (e-mail, Slack, Discord, Teams, Telegram, in person), and it’s easy to forget. Someone is bound to miss it.

Even experienced developers sometimes forget to set a required environment variable on a new server or in a CI/CD pipeline. Missing .env values can lead to:

• runtime errors
• broken features or integrations
• hard-to-debug issues in production

By proactively checking your environment variables, you catch potential problems before they affect users.

What the package does

At Encodia, we've been using Spatie’s excellent Laravel Health for a while, but it seemed there wasn’t a dedicated check for .env variables. That's why I built Laravel Health Env Vars, which integrates seamlessly with Spatie's package to provide a simple but powerful health check:

• ensure that required .env variables are present
• optionally validate their values
• run environment-specific checks
• fail your health check if something is missing or misconfigured

You can run the health checks in different situations:

• when setting up a project locally: for example, at Encodia we built an internal command-line tool called EDIT to help align a project — handling tasks like cloning/pulling from GIT, installing dependencies via Composer and NPM, running migrations and seeds, and more. One of EDIT’s key functions is to automatically run the health checks, ensuring everything is configured correctly from the start
• during deployment: whether in a CI/CD pipeline, a bash script, or other automated workflows, health checks can be executed to verify that all required environment variables are present and valid before going live.

What the package doesn't

Laravel Health Env Vars won’t check your .env variables once you’ve deployed — and let me explain why. In most deployments, it’s best practice to run php artisan config:cache. After that, every call to env('VARIABLE') will simply return null. See Caveats for more details.

Installation & Setup

Installing the package is straightforward:

composer require encodia/laravel-health-env-vars

Usage

Register a check just like any other Laravel Health check:

// typically, in a service provider

use Spatie\Health\Facades\Health;
use Spatie\Health\Checks\Checks\UsedDiskSpaceCheck;
use Encodia\Health\Checks\EnvVars;

Health::checks([
    // From Spatie's examples
    UsedDiskSpaceCheck::new()
        ->warnWhenUsedSpaceIsAbovePercentage(70)
        ->failWhenUsedSpaceIsAbovePercentage(90),

    // Many other checks...

    /*
     * Check that SOME_API_KEY and MAIL_FROM_ADDRESS variables are
     * set (no matter in which environment)
     */
    EnvVars::new()
        ->requireVars([
            'SOME_API_KEY',
            'MAIL_FROM_ADDRESS',
        ])
]);

When you run php artisan health:check --fail-command-on-failing-check, if SOME_API_KEY or MAIL_FROM_ADDRESS have not been set in .env, the command will show an error and return a non-zero exit code.

Sometimes you just want to make sure a variable is set in a particular environment (or in some environments).
Let's say you you want to check if EXTENDED_DEBUG_MODE has been set (only in local) and if BUGSNAG_API_KEY (only in production, because you don't want BugSnag to be enabled in testing/local/staging/UAT):

use Spatie\Health\Facades\Health;
use Encodia\Health\Checks\EnvVars;

Health::checks([
    // ...
    // (other checks)
    // ...

    /*
     * Check that SOME_API_KEY and MAIL_FROM_ADDRESS variables are
     * set (no matter in which environment).
     * 
     * Only in staging, ensure EXTENDED_DEBUG_MODE has been set.
     * 
     * Additionally, only in production,
     * ensure BUGSNAG_API_KEY has been set.
     */
    EnvVars::new()
        ->requireVars([
            'SOME_API_KEY',
            'MAIL_FROM_ADDRESS',
        ])
        ->requireVarsForEnvironment('local', [
            'EXTENDED_DEBUG_MODE'
        ])
        ->requireVarsForEnvironment('production', [
            'BUGSNAG_API_KEY'
        ]);
]);

Need to check if a variable has been set to a specific value? You can use requireVarsMatchValues() to perform this check, regardless of the current environment.
If you need to run this check only if the current environment matches the given one(s), you can use requireVarsForEnvironment() or requireVarsForEnvironments().
Let's see an example:

use Encodia\Health\Checks\EnvVars;
use Spatie\Health\Facades\Health;

Health::checks([
    EnvVars::new()
        // ... other methods ...
        ->requireVarsMatchValues([
            // Ensure that APP_LOCALE is set to 'en' (no matter which is the current environment)
            'APP_LOCALE' => 'en',
            // Ensure that APP_TIMEZONE is set to 'UTC' (no matter which is the current environment)
            'APP_TIMEZONE' => 'UTC',
        ])
        ->requireVarsMatchValuesForEnvironment('staging', [
            // Only if current environment is 'staging', we don't want to send e-mails to real customers
            'MAIL_MAILER' => 'log',        
        ])
        ->requireVarsMatchValuesForEnvironments(['qa', 'production'], [
            // Only if current environment is 'qa' or 'production, we want to log 'info' events or above
            'LOG_LEVEL' => 'info',
            // Only if current environment is 'qa' or 'production, we want to store assets to S3
            'FILESYSTEM_DISK' => 's3',        
        ]);
]);

Conclusion

Environment variables are small but critical. With Laravel Health Env Vars, you can make sure they are always present and valid, reducing errors and saving time in development and production.

Try it out and give feedback on GitHub — contributions are welcome!