README

轻量级 PHP htaccess 解析器

简介

PHP Htaccess Parser 是一个小巧轻量级的库，可以解析（或标记，如果更喜欢的话）apache .htaccess 文件。它是为个人使用开发的，用于安全地读取和操作 .htaccess 文件。

特性

解析器支持

指令（例如：Options -MultiViews）
块和子块（例如：<IfModule mod_headers.c>）
多行语句（以 / 结尾的行）
空行
注释

安装

您可以通过克隆 git 仓库或使用 composer 来安装它。

Git 克隆

git clone https://github.com/tivie/php-htaccess-parser.git

Composer

将这些行添加到您的 composer.json 中

    {
        "require": {
            "tivie/htaccess-parser": "*"
        }
    }

或运行以下命令

php composer.phar require tivie/htaccess-parser

工作原理

将 .htaccess 文件的每一行解析并转换为以下标记之一

每个标记实现了 TokenInterface，它提供了一个简单的 api 来读取和修改其属性。

标记聚合在 HtaccessContainer 中，可以用来添加、修改或删除标记对象，并以纯文本或 json 格式导出。

快速使用指南

使用 PHP Htaccess Parser 非常简单。

$file = new \SplFileObject('path/to/.htaccess');
$parser = new \Tivie\HtaccessParser\Parser();
$htaccess = $parser->parse($file);

然后您可以使用 $htaccess 来操作 .htaccess 内容。

$block = new Block();
$htaccess[0] = $block;

例如，打印文件的第一个标记

echo $htaccess[0];

将标记或 HtaccessContainer 对象转换为字符串返回该元素的字面表示，可用于重新创建 .htaccess 文件。

$output = (string) $htaccess;
file_put_content('.htaccess', $htaccess);

组件

解析器

Parser 类是库的主要组件。由于它的构造函数不需要任何强制参数，初始化解析器对象非常简单

$parser = new \Tivie\HtaccessParser\Parser();

解析器选项

可以通过以下方法或选项更改解析器的行为

设置文件

解析器使用 \SplFileObject 访问文件。您可以在构造函数中通过调用 setFile() 或作为 $parser->parse 的第一个参数设置适当的文件

$parser = new Parser(new \SplObjectStorage('/path/to/file'));
$parser->setFile(new \SplObjectStorage('/path/to/file'));
$parser->parse(new \SplObjectStorage('/path/to/file'));

更改容器

默认情况下，$parser->parse() 返回一个 HtaccessContainer 对象（它扩展了 ArrayObject），其中包含新标记的 .htaccess 文件。您可以通过调用 setContainer() 方法更改返回的对象

$parser->setContainer($myContainer);

$myContainer 可以是一个数组或实现 ArrayAccess 的对象。

使用数组

每个标记都是一个实现 TokenInterface 的对象，它提供了几个有用的方法。但是，如果您更喜欢，可以指示解析器使用简单的数组，通过

调用方法 useArrays()

$parser->useArrays(true);

使用 USE_ARRAYS 标志与 parse 方法一起使用。

$parser->parse(null, USE_ARRAYS);

忽略空行和注释行

您可以通过以下方式指示解析器忽略空行、注释行或两者

调用相应的方法

$parser->ignoreWhiteLines(true)
       ->ignoreComments(true);

或将它作为标志设置在 $parser->parse 中

$parser->parse(null, IGNORE_WHITELINES|IGNORE_COMMENTS);

重置文件

默认情况下，在序列化之前，解析器会将文件指针重置到开头。您可以通过调用 rewindFile 方法来覆盖此操作。

$parser->rewindFile(false);

扩展解析器

解析器类提供了开发者可以重写的API点。更多信息，您可以查看以下代码：https://github.com/tivie/php-htaccess-parser/blob/master/src/Parser.php

HtaccessContainer对象

默认返回的对象（HtaccessContainer）实现了ArrayAccess接口，因此您可以通过数组的方式访问定义。该数组的键是数字的，并按照它们在原始文件中出现的顺序排序。

检索标记

由于解析器返回一个数组或数组对象，您可以通过索引检索特定的标记

$firstToken = $htaccess[0];

您还可以使用search方法通过名称查找特定的标记

$modRewrite = $htaccess->search('modRewrite');

您可以将搜索约束到特定的标记类型。

$modRewrite = $htaccess->search('modRewrite', \Tivie\HtaccessParser\Token\TOKEN_BLOCK);

修改标记

TokenInterface提供了一个通用的API，您可以使用它来操作标记。

$token->setName('fooBar'); //Changes the name of the Token
$token->setArguments('foo', 'bar', 'baz'); //Changes the Token arguments

但是请注意，对于某些标记，参数数组并没有太多意义。例如，注释标记只期望1个参数（注释的实际文本）而空白行标记不期望任何参数，因此额外的参数将被静默忽略。

添加标记

您可以通过创建和追加标记来添加标记。

$newBlock = new Block('modRewrite');
$htaccess[] = $block;

您还可以使用insertAt方法将标记插入到特定的索引。

$newBlock = new Block('modRewrite');
$htaccess->insertAt(4, $newBlock);

输出htaccess

为了输出一个.txt的.htaccess文件，您可以强制将HtaccessContainer转换为字符串，并将生成的字符串写入文件

$output = (string) $htaccess;
file_put_content('.htaccess', $output);

您还可以使用txtSerialize方法来控制输出的格式

$output = $htaccess->ignoreWhiteLines(true)
                   ->ignoreComments(false);
file_put_content('.htaccess', $output);

注意：请注意，解析器中忽略的元素将不会在HtaccessContainer序列化方法中可用。

贡献

请随意通过分支或提出建议来做出贡献。

问题跟踪器：https://github.com/tivie/php-htaccess-parser/issues

源代码：https://github.com/tivie/php-htaccess-parser

许可证

PHP Htaccess Parser在Apache 2.0许可证下发布。有关更多信息，请参阅此存储库中的LICENSE文件或https://apache.ac.cn/licenses/LICENSE-2.0.txt。

tivie / htaccess-parser

维护者

详细信息