README

这是一个用于组织配置数据和设计对象数据模型的Charcoal组件。

该组件是Charcoal框架中许多部分的粘合剂。

安装

首选（也是唯一支持）的方法是使用Composer

$ composer require locomotivemtl/charcoal-config

要求

PHP 5.6+: 推荐使用PHP 7。

PSR

PSR-11: 依赖注入容器的通用接口。用于可互操作的配置集。

实体 & 配置

Config组件简化了对对象数据的访问。它提供了一个基于属性的用户界面，用于在应用代码中检索和存储任意数据。数据组织为两种主要对象类型：实体（Entity）和配置（Config）。

实体

实体代表简单数据对象容器，旨在作为领域模型对象的灵活基础。
示例：存储库的单个结果或作为MVC系统每个组件的基础。

类: Charcoal\Config\AbstractEntity
方法: keys, data, setData, has, get, set
接口: Charcoal\Config\EntityInterface
- ArrayAccess
- JsonSerializable
- Serializable

配置

配置是高级实体（Entities），设计用于运行时配置值，支持加载文件和存储分层数据。
示例：应用程序首选项、服务选项和工厂设置。

类: Charcoal\Config\AbstractConfig
- IteratorAggregate
- Psr\Container\ContainerInterface
方法: defaults, merge, addFile
接口: Charcoal\Config\ConfigInterface
- Charcoal\Config\EntityInterface
- Charcoal\Config\FileAwareInterface
- Charcoal\Config\SeparatorAwareInterface
- Charcoal\Config\DelegatesAwareInterface

文件加载器

Config容器当前支持四种文件格式：INI、JSON、PHP和YAML。

可以通过addFile($path)方法或直接实例化将配置文件导入Config对象。

use Charcoal\Config\GenericConfig as Config;

$cfg = new Config('config.json');
$cfg->addFile('config.yml');

文件的扩展名将用于确定如何导入文件。文件将被解析，如果它是一个数组，则将其合并到容器中。

如果您想加载配置文件而不将其内容添加到Config中，请使用loadFile($path)。无论其内容是数组与否，文件都会被解析并返回。

$data = $cfg->loadFile('config.php');

有关更多信息，请参阅文档和示例。

键分隔符查找

可以使用键分隔符在多维数组中查找、检索、分配或合并值。

在Config对象中，默认分隔符是点字符（.）。可以通过separator()方法检索令牌，并通过setSeparator()方法进行自定义。

use Charcoal\Config\GenericConfig as Config;

$cfg = new Config();
$cfg->setSeparator('/');
$cfg->setData([
    'database' => [
        'params' => [
            'name' => 'mydb',
            'user' => 'myname',
            'pass' => 'secret',
        ]
    ]
]);

echo $cfg['database/params/name']; // "mydb"

有关更多信息，请参阅文档。

代理查找

代理允许多个对象共享值，并在当前对象无法解析给定数据键时充当后备。

在Config对象中，代理对象被注册到内部堆栈。如果无法解析数据键，Config将遍历堆栈中的每个代理，并在找到第一个包含非NULL值的匹配项时停止。

use Charcoal\Config\GenericConfig as Config;

$cfg = new Config([
    'driver' => null,
    'host'   => 'localhost',
]);
$delegate = new Config([
    'driver' => 'pdo_mysql',
    'host'   => 'example.com',
    'port'   => 11211,
]);

$cfg->addDelegate($delegate);

echo $cfg['driver']; // "pdo_mysql"
echo $cfg['host']; // "localhost"
echo $cfg['port']; // 11211

有关更多信息，请参阅文档。

数组访问

实体对象实现了ArrayAccess接口，因此可以使用数组样式。

$cfg = new \Charcoal\Config\GenericConfig();

// Assigns a value to "foobar"
$cfg['foobar'] = 42;

// Returns 42
echo $cfg['foobar'];

// Returns TRUE
isset($cfg['foobar']);

// Returns FALSE
isset($cfg['xyzzy']);

// Invalidates the "foobar" key
unset($cfg['foobar']);

👉 数据键必须是字符串，否则会抛出InvalidArgumentException。

互操作性

Config对象实现了PSR-11: Psr\Container\ContainerInterface。

此接口公开了两个方法：get()和has()。这些方法由实体对象作为ArrayAccess::offsetGet()和ArrayAccess::offsetExists()的别名实现。

$config = new \Charcoal\Config\GenericConfig([
    'foobar' => 42
]);

// Returns 42
$config->get('foobar');

// Returns TRUE
$config->has('foobar');

// Returns FALSE
$config->has('xyzzy');

👉 使用不存在键调用get()方法不会抛出异常。

可配置对象

此外，此包还提供了一种Configurable混合。

Charcoal\Config\ConfigrableInterface
Charcoal\Config\ConfigurableTrait

可配置对象（可以称为“配置感知”）可以关联一个Config对象，该对象可以帮助定义各种属性、状态或其他内容。

可以使用setConfig()分配Config对象，并使用config()检索。

ConfigurableTrait的一个附加好处是createConfig($data)方法，用于在未分配Config对象时创建一个Config对象。此方法可以在子类中重写，以自定义返回的实例和可能需要的初始状态。

有关示例和更多信息，请参阅文档。

开发

安装开发环境

$ composer install

运行脚本（phplint、phpcs和phpunit）

$ composer test

API 文档

自动生成的phpDocumentor API文档可在以下位置获取：
https://locomotivemtl.github.io/charcoal-config/docs/master/
自动生成的apigen API文档可在以下位置获取：
https://codedoc.pub/locomotivemtl/charcoal-config/master/

开发依赖项

编码风格

charcoal-config模块遵循Charcoal编码风格

PSR-1
PSR-2
PSR-4，因此自动加载由Composer提供。
phpDocumentor注释。
phpcs.xml.dist和.editorconfig用于编码标准。

编码风格验证/执行可以通过composer phpcs进行。还有一个自动修复工具，使用composer phpcbf。

此模块在运行phpstan analyse -l7 src/时也应不会产生错误 👍。

致谢

许可证

Charcoal遵循MIT许可证。详细信息请参阅LICENSE。

locomotivemtl / charcoal-config

维护者

详细信息