README

Vars是一个简单易用、轻量级且易于扩展的配置加载器，内置了对ENV、INI、JSON、PHP、Toml、XML和YAML文件类型的加载器。它还内置了对Silex的支持，还有更多框架（如Symfony、Laravel等）即将推出。

为什么？
要求
安装
使用
- 基本
- 访问配置
- 导入
- 资源
- 选项
  - 路径
  - 变量
  - 缓存
  - 加载器
- 提供者
  - Silex
- 公共API
  - Vars
    - 构造函数
    - getContent
    - getResource
    - getResources
    - toEnv
    - toDots
    - set
    - get
  - FileResource
待办事项
变更日志
测试
贡献
安全
致谢
许可

为什么？

有时你不得不使用不同的格式来配置文件，Vars的目标之一就是通过支持最常用的配置格式来简化这一过程，这样你就无需切换库来处理不同的格式。

另一个目标是支持不同的框架，这样你就不必在处理不同框架时切换库。目前仅支持Silex使用服务提供者，Laravel和Symfony的支持即将推出。

通过简单的API和直观的加载选项，Vars试图使配置加载和提供尽可能简单。

要求

Vars需要PHP版本5.3+。

如果你想使用YAML，你需要symfony/yaml库，同样，你需要yosymfony/toml来使用Toml文件，以及m1/env来使用Env文件。

安装

通过Composer

$ composer require m1/vars

使用

基本

// load single file
$vars = new Vars(__DIR__.'/config/config.yml');

// load from dir
$vars = new Vars(__DIR__.'/config');

// load from array
$vars = new Vars(array(
    __DIR__.'/config/config.yml',
    __DIR__.'/config/sub',
));

访问配置

这可以通过多种方式完成，你可以将$vars变量视为一个普通数组，或者你可以以面向对象的方式使用它

// All return the same thing
$vars->get('db.password')
$vars['db.password'];
$vars['db']['password']

你也可以以相同的方式设置值

// All do the same thing
$vars->set('db.password', 'test')
$vars['db.password'] = 'test';
$vars['db']['password'] = 'test';

你也可以从getenv()中获取变量

// All do the same thing
$vars->toEnv();
getenv('db.password');

有关更多信息，请参阅环境变量部分

导入

导入文件

你可以轻松地将配置导入到其他配置中，这些导入取决于配置文件类型，因此请检查/tests/mocks/文件夹中的示例

# example_1.yml
test_key_1: test_value_1
imports: example_2.yml

# example_2.yml
test_key_2: test_value_2

会返回

[
    "test_key_1" => "test_value_1",
    "test_key_2" => "test_value_2"
]

导入默认情况下是相对于键的，例如

test_key_1:
    imports: example_2.yml

会返回

[
    "test_key_1" => [
        "test_key_2" => "test_value_2"
    ]
]

但是你可以以多种方式更改这一点

# example 1
test_key_1:
    imports: 
    - {resource: example.yml, relative: false}

# example 2
test_key_2:
    imports:
        resource: example.yml
        relative: false

如果你正在导入多个文件并且想要设置所有文件的相对性，你可以执行以下操作

test_key_1:
    imports: 
        relative: false
        resource:
            - example_2.yml
            - example_3.yml

以上所有操作都会使example_2.yml和example_3.yml变量相对于配置文件成为绝对路径

[
    "test_key_1" => []
    "test_key_2" => "test_value_2" // from example_2.yml
    "test_key_3" => "test_value_3" // from example_3.yml
]

导入目录

你还可以使用上述语法导入目录

test_key_1:
    imports: sub/

默认情况下，导入目录不是递归的，并且不会搜索文件夹内的文件夹，你可以通过添加递归切换来更改这一点

test_key_1:
    imports:
        resource: sub/
        recursive: true

或者通过添加递归标志

test_key_1:
    imports:
        resource: sub/*

与加载文件一样，你可以通过一个递归切换来批量导入目录

test_key_1:
    imports:
        recursive: false
        resource:
            - sub/
            - sub1/

目录导入依赖于加载器以及加载器支持的扩展。有关更多详细信息，请参阅加载器部分。

标志选项

导入时可以使用各种标志。

if else 标志 ?: 使得如果第一个文件存在，则使用该文件；否则使用其他定义的文件，例如

imports: "example_1.yml ?: example_2.yml"

注意：您需要将字符串用引号括起来，if else 标志才能正常工作

抑制异常标志 @ - 抑制文件未找到异常。例如

imports: @file_does_not_exist.yml

递归标志使得目录中的目录可以搜索文件。例如

imports:
    resource: sub/*

您还可以组合上述标志，如果 else 文件选项不存在，则不会抛出异常，例如

imports: "example_1.yml ?: @example_2.yml"

资源

您可以获取单个文件或资源

// All return the same thing
$vars->getResource('example_2.yml')->get('test_key_2');
$vars->getResource('example_2.yml')['test_key_2'];

选项

变量有多种选项

$vars = new Vars(__DIR__.'/config/config.yml', [
    // this will affect how you getResource() and will  default to the path
    // of the first resource you initiate
    'path' => __DIR__.'/config',

    // to cache or not -- defaults to true
    'cache' => true,

    // where the cache is stored -- If not set will default to the base path
    'cache_path' => __DIR__.'/config/',

    // How long the cache lasts for -- Defaults to 300 seconds (5 minutes)
    'cache_expire' => 300,

    // Replacement variables -- see variables section for more detail
    'replacements' => [
        'foo' => 'bar',
        'foobar' => 'barfoo'
    ],
    
    // Merge globals -- see globals section for more detail
    'merge_globals' => true,

    // The file loaders to load the configs -- see loader section for more detail
    'loaders' => [
        'default'
    ]
]);

基本路径

path 是 $vars->getResource($filename) 中的 $filename 的计算方式。例如

如果您将 path 设置为 __DIR__.'/config' 并且您导入 __DIR__.'/app/test_1.yml'

# example_1.yml
imports: example_2.yml

那么 example_1.yml 和 example_2.yml 的 $filename 分别为 ../app/test_1.yml 和 ../app/test_1.yml。

如果没有设置 path，则第一个文件资源路径将被用作 path，例如

// example 1
$vars = new Vars(__DIR__.'/config/config.yml');

// example 2
$vars = new Vars([
    __DIR__.'/config/config.yml',
    __DIR__.'/sub/config.yml',
    ]);

将都使用 __DIR__.'/config' 作为 path

变量

您可以在 Vars 中使用 3 种类型的变量：替换、文件内 和 环境，语法如下

为了提高可读性，您还可以在变量名和前缀/后缀之间放置空格，如下所示

replacement_variable: % VARIABLE %
infile_variable: %$ VARIABLE %
env_variable: %^ VARIABLE %

替换

替换变量从 Vars 外部加载，因此通常用于 PHP 函数/逻辑，例如 __dir__

test_key_1: %foo%
test_key_2: /bar/%foobar%/bar

$vars = new Vars(__DIR__.'/config/config.yml', [
    'replacements' => [
        'foo' => 'bar',
        'foobar' => 'barfoo'
    ],
]);

输出

[
    "test_key_1" => "bar",
    "test_key_2" => "/bar/barfoo/foobar/"
]

您的替换必须以前缀和后缀 % 包围

您还可以从文件中加载变量

$vars = new Vars(__DIR__.'/config/config.yml', [
    'replacements' => __DIR__.'/config/variables.yml'
]);

文件内变量

您还可以使用文件中已定义的键的变量，例如

test_key_1: hello
test_key_2: /bar/%$test_key_1%/bar

输出

[
    "test_key_1" => "bar",
    "test_key_2" => "/bar/hello/foobar/"
]

您的替换必须以前缀 %$ 和后缀 % 开始。

对于 in-file 和 replacements，您可以使用点表示法语法来获取数组中的值，例如

test_key_1: 
    test_key_2: hello
test_key_3: /bar/%$test_key_1.test_key_2%/bar

输出

[
    "test_key_1" => array(
        "test_key_2" => "hello"
    ),
    "test_key_2" => "/bar/hello/foobar/"
]

环境变量

您还可以使用环境变量进行替换

test_key_1: %^DATABASE_USERNAME%
test_key_2: %^DATABASE_PASSWORD%

# nginx config example
location @site {
    fastcgi_pass unix:/var/run/php5-fpm.sock;
    include fastcgi_params;
    fastcgi_param  SCRIPT_FILENAME $document_root/index.php;

    # env variables
    fastcgi_param DATABASE_USERNAME test_username;
    fastcgi_param DATABASE_PASSWORD test_password;
}

输出

[
    "test_key_1" => "test_username",
    "test_key_2" => "test_password"
]

您必须以前缀 %^ 和后缀 % 开始您的环境变量

您还可以使配置数组可用于 getenv()

$vars = new Vars(__DIR__.'/config/config.yml');
$vars->toEnv();

注意： 您的配置将展平为点表示法，例如

test_key_1:
    test_key_2: value

将被访问

getenv('test_key_1.test_key_2'); // value

全局变量

Vars 中的 Globals 指的是定义为这样的变量

_globals:
    test_key_1: test_value_1

基本上它们只是封装在 _globals 数组中 -- 使用这些变量的目的是可以从 Vars 中的 getGlobals() 访问它们

默认操作是将它们合并到其他文件内容中，因此

_globals:
    test_key_1: test_value_1
test_key_2: test_value_2

变为

[
    'test_key_1' => 'test_value_1',
    'test_key_2' => 'test_value_2',
]

但您可以通过将选项中的 merge_globals 更改为 false 来覆盖此操作。

如果您不理解这一点，那么您可能根本不需要使用全局变量，但它们对于与封装在例如 $app 下的所有内容的工作框架一起使用非常有用，并且您想能够像这样访问一些键 > 值：$app['test_key_1']。有关更多示例，请参阅 Silex 提供程序部分。

缓存

Vars 自动将资源缓存 5 分钟，您可以通过将 cache 选项设置为 false 来关闭此功能。

如果未设置 cache_path，则将其设置为 path 设置的值。必须可写 cache_path。

要使缓存失效，只需删除 cache_path 内部的名为 vars 的文件夹即可，例如：rm -rf /var/www/application/app/cache/vars

由于 opcache 的额外加速，缓存文件是 .php 文件。

如果你正在使用Silex提供程序，那么在调试模式下，缓存将不会被使用或设置。

加载器

加载器使得Vars能够读取不同的文件类型（默认为Ini、Json、Php、Toml、Xml和Yaml）。

您可以通过选项启用和禁用加载器。

默认加载所有默认加载器。

$vars = new Vars(__DIR__.'/config/config.yml', [
    'loaders' => 'default'
]);

// You can load individual loaders:
$vars = new Vars(__DIR__.'/config/config.yml', [
    'loaders' => [
        'ini',
        'json'
    [
]);

//You can also create and load custom loaders:
$vars = new Vars(__DIR__.'/config/config.yml', [
    'loaders' => [
        '\Foo\Bar\CustomFooBarLoader',
        'ini',
        'json'
    ]
]);

要创建自己的自定义加载器，你必须扩展M1\Vars\Loader\AbstractLoader，在public static $supported数组中有支持的扩展，并且有一个public function load()来加载文件内容。

以下是一个加载.txt文件的简单示例

namespace M1\Foo\Bar\Loader;

use M1\Vars\Loader\AbstractLoader;

class TextLoader extends AbstractLoader
{
    public static $supported = array('txt');

    public function load()
    {

        $content = [];

        foreach (file($this->entity) as $line) {
            list($key, $value) = explode(':', $line, 2);
            $content[trim($key)] = trim($value);
        }

        $this->content = $content;

        return $this;
    }
}

然后要使用此加载器，你只需这样做

$vars = new Vars(__DIR__.'/config/config.yml', [
    'loaders' => [
        '\M1\Foo\Bar\Loader\TextLoader',
    ]
]);

注意：不要在实际应用中使用此加载器，它纯粹是为了展示目的。

提供者

Silex

使用Silex库非常简单，只需在注册其他服务提供程序时注册它即可。

$app->register(new M1\Vars\Provider\Silex\VarsServiceProvider('example.yml'), [
    'vars.path' => __DIR__.'/../../app/config/test/',
    'vars.options' => [
        'cache' => true,
        'cache_path' => __DIR__.'/../../app/config/cache/',
        'cache_expire' => 500,
        'replacements' => [
            'test' => 'test_replacement'
        ],
        'loaders' => [
            'yml',
            'json'
        ],
        'merge_globals' => true,
        'replacements' => __DIR__.'/../../app/config/replacements.json',
    ]]);

然后你可以从$app['vars']访问你的配置。

注意：如果你设置了$app['debug'] = true，则不会使用缓存。

您还可以使用点符号从$app访问配置值，例如

test_key_1:
    test_key_2: value
test_key_3: value

你可以这样使用点符号来获取上面的内容

$app['vars']['test_key_1.test_key_2']; // value
$app['vars']['test_key_3']; // value

你还可以这样合并全局变量到$app

# example.yml
_globals:
    monolog.logfile: log.log
test_key_1: test_value_2

$app->register(new M1\Vars\Provider\Silex\VarsServiceProvider('example.yml'));

// register monolog here and other service providers

$app['vars.merge']();

注意$app['vars.merge']() -- 这会覆盖服务提供程序的默认值，所以在这个例子中monolog将使用vars配置中定义的日志文件。

你必须在你配置中为提供配置值的服务提供程序调用vars.merge之后调用。

你也可以通过$app['vars.test_key_1']访问test_key_1，如果你想，你可以这样访问全局变量$app['monolog.logfile']。

公共API

Vars

`Vars($resource, $options = array())`

创建新的Vars配置的构造函数。

$vars = new Vars(__DIR__.'/config/config.yml', [
    // this will affect how you getResource() and will  default to the path
    // of the first resource you initiate
    'path' => __DIR__.'/config',

    // to cache or not -- defaults to true
    'cache' => true,

    // where the cache is stored -- If not set will default to the base path
    'cache_path' => __DIR__.'/config/',

    // How long the cache lasts for -- Defaults to 300 seconds (5 minutes)
    'cache_expire' => 300,

    // Replacement variables -- see variables section for more detail
    'replacements' => [
        'foo' => 'bar',
        'foobar' => 'barfoo'
    ],

    // The file loaders to load the configs -- see loader section for more detail
    'loaders' => [
        'default'
    ]
]);

`getContent()`

返回所有配置的解析内容。

`getResource($resource)`

获取指定的资源，返回文件资源或如果资源不存在则返回false。

$resource的名称基于基础路径中定义的路径和文件名。

# example.yml
imports: example2.yml
test_1: value

# example2.yml
test_2: value

$vars = new Vars('example.yml');
$vars->getResource('example2.yml'); // FileResource

$vars->getResource('example2.yml')->getContent();
# output:
# [
#     "test_2" => "value"
# ]

`getResources()`

返回所有导入的资源，它们将是FileResource对象。

`toEnv()`

使得配置可以通过getenv()访问。

$vars = new Vars('example.yml');
$vars->toEnv();

getenv('test_1'); // value

`toDots()`

使得配置可以展开为点符号数组。

test_value_1:
    test_value_2: value
    test_value_3: value

$vars = new Vars('example.yml');
$vars->toDots();
# output:
# [
#     "test_value_1.test_value_2" => "value",
#     "test_value_1.test_value_3" => "value
# ]

`getGlobals()`

获取在_globals中定义的值。

`set($key, $value)`

设置配置键。

$vars = new Vars('example.yml');
$vars->set('test_key_1', 'value_2');

`get($key)`

获取配置键。

$vars = new Vars('example.yml');
$vars->get('test_key_1'); // value

FileResource

`getRawContent()`

获取来自文件的原始、未解析的内容。

# example.yml
test_value_1:
    imports: example2.yml
test_value_2: %root%/foo/%dir%

$vars = new Vars('example.yml');
$vars->getResource('example.yml')->getRawContent();
# output:
# [
#     test_value_1:
#          imports: example2.yml
#     test_value_2: %root%/foo/%dir%
# ]

`getContent()`

参见getContent()

`get($key)`

参见get()

待办事项

添加更多提供程序（Symfony、Laravel等）。

变更日志

请参阅CHANGELOG了解最近的变化。

测试

$ composer test

贡献

请参阅CONTRIBUTING获取详细信息。

安全

如果你发现任何安全相关的问题，请通过电子邮件[email protected]联系，而不是使用问题跟踪器。

致谢

许可

MIT许可证（MIT）。请参阅许可文件获取更多信息。

m1 / vars

维护者

详细信息

README

为什么？

要求

安装

使用

基本

访问配置

导入

导入文件

导入目录

标志选项

资源

选项

基本路径

变量

替换

文件内变量

环境变量

全局变量

缓存

加载器

提供者

Silex

公共API

Vars

Vars($resource, $options = array())

getContent()

getResource($resource)

getResources()

toEnv()

toDots()

getGlobals()

set($key, $value)

get($key)

FileResource

getRawContent()

getContent()

get($key)

待办事项

变更日志

测试

贡献

安全

致谢

许可

`Vars($resource, $options = array())`

`getContent()`

`getResource($resource)`

`getResources()`

`toEnv()`

`toDots()`

`getGlobals()`

`set($key, $value)`

`get($key)`

`getRawContent()`

`getContent()`

`get($key)`