README

Envator 是一个支持加载多个文件、缓存（使用 psr-16 简单缓存接口）和启用布尔值、数字和值内部变量的类型转换等功能的 .env 文件加载器。

需求

PHP 8.0以上版本。

安装

1. 使用Composer

您可以通过Composer 安装此库。

php composer.phar require abdeslam/envator

或者

composer require abdeslam/envator

2. 手动安装

如果您不使用Composer，您也可以将 Abdeslam/Envator 仓库克隆到您的目录中

git clone https://github.com/Abdeslam-Gacemi/Envator.git

然而，推荐使用Composer，因为您可以轻松地保持库的更新。

使用

1. 直接使用Envator类

假设这是您的 .env 文件

APP_NAME=my_awesome_application

在您的 php 代码中

<?php

use Abdeslam\Envator\Envator;

require '/path/to/autoload.php';

$envator = new Envator();
$envator->load('/path/to/.env');
$envator->populate();

echo getenv('APP_NAME'); // output: 'my_awesome_application'
echo $_ENV['APP_NAME']; // output: 'my_awesome_application'
echo $_SERVER['APP_NAME']; // output: 'my_awesome_application'

加载多个 .env 文件

<?php

use Abdeslam\Envator\Envator;

require '/path/to/autoload.php';

$envator = new Envator();
// loading multiple .env files
$envator->load('/path/to/.env', '/path/to/another/.env');
$envator->populate();

2. 使用工厂

<?php

use Abdeslam\Envator\EnvatorFactory;

require '/path/to/autoload.php';

$envator = new EnvatorFactory::create([
    '/path/to/.env'
]);
$envator->populate();

echo getenv('APP_NAME'); // output: 'my_awesome_application'
echo $_ENV['APP_NAME']; // output: 'my_awesome_application'
echo $_SERVER['APP_NAME']; // output: 'my_awesome_application'

3. 添加过滤器

过滤器允许在解析 .env 文件后的键和值上操作。Envator 包提供 5 个过滤器，您也可以添加自定义过滤器。

TrimQuotesFilter::class：移除字符串键和值的引号。
BooleanValuesFilter::class：将 'true' 和 'false' 字符串转换为布尔值（不区分大小写）。
NumericValueFilter::class：将数字字符串转换为整数和浮点数。
EmptyStringToNullFilter::class：将空字符串 '' 转换为 NULL。
VariableFilter::class：在值内部替换变量（变量必须在值内部使用之前定义）。 请见以下示例

假设这是您的 .env 文件

APP_NAME=my_awesome_application
ENVIRONMENT="development"
DEBUG=true
VERBOSITY_LEVEL=2

DATABASE_USER=user
DATABASE_PASSWORD=${DATABASE_USER}1234

EMPTY=
EMPTY2

在您的 php 代码中

<?php

use Abdeslam\Envator\Envator;
use Abdeslam\Envator\Filters\TrimQuotesFilter;
use Abdeslam\Envator\Filters\BooleanValueFilter;
use Abdeslam\Envator\Filters\NumericValueFilter;
use Abdeslam\Envator\Filters\VariableFilter;
use Abdeslam\Envator\Filters\EmptyStringToNullFilter;

require '/path/to/autoload.php';

$envator = new Envator();
$envator->addFilters([
    TrimQuotesFilter::class,
    BooleanValueFilter::class,
    NumericValueFilter::class,
    VariableFilter::class,
    EmptyStringToNullFilter::class
]);
$envator->load('/path/to/.env');
$envator->populate();

echo getenv('ENVIRONMENT'); // output: 'development' instead of '"development"'

echo $_ENV['DEBUG']; // output: true (boolean) instead of 'true' (string)

echo $_ENV['VERBOSITY_LEVEL']; // output: 2 (integer) instead of '2' (string)

echo $_SERVER['DATABASE_PASSWORD']; // output: 'user1234'

echo getenv('DEBUG'); // output: '1' 
// getenv() does not support booleans and NULL
echo getenv('EMPTY'); // output: '' 
// getenv() does not support booleans and NULL

echo $_ENV['EMPTY']; // output: NULL

echo $_SERVER['EMPTY2']; // output: NULL

注意事项

使用 getenv() 函数：它不支持布尔值（TRUE 和 FALSE）和 NULL，它们会被转换为字符串：TRUE => '1'，FALSE => ''，NULL => ''。

4. 使用工厂的过滤器

工厂会自动加载 5 个默认过滤器，要更改此行为

<?php

use Abdeslam\Envator\EnvatorFactory;

require '/path/to/autoload.php';

$envator = EnvatorFactory::create(
    ['/path/to/.env'],
    [] // no filter will be loaded
);

或者

<?php

use Abdeslam\Envator\EnvatorFactory;

require '/path/to/autoload.php';

$envator = EnvatorFactory::create(
    ['/path/to/.env'],
    null // (default value) the default 5 filters will be loaded
);

或者

<?php

use Abdeslam\Envator\EnvatorFactory;
use Abdeslam\Envator\Filters\BooleanValueFilter;

require '/path/to/autoload.php';

$envator = EnvatorFactory::create(
    ['/path/to/.env'],
    // loading needed filters only
    [BooleanValueFilter::class]
);

5. 自定义过滤器

过滤器必须是一个实现了 Abdeslam\Envator\Contracts\FilterInterface 的类

<?php

use Abdeslam\Envator\Contracts\FilterInterface;

class MyCustomFilter implements FilterInterface
{
   /**
    * @inheritDoc
    */
   public static function filter(array $oldItems, string $key, $value): array
   {
       $prefix = 'MY_PREFIX_';
       // the key exists in the items parsed previously
       // so it will be overwritten
       // we add a prefix to the key
       if (array_key_exists($key, $oldItems)) {
           $key = $prefix . $key;
       }
       return ['key' => $key, 'value' => $value];
   }
}

如果我们以这个 .env 变量为例

USERNAME=user
USERNAME=admin

<?php

use Abdeslam\Envator\EnvatorFactory;
use MyCustomFilter;

require '/path/to/autoload.php';

$envator = EnvatorFactory::create(
    ['/path/to/.env'],
    // loading needed filters
    [MyCustomFilter::class]
);
$envator->populate();

echo getenv('USERNAME'); // output : 'user'
echo getenv('MY_PREFIX_USERNAME'); // output : 'admin'

6. 选项

在将变量填充到环境变量时，您可以通过将数组作为参数传递给 Envator::populate() 方法来指定变量填充的方式

<?php

use Abdeslam\Envator\EnvatorFactory;

require '/path/to/autoload.php';

$envator = EnvatorFactory::create(['/path/to/.env']);
// populate the variables to the super global $_ENV only
$envator->populate([
    Envator::GLOBAL_ENV => true,
    Envator::PUT_ENV => false, // populate using putenv() function (risky)
    Envator::APACHE => false, // populates using apache_setenv() (for apache environment)
    Envator::SERVER => false // populates to the super global $_SERVER
]);

/**
 * the default configuration :
 * [
 *  Envator::GLOBAL_ENV => true,
 *  Envator::PUT_ENV => true,
 *  Envator::APACHE => false,
 *  Envator::SERVER => true,
 * ]
*/

7. 缓存

Envator 支持任何实现 psr-16（简单缓存）的版本，并提供了一个默认版本

<?php

use Abdeslam\Envator\Envator;

require '/path/to/autoload.php';
// instantiating the cache manager providing the directory to use for caching
$cacheManager = new CacheManager(__DIR__);
$envator = new Envator();
// setting a cache manager enables the cache automatically
$envator->setCacheManager($cacheManager);
$envator->load('/path/to/.env')->populate();

或者

<?php

use Abdeslam\Envator\EnvatorFactory;

require '/path/to/autoload.php';

$envator = EnvatorFactory::create(
    ['/path/to/.env'],
    null,
    __DIR__ // cache directory
);
$envator->populate();

自定义

创建自定义的 .env 文件解析器和解析器类，它们必须实现 Abdeslam\Envator\ResolverInterface 和 Abdeslam\Envator\ParserInterface。

<?php

use Abdeslam\Envator\Envator;

require '/path/to/autoload.php';

$resolver = new MyCustomResolver();
$parser = new MyCustomParser();
$envator = new Envator($resolver, $parser);

用爱制作 ❤️

abdeslam / envator

维护者

详情