Keeping your .env.example file updated

We've all been there. You're getting a new developer up and running with your Laravel project, and for some reason, it's nothing but 500 errors! It works on your machine... what on earth is going on? You've checked all of the usual suspects; the database exists and migrations have been run.

Hours pass. Confusion mounts. Muttering ensues.

Then suddenly, you facepalm. There's a missing entry in their .env file. See, more often than not, we forget to keep our .env.example file up to date because it no longer has any meaningful impact on our development cycle. It's only when this happens that you swear you're going to update it. Perhaps you do, perhaps you don't. But even if you do, likely it will get outdated again.

At Worksome, we got tired of this endless cycle of pain. So we decided to do something about it! Meet Envy, the Laravel package that will make sure you never miss an environment variable again.

How does it work?

Envy is not a sync-up between your .env and .env.example file. See, that has a lot of pitfalls. For starters, you almost never want to actually copy environment values from your .env, because they tend to contain sensitive information that shouldn't be in version control. Additionally, if you no longer need an environment variable in your project because you delete a config file or remove a package, a simple sync between these two files won't help remove those now outdated variables.

Envy is much smarter. It reads all of your project's config files (or any other files you've configured) and finds calls to the env function. Then, it compares those calls to what's contained inside your .env.example file. With that knowledge, it is able to suggest additions or removals for you, so that syncing your environment file with your project is only ever an Artisan command away.

Envy has two Artisan commands: php artisan envy:sync and php artisan envy:prune. Sync is designed to insert missing environment variables into your .env.example file. Prune is designed to remove environment variables that are no longer required.

Don't worry, neither of these commands will make changes without confirmation (unless you pass the --force option).

Running in CI

Of course, you'd still have to run these commands to sync everything up, which you may forget to do. To make sure you never miss this again, both Artisan commands provide a --dry option that will check for required additions or removals and return a failure code if any are found.

Let's take a look at a basic GitHub workflow that would perform this check for you.

name: Check Environment Variables
 
on: [pull_request]
 
jobs:
  envy:
    runs-on: ubuntu-latest
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
 
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1
 
      - name: Install Composer dependencies
        run: composer install --prefer-dist --no-interaction
 
      - name: Run Envy sync 
        run: php artisan envy:sync --dry
 
      - name: Run Envy prune
        run: php artisan envy:prune --dry 

Pretty straightforward stuff, hey? With this in place (obviously tweaked to your project's requirements), you'd know before any PR is merged if your .env.example file needs some TLC.

Configuration

Envy has tons of configuration options, all of which can be customised in config/envy.php. The Envy docs have extensive documentation on all of the options available to you. One thing I'd like to point out however, is the fact that you can add additional environment files to check. So, if you have a .env.testing or .env.dusk file, you could add those into the mix to ensure they remain up to date.

One thing to remember is that Envy will only search files in your config directory for env calls. This is because you should only use the env function in your config files, as using it elsewhere will prevent app config caching. However, if you need to add additional directories to search, you may add them here.

/**
 * Here you should list any config files/directories that you want to be
 * included when looking for calls to `env`. Directories are searched
 * recursively. Feel free to include unpublished vendor configs too.
 */
'config_files' => [
    config_path(),
    base_path('vendor/spatie/laravel-permission/config'), 
],

Side notes

I wanted to take a moment to say how much I enjoyed writing Envy. I built it using the action paradigm, which you can see my Laracon talk on here. It makes use of PHP AST for parsing and creating PHP files, which is always entertaining. It also marks my first time using the excellent Termwind package for styling console applications - you should definitely check it out. Writing HTML for the console is so much nicer and feels immediately familiar.

We put a lot of polish into this one, and we hope it comes through.

Conclusion

Envy is certainly going to help us keep things up to date, and we hope it can help you in your projects too! Go read the docs, check out the source code, and remember to like the project on GitHub if it helps you out!

Take care, Luke