sil-org/php-env

Simple PHP library for getting (or requiring) environment variables, designed to handle true, false, and null more intelligently. If desired, an environment variable's value can be split into an array automatically.

4.0.1 2025-09-16 13:56 UTC

Requires

• php: ^8.0

Requires (Dev)

• phpunit/phpunit: ^12.0

MIT

README

Simple PHP library for getting (or requiring) environment variables, designed to handle true, false, and null more intelligently. If desired, an environment variable's value can be split into an array automatically.

Build Status

Setup

1. Clone this repo.
2. Copy local.env.dist to local.env and update GitHub.com token as appropriate.
3. Run make test to install dependencies and run PHPUnit tests.

Makefile script

There is a Makefile in place to simplify common tasks.

• make test - does composer install and runs phpunit tests

Classes in Sil/PhpEnv namespace

1. Env: use Sil\PhpEnv\Env;
2. EnvVarNotFoundException: use Sil\PhpEnv\EnvVarNotFoundException;

Class Env summary of functions

1. get - public static function get($varname, $default = null)

   • searches the local environment for $varname and returns the corresponding value string
   • if $varname is not set or the value is empty (only whitespace), get returns $default parameter
   • if the value string corresponding to $varname is 'true', 'false' or 'null', get returns php values of true, false, or null respectively
   • NOTE: Any value string containing 'true' with any combination of case and/or leading/trailing whitespace still returns php true.
     false and null are handled similarly. Other value strings will have leading/trailing whitespace trimmed.

2. getString - public static function getString($varname, $default = null): ?string

   • searches the local environment for $varname and returns the corresponding trimmed value string
   • if $varname is not set or the value is empty (only whitespace), getString returns $default parameter

3. getBoolean - public static function getBoolean($varname, $default = null): ?bool

   • searches the local environment for $varname and returns the corresponding boolean value string
   • if $varname is not set or the value is empty (only whitespace), getBoolean returns $default parameter
   • if the value string corresponding to $varname is 'true', 'false' or 'null', getBoolean returns php values of true, false, or null respectively
   • if the value is not boolean, getBoolean returns $default parameter
   • NOTE: Any value string containing 'true' with any combination of case and/or leading/trailing whitespace still returns php true. false and null are handled similarly.

4. getArray - public static function getArray($varname, array $default = [])

   • searches the local environment for $varname and returns the corresponding value string with comma separated elements as a php array
   • if $varname is not set or the value is empty (only whitespace), getArray returns $default parameter which must be an array
   • if $default is not an array, it throws a TypeError exception

5. requireEnv - public static function requireEnv($varname)

   • searches the local environment for $varname and returns the corresponding value string
   • if $varname is not set or the value is empty (only whitespace), it throws EnvVarNotFoundException
   • 'true', 'false', and 'null' are handled the same as get()

6. requireArray - public static function requireArray($varname)

   • searches the local environment for $varname and returns the corresponding value string with comma separated elements as a php array
   • if $varname is not set or the value is empty (only whitespace), it throws EnvVarNotFoundException

Class EnvVarNotFoundException

class EnvVarNotFoundException extends \Exception

EnvVarNotFoundException is thrown by requireEnv() and requireArray() when $varname is not found in the local environment or the corresponding value string is empty (only whitespace)

Env example function calls

Assume this local.env file

EMPTY=
SPACES=      
WHITESPACE= Some whitespace    
FALSE=False
TRUE=TRUE
NULL=null
LOWERCASE=abc123
UPPERCASE=ABC123
ARRAY0=
ARRAY1=one
ARRAY=one,two,,three

Example function calls and results

• get - public static function get($varname, $default = null)

  1. Env::get('NOTFOUND') - returns null
  2. Env::get('NOTFOUND', 'bad data') - returns 'bad data'
  3. Env::get('EMPTY') - returns ''
  4. Env::get('SPACES') - returns ''
  5. Env::get('WHITESPACE') - returns 'Some whitespace'
  6. Env::get('FALSE') - returns false
  7. Env::get('TRUE') - returns true
  8. Env::get('NULL') - returns null
  9. Env::get('LOWERCASE') - returns 'abc123'
  10. Env::get('UPPERCASE') - returns 'ABC123'

• requireEnv - public static function requireEnv($varname)

  1. Env::requireEnv('NOTFOUND') - throws EnvVarNotFoundException
  2. Env::requireEnv('EMPTY') - throws EnvVarNotFoundException
  3. Env::requireEnv('WHITESPACE') - returns 'Some whitespace'
  4. Env::requireEnv('FALSE') - returns false
  5. Env::requireEnv('LOWERCASE') - returns 'abc123'

• getArray - public static function getArray($varname, array $default = [])

  1. Env::getArray('NOTFOUND') - returns []
  2. Env::getArray('NOTFOUND', ['one', 'two']) - returns ['one', 'two']
  3. Env::getArray('NOTFOUND', 'one,two,three') - throws TypeError exception
  4. Env::getArray('ARRAY0') - returns ['']
  5. Env::getArray('ARRAY1') - returns ['one']
  6. Env::getArray('ARRAY') - returns ['one', 'two', '', 'three']

• requireArray - public static function requireArray($varname)

  1. Env::requireArray('NOTFOUND') - throws EnvVarNotFoundException
  2. Env::requireArray('EMPTY') - throws EnvVarNotFoundException
  3. Env::requireArray('ARRAY1') - returns ['one']
  4. Env::requireArray('ARRAY') - returns ['one', 'two', '', 'three']