README

Track Your Environment Variable Changes Using Specification

Table Of Contents

• About
• Installation
• Initialization
• Validation
• Filling
• Adding
• Dumping
• Syntax
• Tips
• Contributing

About

KeepEnv is a CLI tool for checking and managing environment variables based on a specification file.

Motivations:

• I want to have a way to describe all environment variables in one specification file.
• I want to make sure that all required variables are filled in correctly before deploying the application.
• I don't want to check variables in runtime.
• I want to keep track of new environment variables when they are added by one of my colleagues.
• I want to have a convenient and safe way to fill in new variables.
• I want to check variables from different state providers (system $_ENV, from .env file + system or only from .env file).
• I don't want to manually describe all 100+ existing environment variables.
• I want to use a tool that will not be tied to a specific framework, because I work with several frameworks.

Features:

• Environment specification generation based on current .env files.
• Environment variables validation.
• Split variable definition between environments.
• Extend variables from particular environment e.g. local from common.
• Split system ($_ENV) and regular variables from .env files.
• Ability to fill missing variables through console command.

Supported dotenv file state loaders:

• vlucas/phpdotenv
• symfony/dotenv
• josegonzalez/dotenv

Installation

Install composer package:

composer require andriichuk/keepenv

Initialization

This command allows you to generate a new environment specification file based on your current .env structure.

Basic usage:

./vendor/bin/keepenv init

This will create a specification file (keepenv.yaml) in your root directory with common environment.

Using preset (available presets: laravel, symfony):

./vendor/bin/keepenv init --preset=laravel

For Laravel Sail:

./vendor/bin/sail php ./vendor/bin/keepenv init --preset=laravel

Using custom .env files for vlucas/dotenv (paths to the folders with .env file):

./vendor/bin/keepenv init --env-file=./ --env-file=./config/

Using custom .env files for symfony/dotenv (direct file paths):

./vendor/bin/keepenv init --env-file=./.env --env-file=./.env.local

Environment file reader will be detected automatically, but you can customize it:

./vendor/bin/keepenv init --env-reader=symfony/dotenv --env-file=./.env

Validation

Using this command you can check your environment variables according to the specification file keepenv.yaml.

Basic usage:

./vendor/bin/keepenv validate common

Check only system variables ($_ENV) without looking at the .env file:

./vendor/bin/keepenv validate common --env-provider=system

Use --help option to check other parameters.

Filling

This command allows you to fill in and validate missing variable values from your .env file (use --help for list of all options).

Command:

./vendor/bin/keepenv fill

For specific environment:

./vendor/bin/keepenv fill --env=common

Adding

The following command can help you to add a new variable definition to specification and dotenv files:

./vendor/bin/keepenv add

Dumping

Using this command you can export all your variables defined in keepenv.yaml file into the custom .env file.

Create a new .env file according to variables defined in the keepenv.yaml (same as cp .env.example .env). Variables will be filled in only with default values. Perhaps now you can delete the .env.example file:

./vendor/bin/keepenv dump

Dump system variables into the file:

./vendor/bin/keepenv dump --target-env-file=./.env.system --env-provider=system --with-values=true

Create a new .env.stage file based on production environment specification and current .env file:

./vendor/bin/keepenv dump --env=production --target-env-file=./.env.stage --env-file=./ --with-values=true

Syntax

Currently, only the YAML syntax format is supported.

Environments definition:

version: '1.0'
environments:
    common:
        variables:
        # ...
    local:
        extends: common
        variables:
        # ...
    testing:
        variables:
        # ...

Variables definition:

• Describe the purpose of variables:

SESSION_LIFETIME:
    description: 'Session lifetime in minutes.'

• Mark that variable should be followed by export keyword in .env file (export APP_LOCALE=en):

APP_LOCALE:
    export: true

• Mark that variable should be set on the server-side ($_ENV or $_SERVER) not from .env file:

APP_TIMEZONE:
    system: true

• Specify default value (please use this only for non-sensitive data):

REDIS_PORT:
    default: 6379

• Describe validation rules:
  • Mark variable as required:

  APP_ENV:
      rules:
          required: true

  • Check that variable value is a string (can usually be omitted because all values in the .env file are read as strings by default):

  APP_ENV:
      rules:
          string: true

  • String with length range

  APP_KEY:
      rules:
          string:
              min: 32
              max: 60

  • Numeric

  REDIS_PORT:
      rules:
          numeric: true

  • Boolean (true/false, on/off, yes/no, 1/0)

  APP_DEBUG:
      rules:
          boolean: true

  • Boolean with custom options

  PAYMENT_FEATURE:
      rules:
          boolean:
              'true': Y
              'false': N

  • Email address

  MAIL_FROM_ADDRESS:
      rules:
          email: true

  • Enumeration:

  APP_ENV:
      rules:
          enum:
              - local
              - production

  • Means that the value of the variable must be equal (==) to a specific value.

  APP_ENV:
      rules:
          equals: local

  • IP address

  DB_HOST:
      rules:
          ip: true

Full example:

version: '1.0'
environments:
    common:
        variables:
            APP_NAME:
                description: 'Application name.'
            APP_ENV:
                description: 'Application environment name.'
                default: local
                rules:
                    required: true
                    enum:
                        - local
                        - production
            APP_DEBUG:
                rules:
                    boolean: true
            DB_HOST:
                description: 'Database host.'
                default: 127.0.0.1
                rules:
                    required: true
                    ip: true
            DB_PORT:
                description: 'Database port.'
                default: 3306
                rules:
                    required: true
                    numeric: true

    local:
        extends: common
        variables:
            APP_ENV:
                rules:
                    equals: local

    testing:
        variables:
            DB_DATABASE:
                description: 'Database name.'
                default: testing
                rules:
                    required: true
            DB_USERNAME:
                description: 'Database username.'
                rules:
                    required: true
            DB_PASSWORD:
                description: 'Database password.'
                rules:
                    required: true

Tips

Use equals rule to check for a specific value for the environment, e.g., a useful example for APP_ENV:

version: '1.0'
environments:
    common:
        variables:
            APP_ENV:
                rules:
                    required: true
                    enum:
                        - local
                        - production
            # ...
    production:
        extends: common
        variables:
            APP_ENV:
                rules:
                    equals: production

You can add a composer script for the new environment variables filling and validation:

"scripts": {
    "keepenv": "./vendor/bin/keepenv fill && ./vendor/bin/keepenv validate",
},

Then use:

composer keepenv common

You can also define keepenv common on post-update-cmd composer event, so environment filling and validation will be running after each composer update:

"scripts": {
    "post-update-cmd": [
        "@keepenv common"
    ]
},

Contributing

Contributions, issues and feature requests are welcome.
Feel free to check issues page if you want to contribute. Check the contributing guide.

Credits

• Serhii Andriichuk
• All Contributors

License

Copyright © 2022 Serhii Andriichuk.
This project is MIT licensed.