README

• 简介
• 许可
• 安装
• 示例用法
• 实现说明
  • 设置用户代理
  • 记录分隔符
  • 大小写敏感
  • 编码转换
  • 特性
• 选项
  • Tester类选项
  • Filter类选项
  • FilterParser类选项
  • Parser类选项
• 接口

简介

robots-txt-processor是一个用于处理互联网自然通配符robots.txt数据的测试器，具有过滤功能。该模块可以过滤如

• 其他用户代理的规则
• 过长的规则
• 包含太多通配符的路径
• 注释（行内或整行）

此外，例如还可以

• 解析行续行符（LWS,），尽管不太常用
• 识别拼写错误的Useragent指令
• 补充路径中缺少的起始斜杠

测试模块可以处理包含*/$元字符的Allow/Disallow指令。或者，您可以使用过滤器模块单独使用，并将输出作为单个User-agent: *记录（非分组记录）提供给另一个测试模块（例如Sitemap。）

许可

BSD 2-Clause License

安装

composer require "ranvis/robots-txt-processor:^1.0"

示例用法

require_once __DIR__ . '/vendor/autoload.php';

$source = "User-agent: *\nDisallow: /path";
$userAgents = 'MyBotIdentifier';
$tester = new \Ranvis\RobotsTxt\Tester();
$tester->setSource($source, $userAgents);
var_dump($tester->isAllowed('/path.html')); // false

Tester->setSource(string)实际上是Tester->setSource(RecordSet)的缩写

use Ranvis\RobotsTxt;

$source = "User-agent: *\nDisallow: /path";
$userAgents = 'MyBotIdentifier';
$filter = new RobotsTxt\Filter();
$filter->setUserAgents($userAgents);
$recordSet = $filter->getRecordSet($source);
$tester = new RobotsTxt\Tester();
$tester->setSource($recordSet);
var_dump($tester->isAllowed('/path.php')); // false

请参阅EXAMPLES.md获取更多示例，包括仅过滤器使用。

实现说明

设置用户代理

设置源时，您可以（可选）传递如上例所示的用户代理。如果您传递用户代理字符串或字符串数组，后续的Filter将过滤出未指定的用户代理记录（除了*以外。）而Tester->isAllowed()接受用户代理，但它运行得更快，可以使用Filter->setUserAgents()或Tester->setSource(source, userAgents)进行过滤，并多次调用Tester->isAllowed()而不指定用户代理。（当传递用户代理字符串数组时，先指定的用户代理在测试时具有优先权。）

记录分隔符

此解析器忽略空白行。另一个记录从组成员行之后的用户代理行开始（即Disallow/Allow。）

大小写敏感

User-agent值和如Disallow之类的指令名称不区分大小写。Filter类将指令名称规范化为首字母大写形式。

编码转换

此过滤器/测试器本身不处理编码转换，因为它不是必需的。如果远程robots.txt使用某些非Unicode（特别是非UTF-8）编码，则URL路径也应使用该编码。过滤器/测试器可以安全地处理任何字符或百分号编码序列，这些序列可能导致无效的UTF-8。一个例外是当远程robots.txt使用带有BOM的任何Unicode编码时。如果这种情况发生，您需要事先将其转换为UTF-8（不带BOM）。

特性

请参阅robots-txt-processor-test项目的features/behaviors table。

选项

选项可以指定在构造函数的第一个参数中。通常，默认值应该足够过滤潜在的有害输入，同时保留请求的规则。

Tester类选项

• 'respectOrder' => false,

  如果为true，按指定顺序处理路径规则。如果为false，则首先处理较长的路径，如Googlebot所做的那样。

• 'ignoreForbidden' => false,

  如果为true，则将setResponseCode()与401 Unauthorized或403 Forbidden视为不存在robots.txt，如Googlebot所做的那样，而不是像robotstxt.org规范那样。

• 'escapedWildcard' => false,

  如果为true，路径行中的%2A将被视为通配符*。通常你不想为这个类设置这个选项为true。有关更多信息，请参阅Filter类。

Tester->setSource(string)内部使用初始传递的选项实例化Filter，并调用Filter->getRecordSet(string)。

Filter类选项

• 'maxRecords' => 1000,

  要解析的记录（分组规则）的最大数量。之后的任何记录都将不会保留。不要设置得太低，否则过滤器会在你的用户代理之前放弃。此限制仅适用于解析。调用setUserAgents()限制要保留的用户代理。

Filter->getRecordSet(string)内部使用初始传递的选项实例化FilterParser。

FilterParser类选项

• 'maxLines' => 1000,

  每个记录（分组或非分组）要解析的最大行数。对于当前记录之后的任何行都将不会保留。

• 'keepTrailingSpaces' => false,

  如果为false，则去除不带注释的行的尾部空格（包括制表符）。对于带注释的行，#前的空格总是会被去除。保留空格是robotstxt.org和Google规范的要求。

• 'maxWildcards' => 10,

  要接受的路径中非重复*的最大数量。如果一个路径包含超过这个数量的通配符，该规则本身将被忽略。

• 'escapedWildcard' => true,

  如果为true，路径行中的%2A将被视为通配符*，并将受到maxWildcards的限制。当使用外部测试器时，除非你确定你的测试器不会以这种方式处理%2A（并且这个测试器也不会），否则不要将其设置为false，以防止规则绕过maxWildcards的限制。（在特性测试表中列出的测试器应不更改此标志。）

• 'complementLeadingSlash' => true,

  如果为true，并且路径不以/或*（这必须是一个错误）开头，则会在前面添加/。

• 'pathMemberRegEx' => '/^(?:Dis)?Allow$/i',

  匹配此正则表达式的指令的值被视为路径，并应用如maxWildcards之类的配置。

FilterParser扩展了Parser类。

Parser类选项

• 'maxUserAgents' => 1000,

  要解析的用户代理的最大数量。之后的任何用户代理都将被忽略，并且之后的任何新分组记录都将被跳过。

• 'maxDirectiveLength' => 32,

  指令的最大字符数。任何超过这个长度的指令都将被跳过。至少需要10个字符来解析User-agent指令。如果你需要保留自定义的长名称指令值，请增加。

• 'maxNameLength' => 200,

  User-agent值的最大字符数。任何超过这个长度的用户代理名称都将被截断。

• 'maxValueLength' => 2000,

  指令值的最大字符数。任何超过这个长度的值都将被更改为-ignored-指令，其值包含原始值长度。

• 'userAgentRegEx' => '/^User-?agent$/i',

  匹配此正则表达式的指令被视为User-agent指令。

接口

• new Tester(array $options = [])
• Tester->setSource($source, $userAgents = null)
• Tester->setResponseCode(int $code)
• Tester->isAllowed(string $targetPath, $userAgents = null)
• new Filter(array $options = [])
• Filter->setUserAgents($userAgents, bool $fallback = true) : RecordSet
• Filter->getRecordSet($source) : RecordSet
• new Parser(array $options = [])
• Parser->registerGroupDirective(string $directive)
• Parser->getRecordIterator($it) : \Traversable
• (string)RecordSet
• RecordSet->extract($userAgents = null)
• RecordSet->getRecord($userAgents = null, bool $dummy = true) : ?RecordSet
• RecordSet->getNonGroupRecord(bool $dummy = true) : ?RecordSet
• (string)Record
• Record->getValue(string $directive) : ?string
• Record->getValueIterator(string $directive) : \Traversable