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示例

有关可用的初始CSS示例，请参阅https://github.com/caxy/php-htmldiff/blob/master/demo/codes.css。

配置

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

有两种设置配置的方法

配置现有的HtmlDiff对象
创建和使用HtmlDiffConfig对象

配置现有的HtmlDiff对象

当创建新的HtmlDiff对象时，它会创建一个具有默认配置的HtmlDiffConfig对象。您可以使用对象上的设置器来更改配置

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::create创建新的HtmlDiff对象时使用它来设置配置。

这在创建多个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](https://github.com/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 改进，以便每个新的差异不需要新的 HtmlDiff（特别是为了使配置可重用）
将演示应用程序拆分为单独的存储库
添加关于替代 htmldiff 引擎的文档，或许还有一些比较

kamil-malinski / php-htmldiff

维护者

详细信息