README

php-htmldiff 是一个用于比较两个HTML文件/片段，并使用简单HTML突出显示差异的库。

这个HTML Diff实现是从 rashid2538/php-htmldiff 分支出来的，并添加了新功能、修复了错误和增强了原始代码。

有关这些修改的更多信息，请阅读 与 rashid2538/php-htmldiff 的差异 或查看 变更日志。

演示

https://php-htmldiff.caxy.com/

安装

推荐通过 Composer 安装 php-htmldiff。通过以下命令安装 caxy/php-htmldiff 包：

composer require caxy/php-htmldiff

这将解决最新稳定版本。

否则，您可以自行安装库并设置自动加载器。

与 Symfony 一起使用

如果您正在使用 Symfony，您可以使用 caxy/HtmlDiffBundle 使生活更简单！

使用方法

use Caxy\HtmlDiff\HtmlDiff;

$htmlDiff = new HtmlDiff($oldHtml, $newHtml);
$content = $htmlDiff->build();

CSS 示例

有关可用于显示HTML差异输出的起始CSS，请参阅 https://github.com/caxy/php-htmldiff/blob/master/demo/codes.css。

配置

HtmlDiff的配置包含在 Caxy\HtmlDiff\HtmlDiffConfig 类中。

有两种方式设置配置

1. 配置现有的HtmlDiff对象
2. 创建并使用HtmlDiffConfig对象

配置现有的HtmlDiff对象

当创建一个新的 HtmlDiff 对象时，它会创建一个具有默认配置的 HtmlDiffConfig 对象。您可以通过对象上的setter更改配置

use Caxy\HtmlDiff\HtmlDiff;

// ...

$htmlDiff = new HtmlDiff($oldHtml, $newHtml);

// Set some of the configuration options.
$htmlDiff->getConfig()
    ->setMatchThreshold(80)
    ->setInsertSpaceInReplace(true)
;

// Calculate the differences using the configuration and get the html diff.
$content = $htmlDiff->build();

// ...

创建并使用HtmlDiffConfig对象

您也可以通过创建 Caxy\HtmlDiff\HtmlDiffConfig 的实例并使用它来创建新的 HtmlDiff 对象，使用 HtmlDiff::create。

当创建多个 HtmlDiff 实例时，这很有用

use Caxy\HtmlDiff\HtmlDiff;
use Caxy\HtmlDiff\HtmlDiffConfig;

// ...

$config = new HtmlDiffConfig();
$config
    ->setMatchThreshold(95)
    ->setInsertSpaceInReplace(true)
;

// Create an HtmlDiff object with the custom configuration.
$firstHtmlDiff = HtmlDiff::create($oldHtml, $newHtml, $config);
$firstContent = $firstHtmlDiff->build();

$secondHtmlDiff = HtmlDiff::create($oldHtml2, $newHtml2, $config);
$secondHtmlDiff->getConfig()->setMatchThreshold(50);

$secondContent = $secondHtmlDiff->build();

// ...

完整的默认配置

$config = new HtmlDiffConfig();
$config
    // Percentage required for list items to be considered a match.
    ->setMatchThreshold(80)
    
    // Set the encoding of the text to be diffed.
    ->setEncoding('UTF-8')
    
    // If true, a space will be added between the <del> and <ins> tags of text that was replaced.
    ->setInsertSpaceInReplace(false)
    
    // Option to disable the new Table Diffing feature and treat tables as regular text.
    ->setUseTableDiffing(true)
    
    // Pass an instance of \Doctrine\Common\Cache\Cache to cache the calculated diffs.
    ->setCacheProvider(null)

    // Disable the HTML purifier (only do this if you known what you're doing)
    // This bundle heavily relies on the purified input from ezyang/htmlpurifier
    ->setPurifierEnabled(true)
    
    // Set the cache directory that HTMLPurifier should use.
    ->setPurifierCacheLocation(null)
    
    // Group consecutive deletions and insertions instead of showing a deletion and insertion for each word individually. 
    ->setGroupDiffs(true)
    
    // List of characters to consider part of a single word when in the middle of text.
    ->setSpecialCaseChars(array('.', ',', '(', ')', '\''))
        
    // List of tags (and their replacement strings) to be diffed in isolation.
    ->setIsolatedDiffTags(array(
        'ol'     => '[[REPLACE_ORDERED_LIST]]',
        'ul'     => '[[REPLACE_UNORDERED_LIST]]',
        'sub'    => '[[REPLACE_SUB_SCRIPT]]',
        'sup'    => '[[REPLACE_SUPER_SCRIPT]]',
        'dl'     => '[[REPLACE_DEFINITION_LIST]]',
        'table'  => '[[REPLACE_TABLE]]',
        'strong' => '[[REPLACE_STRONG]]',
        'b'      => '[[REPLACE_B]]',
        'em'     => '[[REPLACE_EM]]',
        'i'      => '[[REPLACE_I]]',
        'a'      => '[[REPLACE_A]]',
    ))
    
    // Sets whether newline characters are kept or removed when `$htmlDiff->build()` is called.
    // For example, if your content includes <pre> tags, you might want to set this to true.
    ->setKeepNewLines(false)
;

贡献

请参阅 CONTRIBUTING 文件。

贡献者行为准则

请注意，本项目按照 贡献者行为准则 发布。通过参与本项目，您同意遵守其条款。请参阅 行为准则 文件。

鸣谢

• SavageTiger 为 caxy/php-htmldiff 贡献了许多改进和修复！
• rashid2538 为将项目移植到PHP和我们的项目基础： rashid2538/php-htmldiff
• 感谢 willdurand 在开源库方面的优秀文章。本文档的大部分内容基于该文章中的示例。

我们遗漏了谁吗？如果遗漏了，请告诉我们或在 pull request 中提出！

许可证

php-htmldiff 在GNU 通用公共许可证，版本 2下可用。有关详细信息，请参阅LICENSE文件。

待办事项

• 测试，测试，更多测试！(主要是单元测试) - 在进行 v1 版本的重大重构/清理之前，我们需要更多的测试
• 添加设置缓存提供程序（doctrine cache）的文档
  • 可能添加缓存和 doctrine cache 的抽象层和适配器
• 将 HTML Purifier 作为可选依赖项 - 可能使用抽象层进行 purifiers，以便可以使用替代品（或根本不使用以提高性能）
• 公开 HTML Purifier 的配置（用于表格比较） - 当前通过 HtmlDiffConfig 对象只能配置缓存目录
• 性能改进（我们有一个基准测试，我们可能需要更多）
  • 算法改进 - 去除开始和结尾的类似文本，将嵌套比较结果存储在内存中以重复使用（就像我们使用缓存一样）
  • 使用 DOMDocument 与替代品和字符串解析进行比较的基准测试
  • 考虑不使用字符串解析进行 HtmlDiff，以避免在 ListDiff 和 TableDiff 中创建许多 DOMDocument 实例
• 基准测试
• 重构（但...先进行测试）
  • 总体设计/架构改进
  • API 改进，以便不需要为每个新的 diff 创建新的 HtmlDiff（特别是配置可以重用）
• 将演示应用程序拆分为单独的存储库
• 添加有关替代 htmldiff 引擎的文档，并可能进行一些比较