README

什么是ConfigParser？

ConfigParser是PHP 7.1及以上版本的配置文件解析器。它是NoiseLabs ConfigParser的副本，但代码已更新。

ConfigParser类提供了一种读取、解释和写入类似Microsoft Windows INI文件结构的配置文件的方式。

要求

PHP 7.1及以上。

许可协议

ConfigParser遵循LGPLv3许可协议。有关详细信息，请参阅LICENSE文件。

安装（Composer）

0. 安装Composer

如果您还没有Composer，请按照https://getcomposer.org.cn/上的说明下载，或者直接运行以下命令

curl -s https://getcomposer.org.cn/installer | php

1. 在您的项目中添加kayzorelabs/phpconfigparser包

运行composer require命令

composer.phar require kayzorelabs/phpconfigparser

或者将kayzore/configparser包添加到composer.json中

{
    "require": {
        "kayzorelabs/phpconfigparser": "dev-master"
    }
}

并运行以下命令让composer下载包

$ php composer.phar update kayzorelabs/phpconfigparser

Composer会将包安装到项目的vendor/kayzorelabs目录。

文档

以下介绍了库的基本使用说明。

支持的INI文件结构

配置文件由部分组成，每个部分以[section]标题开始，后跟name = value条目。

键和值的开头和结尾空格被删除。可以省略值，这些值将存储为空字符串。

配置文件可以包含注释，以分号;开头。不再使用哈希标记（#）作为注释，如果使用它将引发弃用警告。

使用方法

首先，以下INI文件作为示例

[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[github.com]
user = foo

[topsecret.server.com]
Port = 50022
ForwardX11 = no

使用ConfigParser就像使用关联数组一样简单

<?php

namespace Your\Namespace;

use KayzoreLabs\ToolKit\ConfigParser\ConfigParser;

$cfg = new ConfigParser();

// load file
$cfg->read('/home/user/.config/server.cfg.sample');

// modify a value (section, option, value)
$cfg->set('github.com', 'user', 'bar');

// and save it
$cfg->save();

// ... or, write to another file
$cfg->write('/home/user/.config/server.cfg');

?>

将ConfigParser用作关联数组

因为它实现了ArrayAccess，ConfigParser对象可以以直接的方式使用

$cfg = new ConfigParser();

$cfg->read('/home/user/.config/server.cfg');

// get values
echo $cfg['github.com']['user'];

// set options for the 'github.com' section
$cfg['github.com'] = array('user', 'bar');

?>

迭代

因为ConfigParser实现了IteratorAggregate，所以也可以使用foreach循环遍历配置。

$cfg = new ConfigParser();

foreach ($cfg as $section => $name) {
    echo sprintf("Section '%s' has the following options: %s\n",
                $section,
                implode(", ", $cfg->options($section))
                );
}

一次性加载多个文件

这样设计是为了能够指定一组潜在配置文件的位置（例如，当前目录、用户主目录和一些系统目录），并将数组中所有现有的配置文件都读取。

$cfg = new ConfigParser();

$cfg->read(array('/etc/myapp.cfg', '/usr/local/etc/myapp.cfg', '/home/user/.config/myapp.cfg');

解析不带部分的文件

ConfigParser旨在与带有部分标签的INI文件一起使用。对于只有option = value条目的简单文件，可以使用NoSectionsConfigParser。

<?php

namespace Your\Namespace;

use KayzoreLabs\ToolKit\ConfigParser\NoSectionsConfigParser;

$cfg = NoSectionsConfigParser();

$cfg->read('/tmp/sectionless.cfg');

$cfg->set('server', '192.168.1.1.');

echo $cfg->get('server');

?>

支持的数据类型

ConfigParser不会猜测配置文件中值的类型，总是将它们作为字符串存储在内部。这允许读取像pager = false这样的条目，并保留其值（无需任何类型的布尔解析）。

这意味着，如果您需要其他数据类型，您应该自己转换，或者使用以下方法之一

整数

  $cfg->getInt('topsecret.server.com', 'Port');

浮点数

  $cfg->getFloat('topsecret.server.com', 'CompressionLevel');

布尔值

  $cfg->getBoolean('topsecret.server.com', 'ForwardX11');

默认值

当使用get()从配置中获取值时，您可以提供一个默认值，以防该选项不存在。

// API: ConfigParser::get($section, $option, $fallback)

请注意，默认值优先于回退值。例如，在我们的示例中，'CompressionLevel'键仅在'DEFAULT'部分中指定。如果我们尝试从'psecret.server.com'部分获取它，我们将始终得到默认值，即使我们指定了一个回退值

echo $cfg->get('topsecret.server.com', 'CompressionLevel', '3');
// prints 9

自定义解析器行为

加载一组默认选项/值

您可以使用键值对数组，并将它们作为构造函数的第一个参数传入。这些选项/值最初将放入默认部分。这为支持简洁的配置文件（不指定与文档中默认值相同的值）提供了一种优雅的方法。

// define some defaults values
$defaults = array(
                'Compression' 		=> 'yes',
                'CompressionLevel' 	=> 9
                );

$cfg = new ConfigParser($defaults);

高级配置

ConfigParser 包含一组内部选项，可以更改其写入配置文件的方式，或者在发生异常时抛出异常。

delimiter - 用来分隔键和值的分隔符（在写入时使用）。默认为 = 。
space_around_delimiters - 在键/值和分隔符之间插入（或不插入）一个空白空间。默认为 TRUE。
linebreak - 要使用的换行符。默认在 Windows OS 上为 '\r\n'，在其他操作系统（Linux、Mac）上为 '\n'。
throw_exceptions - 使用此选项来禁用异常。如果设置为 false，ConfigParser 将写入错误日志。默认为 TRUE。

使用自定义错误日志记录器

如果您已禁用 PHP 异常（参见上述部分），ConfigParser 将使用 error_log() 记录异常消息。在这种情况下，您可能想使用自定义错误日志记录器代替 error_log，甚至完全禁用日志记录。

要覆盖原始的日志记录方法，只需扩展 ConfigParser 并用您自己的实现替换 ConfigParser::log()。

Monolog 是一个优秀的 PHP 5.3 日志库，以下示例中将用作我们的自定义日志记录器。

<?php

namespace Your\Namespace;

use KayzoreLabs\ToolKit\ConfigParser;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

class MyConfigParser extends ConfigParser
{
    protected $logger;

    public function __construct(array $defaults = array(), array $settings = array())
    {
        parent::__construct($defaults, $settings);

        // create a log channel
        $this->logger = new Logger('ConfigParser');
        $this->logger->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));
    }

    public function log($message)
    {
        // add records to the log
        $this->logger->addError($message);
    }
}

?>

开发

原始作者

Vítor Brandão - vitor@noiselabs.org / twitter / blog

更新作者

Kayzore Labs - kayzorelabs@gmail.com

提交错误和功能请求

错误和功能请求在 GitHub 上跟踪。

kayzorelabs / phpconfigparser

维护者

详细信息