README

更新于 2022

dotenvy

PHP 环境变量管理器，使用 .env 文件和示例进行验证

目标是提供一种简单的方式来处理环境变量

安装

composer require jpolvora/dotenvy

工作流程

创建一个名为 .env.example 的文件，该文件将通过您的开发团队共享。此文件必须提交到您的代码库中。放置您应用程序变量的键和值。格式为 KEY=__validation-string__

例如

#.env.example
API_KEY = trim|fallback(123)|number
CI_ENV = trim|required|enum(development,production)

库中内置了一些验证器

当前可用的验证器有

required：值不能为空，可以是任何字符串

# .env.example
API_KEY=required
# .env
API_KEY=sdkfjsdlk8349759843udj #pass
API_KEY= #fail

number：值不能为空，并且必须可以转换为整数（is_numeric）

# .env.example
PORT=number
# .env
PORT=8080 #pass
PORT=abc #fail

boolean：值不能为空，并且必须可以转换为布尔值（filter_var）

# .env.example
ENABLED=boolean
# .env
ENABLED=1 #pass
ENABLED=true #pass
ENABLED=0 #pass
ENABLED=FALSE #pass
ENABLED=foo #fail

enum：值不能为空，应该是

# .env.example
NODE_ENV=enum(development,production)
# .env
NODE_ENV=development #pass
NODE_ENV=production #pass
NODE_ENV= #FAIL
NODE_ENV=staging #fail

fallback：值可以为空，但将回退到所需的值

# .env.example
APP_LANG=fallback(en-us)
# .env
APP_LANG=pt-br # $_ENV['APP_LANG'] will be 'pt-br'
APP_LANG= # $_ENV['APP_LANG'] will fallback to 'en-us'

trim：仅在前设置环境变量之前修剪字符串

# .env.example
WHITE_SPACES=trim
# .env
WHITE_SPACES=   string_that_should_be_trimmed #will trim left and right trailling white spaces

重要

验证器的顺序是强制性的。它们将按顺序执行，将结果值传递给下一个验证器，以中间件模式运行。如果验证器评估为无效，则中断管道

自定义验证器

您可以创建自定义验证器，并以键：值函数名称和函数引用的形式将数组提供给 Dotenvy。规则

验证器必须是具有以下签名的函数

function (string $key, string $value, array $args)

您必须始终返回一个字符串，该字符串将被传递给验证器链/管道中的下一个验证器。如果您传递 null 或空字符串，则值将被忽略。
如果您想使值无效，则必须抛出异常并告诉用户发生了什么。

$options = [
  'custom_validators' => [
    'uppercase' => function (string $key, string $value, array $args) {
      return strtoupper($value);
    },
    'lowercase' => function (string $key, string $value, array $args) {
      return strtolower($value);
    },
    'throw_exception' => function (string $key, string $value, array $args) {
      throw new Exception(sprintf('%s=%s %s', $key, $value, implode(' - ', $args)));
    }
  ]
];

$dotenvy = new \Dotenvy\Dotenvy(__DIR__, $options);

在 .env.example 中引用您的验证器

#.env.example
MY_ENV_VAR=my_custom_validator_name(my_custom_parameter)
ANOTHER_ENV_VAR=uppercase

#.env
ANOTHER_ENV_VAR=this_value_will_be_uppercased #will evaluate to THIS_VALUE_WILL_BE_UPPERCASED

用法

$dotenvy = new \Dotenvy\Dotenvy(__DIR__); //directory of containing files (.env and .env.example)

$environment = $dotenvy->execute();
if (is_string($environment)) throw new Exception('Invalid env: ' . $environment);

var_dump($environment);

环境结果

运行 Dotenvy 后，环境变量将通过以下方式可用

$_SERVER
$_ENV
getenv()
apache_getenv()

重要

值的优先级顺序

$_SERVER
$_ENV
getenv()
apache_getenv()
.env 文件
回退验证器
抛出异常

性能优化

Dotenvy 可以使用编译后的缓存文件以实现最大性能。以下代码可以在生产模式下提高性能

$envoptions = array();
$dotenvy = new \Dotenvy\Dotenvy(__DIR__, $options);

$is_production = TRUE; //my custom logic to get info about production mode

if ($is_production) {
  if ($dotenvy->hasCacheFile()) {
    $dotenvy->executeFromCache();
  } else {
    $envresult = $dotenvy->execute();
    if (is_array($envresult)) {
      $dotenvy->writeCache($envresult);
    } else {
      throw new \Exception($envresult);
    }
  }
} else {
  //not in production mode
  //delete cache file if exist
  $dotenvy->clearCache();
  $dotenvy->execute();
}

选项使用

$envoptions = [
  'example' => '.env.example',
  'envfile' => '.env',
  'allow_ovewrite' => FALSE,
  'cachefile' => md5(date("Ymd")) . '.env',
  'custom_validators' => [
    'mycustomvalidator' => function (string $key, string $value, array $args) {
      return '(-' . $value . '-)';
    }
  ]
];

if ((array_key_exists('CI_ENV', $_SERVER) && $_SERVER['CI_ENV'] === 'production')) {
  Dotenvy\Dotenvy::exec_production(__DIR__, $envoptions);
} else {
  Dotenvy\Dotenvy::exec_development(__DIR__, $envoptions);
}

运行测试

cd tests && php index.php

贡献

// todo: 分支并提交 pull request。

jpolvora / dotenvy

维护者

详细信息