blackrabbit/readability.php

Readability.js 的 PHP 版本

维护者

详细信息

github.com/blackrabbit944/readability.php

主页

源代码

安装: 2

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 89

语言:HTML

dev-main 2022-11-25 06:06 UTC

Requires

Requires (Dev)

Suggests

Apache-2.0 7f900274aed09f2537df10b259644e003aae3e78

  • Andres Rey <andreskrey.woop@gmail.com>

htmlreadability

This package is auto-updated.

Last update: 2024-09-25 09:47:03 UTC

README

新闻（2021年8月）

Readability.php 的原始开发者 Andres Rey 仁慈地允许我们接管项目的维护和开发。

请耐心等待我们赶上 Readability.js 的变化。准备好后，将会有一个新的版本（3.0.0）发布。

关于我们在本存储库中已做的更改，请参阅我们的博客文章。

关于

Latest Stable Version Tests

PHP 版本的 Mozilla 的 Readability.js。解析 HTML 文本（通常是新闻和其他文章）并返回 标题、作者、主要图片 和 文本内容，没有导航栏、广告、页脚或其他不是文本主体内容的东西。分析每个节点，给它们打分，并确定哪些是相关的，哪些可以丢弃。

Screenshot

项目的目标是成为 Mozilla 版本的 1:1 端口，并紧跟那里引入的所有更改，但在结构上存在一些重大差异。大部分代码是 1:1 的复制——甚至注释也被导入——但一些函数和结构被调整为更好地适应 PHP 语言。

原始开发者: Andres Rey

开发者/维护者: blackrabbit.org

代码移植

主分支 - 截至 2021 年 8 月 26 日更新，除了一块代码外，这块代码在 PHP 版本和 JS 版本中产生的结果不一致。也许有错误，或者底层代码中的某些差异影响了这一点。如果你知道问题所在，请随时给我们留言或提交一个拉取请求。 :)

版本 2.1.0 - 与 Readability.js 至 2018 年 11 月 19 日 保持同步。

要求

PHP 7.4+、ext-dom、ext-xml 和 ext-mbstring。在 *nix 类环境中安装这些依赖项（在您系统尚未安装的情况下），可以尝试以下操作

$ sudo apt-get install php7.4-xml php7.4-mbstring

如何使用

首先，您必须使用 composer 引入库

composer require blackrabbit/readability.php

然后，创建一个 Readability 类并传入一个配置类，将 HTML 传递给 parse() 函数，并输出变量

<?php
require __DIR__ . '/vendor/autoload.php';
use blackrabbit\Readability\Readability;
use blackrabbit\Readability\Configuration;
use blackrabbit\Readability\ParseException;

$readability = new Readability(new Configuration());

$html = file_get_contents('http://your.favorite.newspaper/article.html');

try {
    $readability->parse($html);
    echo $readability;
} catch (ParseException $e) {
    echo sprintf('Error processing text: %s', $e->getMessage());
}

您的脚本将输出解析后的文本或报告任何错误。您应该始终在 try/catch 块中封装 ->parse 调用，因为如果 HTML 无法正确解析，将抛出 ParseException。

如果您想更精细地控制输出，只需逐个调用属性，并用您自己的 HTML 包装它们。

<h1><?= $readability->getTitle(); ?></h1>
<h2>By <?= $readability->getAuthor(); ?></h2>
<div class="content"><?= $readability->getContent(); ?></div>

以下是可用属性的列表

  • 文章标题：->getTitle();
  • 文章内容：->getContent();
  • 摘要：->getExcerpt();
  • 主要图片：->getImage();
  • 所有图片：->getImages();
  • 作者：->getAuthor();
  • 文本方向（ltr 或 rtl）：->getDirection();

如果您需要调整最终的HTML，可以通过调用->getDOMDocument()来获取结果文档的DOMDocument。

选项

您可以通过配置对象来更改Readability的行为。例如，如果您想修复相对URL并声明原始URL，可以设置配置如下

$configuration = new Configuration();
$configuration
    ->setFixRelativeURLs(true)
    ->setOriginalURL('http://my.newspaper.url/article/something-interesting-to-read.html');

您还可以向构造函数传递一个配置参数数组

$configuration = new Configuration([
    'fixRelativeURLs' => true,
    'originalURL'     => 'http://my.newspaper.url/article/something-interesting-to-read.html',
    // other parameters ... listing below
]);

然后将此配置对象传递给Readability。以下是一些可用的选项。记得在使用原生设置器调用时，要预先添加set。

  • MaxTopCandidates：默认值5，顶级候选人的最大数量。
  • CharThreshold：默认值500，考虑文章解析成功所需的最小字符数。
  • ArticleByLine：默认值false，搜索文章署名并将其从文本中移除。它将被移动到文章元数据中。
  • StripUnlikelyCandidates：默认值true，移除不太可能包含相关信息的内容。对调试或解析复杂或非标准文章很有用。
  • CleanConditionally：默认值true，在解析后移除某些节点，以返回更干净的结果。
  • WeightClasses：默认值true，在评分阶段对类别进行加权。
  • FixRelativeURLs：默认值false，将相对URL转换为绝对URL。例如，/test转换为http://host/test。
  • SubstituteEntities：默认值false，禁用libxml的substituteEntities标志。将避免替换HTML实体。例如，&aacute;转换为á。
  • NormalizeEntities：默认值false，将UTF-8字符转换为其HTML实体等效项。对解析具有混合编码的HTML很有用。
  • OriginalURL：默认值http://fakehost，用于修复相对URL的文章原始URL。
  • KeepClasses：默认值false，删除所有HTML元素的class="..."属性值。
  • Parser：默认值html5，使用HTML5-PHP进行解析。将其设置为libxml以使用它（不推荐用于现代HTML文档）。
  • SummonCthulhu：默认值false，通过正则表达式删除所有<script>节点。这不是理想的解决方案，因为它可能会破坏某些内容，但如果您已将解析器设置为libxml（如上所述），则可能是唯一的解决方案，以解决libxml与未转义javascript的问题。

调试日志

日志记录是可选的，您必须注入自己的记录器以保存所有调试消息。为此，使用实现PSR-3记录接口的记录器，并将其传递给配置对象。例如

// Using monolog

$log = new Logger('Readability');
$log->pushHandler(new StreamHandler('path/to/my/log.txt'));

$configuration->setLogger($log);

在日志中，您将找到有关已解析节点、为什么移除它们以及为什么认为它们与最终文章相关联的信息。

限制

当然，主要的限制是PHP。通过懒加载、AJAX或任何类型的javascript调用加载内容的网站将被忽略（实际上，未运行）并且生成的文本与readability.js的结果相比将是不正确的。所有您想使用readability.php解析的文章都必须完整，并且所有内容都应在HTML中。

已知的libxml解析问题

从版本3.0.0开始，readability.php使用HTML5解析器。早期版本使用libxml。以下问题适用于libxml解析，因此如果您使用的是readability.php的早期版本（3.0.0之前），或者您在配置中已将解析器设置为libxml，请继续阅读...

Javascript溢出到文本主体

DOMDocument在解析带有未转义HTML的字符串时存在一些问题。考虑以下代码

<div> <!-- Offending div without closing tag -->
<script type="text/javascript">
       var test = '</div>';
       // I should not appear on the result
</script>

如果您想移除HTML中的脚本（如readability所做的那样），您可能会期望最终只留下一个div和一个注释。问题是libxml将关闭div标签视为HTML标签，实际上关闭了未关闭的标签，并将剩余的javascript作为字符串留在p标签内。如果您保存该节点，最终的HTML将变成这样：

<div> <!-- Offending div without closing tag -->
<p>';
       // I should not appear on the result
</p></div>

这是一个libxml问题，而不是Readability.php的bug。

有一个解决方案：使用summonCthulhu选项。这将通过正则表达式删除所有script标签，这不是最佳做法，因为您可能会召唤黑暗之神。

&nbsp实体消失

&nbsp实体被libxml自动转换为空格，无法禁用。

自闭合标签渲染为完全展开的标签

自闭合标签，如<br />，会自动展开为<br></br。在libxml中无法禁用。

依赖项

Readability.php使用

  • HTML5-PHP来解析和序列化HTML。
  • PSR Log接口来定义允许的日志记录器类型。
  • Monolog仅在开发安装中需要。（在composer install期间的--dev选项）。

待办事项

  • 跟踪Readability.js的变化
  • 为__toString()方法添加一个小型模板引擎，而不是使用硬编码的一个。
  • 将所有iterator_to_array调用替换为自定义PHP生成器，该生成器可以跟踪已删除或修改的节点。

工作原理

Readability使用DOMDocument解析所有文本，扫描文本节点并给出分数，基于单词数、链接数和元素类型。然后它选择得分最高的元素，并使用所有兄弟元素创建一个新的DOMDocument。每个兄弟元素都会评分，以丢弃无用的元素，如导航栏、空节点等。

安全

如果您打算使用Readability处理不受信任的输入（无论是HTML还是DOM形式），我们强烈建议您使用类似HTML Purifier的清理库，以避免使用Readability输出时发生脚本注入。我们还建议使用CSP添加进一步的防御深度限制，限制您允许的结果内容可以执行的操作。Firefox的阅读模式集成本身使用了这两种技术。从输入中清理不安全内容不是Readability本身的目标 - 有其他很好的清理库，请使用它们！

测试

本地安装的PHP 7.4及以上版本应足够用于开发新功能和添加新测试用例。如果您想100%确信您的更改不会与其他PHP版本创建任何问题，您可以使用提供的Docker容器来测试目前在7.4、8.0、8.1上的版本。

您需要Docker和Docker Compose才能这样做。要运行三个PHP版本的测试，只需键入以下命令：

make test-all

这将启动所有容器并在每个支持的PHP版本上运行所有测试。如果您想针对特定版本进行测试，可以使用make test-7.4、make test-8.0或make test-8.1。

不同版本的libxml

如果您想针对支持的PHP版本和多个libxml版本进行测试，请运行test-all-versions。这将针对PHP版本7.4至8.1和libxml版本2.9.10、2.9.13和2.9.14进行测试。通常您不需要这样做，除非您认为您在libxml的特定版本上发现了bug。

更新预期测试

如果您对代码进行了改进，您可能希望检查这里测试用例的 Readability.php 输出。为了做到这一点，首先从项目文件夹的根目录运行以下命令

docker-compose up -d php-7.4-libxml-2.9.10

现在您应该有一个运行中的 Docker 镜像，项目根目录已映射到 Docker 实例上的 /app/（请参阅 docker-compose.yml）。从现在起，对这些文件的任何更改都将可以从 Docker 实例访问。

接下来，在 tests/ 中创建一个名为 /changed 的文件夹，然后运行以下命令以运行测试套件

docker-compose exec -e output-changes=1 -e output-diff=1 php-7.4-libxml-2.9.10 php /app/vendor/phpunit/phpunit/phpunit --configuration /app/phpunit.xml

这两个环境变量（output-changes=1 和 output-diff=1）会导致任何失败的测试（连同更改的 diff）被写入 changed/ 文件夹。

如果您对更改满意，将 output-diff=0 设置为值，diff 文件将不再被写入，这使得将新的预期输出文件复制到 test-pages 中相应的位置更容易。

许可证

基于 Arc90 的 readability.js（1.7.1）脚本，可在以下位置获取：http://code.google.com/p/arc90labs-readability

Copyright (c) 2010 Arc90 Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   https://apache.ac.cn/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.