README

它是如何工作的

此包可以通过以下方式验证 security.txt 文件：

• 通过调用 Spaze\SecurityTxt\Parser\SecurityTxtParser::parseString() 提供文件内容作为字符串
• 将主机名如 example.com 传递给 Spaze\SecurityTxt\Parser\SecurityTxtParser::parseHost()
• 将 URL 如 https://example.com/ 传递给 Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check()

上述每个选项都会调用前面的方法并添加更多仅在该特定情况下可行的验证。

在 bin 中还有一个命令行脚本，它使用 Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check()，主要是为了向 Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check() 添加命令行输出。

如果您想解耦获取 security.txt 文件和解析它，还可以将 SecurityTxtFetchResult 对象传递给 Spaze\SecurityTxt\Parser\SecurityTxtParser::parseFetchResult()。

如何使用它

Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check() 可能是您想要使用的，因为它提供了最全面的检查，可以传递 URL（不仅仅是主机名），还支持回调。它接受以下参数：

字符串 $url

文件将被查找的 URL，例如您可以传递 https://example.com，无需使用 security.txt 文件的完整路径，因为只会使用 URL 的主机名进行后续检查

?int $expiresWarningThreshold = null

验证器将在文件即将过期时开始抛出警告，并且您可以指定“即将过期”意味着多少天

bool $strictMode = false

如果您启用严格模式，则文件将被视为无效，这意味着 SecurityTxtCheckHostResult::isValid() 将返回 false，即使只有警告，如果没有启用严格模式，只有警告的文件仍然是有效的，并且 SecurityTxtCheckHostResult::isValid() 将返回 true

bool $noIpv6 = false

因为一些环境不支持 IPv6，比如 GitHub Actions

Spaze\SecurityTxt\Check\SecurityTxtCheckHost::check() 返回一个具有一些明显和不那么明显的属性的 Spaze\SecurityTxt\Check\SecurityTxtCheckHostResult 对象。不那么明显的属性可以通过以下方法获得。所有这些方法都返回一个 SecurityTxtSpecViolation 后裔数组。

getFetchErrors()

返回 list<SecurityTxtSpecViolation>，包含从服务器获取文件时遇到的错误。例如但不限于

• 当内容类型或字符集错误时
• 当 URL 方案不是 HTTPS 时

getFetchWarnings()

也返回 list<SecurityTxtSpecViolation>，在获取文件时具有警告，例如但不限于

• 当 /security.txt 和 /.well-known/security.txt 中的文件不同时
• 当 /security.txt 没有重定向到 /.well-known/security.txt 时

getLineErrors()

返回 array<int, list<SecurityTxtSpecViolation>>，其中 int 键是行号。包含解析和验证 security.txt 文件内容时发现的错误。这些错误由实现 FieldProcessor 接口的任何类产生。错误包括但不限于

• 当字段使用不正确的分隔符时
• 当字段值不是 URL 或 URL 未使用 https:// 方案时

getLineWarnings()

还返回一个数组 array<int, list<SecurityTxtSpecViolation>>，其中 int 键是行号。包含在解析和验证 security.txt 文件内容时由实现 FieldProcessor 接口的任何类生成的警告。这些警告包括但不限于：

• 当 Expires 字段的值过于未来时

getFileErrors()

返回 list<SecurityTxtSpecViolation>，该列表包含无法与任何单行配对的文件级错误。这些错误由 FieldValidator 子类生成，包括：

• 当缺少必需字段如 Contact 或 Expires 时

getFileWarnings()

返回 list<SecurityTxtSpecViolation>，该列表包含无法与任何单行配对的文件级警告。这些警告由 FieldValidator 子类生成，例如：

• 当文件已签名，但没有 Canonical 字段时

回调函数

SecurityTxtCheckHost::check() 支持回调函数，可以通过 SecurityTxtCheckHost::addOn*() 方法设置。您可以使用它们以“实时”获取解析信息，例如，由 bin/checksecuritytxt.php 脚本通过 \Spaze\SecurityTxt\Check\SecurityTxtCheckHostCli 类打印信息，以便信息一出现就打印出来。

JSON

可以使用 json_encode() 将 Spaze\SecurityTxt\Check\SecurityTxtCheckHostResult 对象编码为 JSON，并使用 Spaze\SecurityTxt\Check\SecurityTxtCheckHostResultFactory::createFromJson() 解码。

其他方法

无论是 Spaze\SecurityTxt\Parser\SecurityTxtParser::parseString() 还是 Spaze\SecurityTxt\Parser\SecurityTxtParser::parseHost()，都返回一个具有与上面描述的 SecurityTxtCheckHostResult 类似方法的 Spaze\SecurityTxt\Parser\SecurityTxtParseResult 对象。从 parseHost() 返回的结果还包含 Spaze\SecurityTxt\Fetcher\SecurityTxtFetchResult 对象。