damejidlo/envy

This package is abandoned and no longer maintained. The author suggests using the nepada/envy package instead.

Helpers for extracting, validating and type-casting data from environment variables

v0.1.1 2019-10-30 02:27 UTC

Requires

• php: >=7.3
• nette/utils: ^2.5@dev || ^3.0@dev

Requires (Dev)

• damejidlo/coding-standard: ^1.1
• damejidlo/phpstan-nette-tester: ^0.1.0
• jakub-onderka/php-parallel-lint: ^1.0
• nette/bootstrap: ^2.4.6 || ^3.0
• nette/di: ^2.4.10@dev || ^3.0.1@dev
• nette/tester: ^2.3
• pepakriz/phpstan-exception-rules: ^0.8.1
• phpstan/phpstan-nette: ^0.11
• phpstan/phpstan-shim: ^0.11.19
• phpstan/phpstan-strict-rules: ^0.11.1

Suggests

• nette/di: for integration with Nette DI container

BSD-3-Clause

README

Installation

$ composer require damejidlo/envy

Basic usage

Create Envy instance:

use Damejidlo\Envy\Envy;
use Damejidlo\Envy\LoaderFactory;
use Damejidlo\Envy\ValueProviders\Reader;

$reader = new Reader();
$loaderFactory = new LoaderFactory($reader);
$envy = new Envy($reader, $loaderFactory);

Envy supports several methods for loading the most common data types from env variables. When loading the value, it is first validated (throws exception on invalid input), and then type-casted.

String values

// Get string from `FOO` env variable, or throw exception if not set
$envy->getString('FOO');
// Get string from `FOO` env variable, or return `'default'` if not set
$envy->getString('FOO', 'default');
// Get string from `FOO` env variable, or return `NULL` if not set
$envy->getStringOrNull('FOO');

Boolean values

There are multiple supported ways of expressing boolean values: true/false, yes/no, 1/0 (all case insensitive).

// Get boolean from `FOO` env variable, or throw exception if not set
$envy->getBool('FOO');
// Get boolean from `FOO` env variable, or return `FALSE` if not set
$envy->getBool('FOO', FALSE);
// Get boolean from `FOO` env variable, or return `NULL` if not set
$envy->getBoolOrNull('FOO');

Integer values

// Get integer from `FOO` env variable, or throw exception if not set
$envy->getInt('FOO');
// Get integer from `FOO` env variable, or return `42` if not set
$envy->getInt('FOO', 42);
// Get integer from `FOO` env variable, or return `NULL` if not set
$envy->getIntOrNull('FOO');

Float values

// Get float from `FOO` env variable, or throw exception if not set
$envy->getFloat('FOO');
// Get float from `FOO` env variable, or return `3.1415` if not set
 $envy->getFloat('FOO', 3.1415);
// Get float from `FOO` env variable, or return `NULL` if not set
$envy->getFloatOrNull('FOO');

Arrays

The default item delimiter ~\s*,\s*~ is used to split the items.

List of string values

// Get array of string from `FOO` env variable, or throw exception if not set
$envy->getStringArray('FOO');
// Get array of strings from `FOO` env variable, or return `['foo']` if not set
$envy->getStringArray('FOO', ['foo']);
// Get array of strings from `FOO` env variable, or return `NULL` if not set
$envy->getStringArrayOrNull('FOO');

List of integer values

// Get array of integer from `FOO` env variable, or throw exception if not set
$envy->getIntArray('FOO');
// Get array of integers from `FOO` env variable, or return `[42]` if not set
$envy->getIntArray('FOO', [42]);
// Get array of integers from `FOO` env variable, or return `NULL` if not set
$envy->getIntArrayOrNull('FOO');

List of float values

// Get array of float from `FOO` env variable, or throw exception if not set
$envy->getFloatArray('FOO');
// Get array of float from `FOO` env variable, or return `[3.1415]` if not set
$envy->getFloatArray('FOO', [3.1415]);
// Get array of float from `FOO` env variable, or return `NULL` if not set
$envy->getFloatArrayOrNull('FOO');

Nette DI integration

Register the extension in your configuration, this will register the necessary services in your DI container:

extensions:
    envy: Damejidlo\Envy\DI\EnvyExtension

You can now use a shorthand notation to access Envy methods:

parameters:
    loadedFromEnvVariables:
        foo: @envy::getString('FOO')
        bar: @envy::getIntArray('FOO', [1, 1, 2, 3, 5, 8, 13])

services:
    -
        type: MyService
        arguments:
            foo: %loadedFromEnvVariables.foo%
            bar: %loadedFromEnvVariables.bar%

Custom loaders

You can create your own loaders with completely customizable processing of loaded values, e.g.:

use Damejidlo\Envy\LoaderFactory;
use Damejidlo\Envy\ValueProviders\Reader;

$reader = new Reader();
$loaderFactory = new LoaderFactory($reader);

$defaultValue = ['https://example.com'];

// Processor that will split items on semicolon and validate every item contains valid URL
$arrayProcessor = (new ArrayProcessor())
	->withDelimiter('~;~')
	->withItemValidator('url');

$loader = $loaderFactory->createLoader()
	->withAddedProcessor($arrayProcessor)
	->withValidator('array:1..') // make sure we're loading non-empty array
	->withFallback($defaultValue);

// Get non-empty list of URLs from `FOO_URLS` env variable, or `$defaultValue` if not set
$urls = $loader->get('FOO_URLS');

If the default set of processors does not cover your use case, you can write your own by implementing ProcessorInterface.

Validation

The validation is build on top of Nette\Utils\Validators - you can validate against any type Nette supports.