4 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/quality-score.png?b=master)][badge_score]
5 [![Build Status](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/build.png?b=master)][badge_status]
6 [![Code Coverage](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/coverage.png?b=master)][badge_coverage]
7 [![Packagist](https://img.shields.io/packagist/dt/caxy/php-htmldiff.svg)][badge_packagist]
8 [![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/caxy/php-htmldiff.svg)][badge_resolve]
9 [![Percentage of issues still open](http://isitmaintained.com/badge/open/caxy/php-htmldiff.svg)][badge_issues]
11 php-htmldiff is a library for comparing two HTML files/snippets and highlighting the differences using simple HTML.
13 This HTML Diff implementation was forked from [rashid2538/php-htmldiff][upstream] and has been modified with new features,
14 bug fixes, and enhancements to the original code.
16 For more information on these modifications, read the [differences from rashid2538/php-htmldiff][differences] or view the [CHANGELOG][changelog].
20 The recommended way to install php-htmldiff is through [Composer][composer].
21 Require the [caxy/php-htmldiff][badge_packagist] package by running following command:
24 composer require caxy/php-htmldiff
27 This will resolve the latest stable version.
29 Otherwise, install the library and setup the autoloader yourself.
31 ### Working with Symfony
33 If you are using Symfony, you can use the [caxy/HtmlDiffBundle][htmldiffbundle] to make life easy!
38 use Caxy\HtmlDiff\HtmlDiff;
40 $htmlDiff = new HtmlDiff($oldHtml, $newHtml);
41 $content = $htmlDiff->build();
46 The configuration for HtmlDiff is contained in the `Caxy\HtmlDiff\HtmlDiffConfig` class.
48 There are two ways to set the configuration:
50 1. [Configure an Existing HtmlDiff Object](#configure-an-existing-htmldiff-object)
51 2. [Create and Use a HtmlDiffConfig Object](#create-and-use-a-htmldiffconfig-object)
53 #### Configure an Existing HtmlDiff Object
55 When a new `HtmlDiff` object is created, it creates a `HtmlDiffConfig` object with the default configuration.
56 You can change the configuration using setters on the object:
59 use Caxy\HtmlDiff\HtmlDiff;
63 $htmlDiff = new HtmlDiff($oldHtml, $newHtml);
65 // Set some of the configuration options.
66 $htmlDiff->getConfig()
67 ->setMatchThreshold(80)
68 ->setInsertSpaceInReplace(true)
71 // Calculate the differences using the configuration and get the html diff.
72 $content = $htmlDiff->build();
78 #### Create and Use a HtmlDiffConfig Object
80 You can also set the configuration by creating an instance of
81 `Caxy\HtmlDiff\HtmlDiffConfig` and using it when creating a new `HtmlDiff`
82 object using `HtmlDiff::create`.
84 This is useful when creating more than one instance of `HtmlDiff`:
87 use Caxy\HtmlDiff\HtmlDiff;
88 use Caxy\HtmlDiff\HtmlDiffConfig;
92 $config = new HtmlDiffConfig();
94 ->setMatchThreshold(95)
95 ->setInsertSpaceInReplace(true)
98 // Create an HtmlDiff object with the custom configuration.
99 $firstHtmlDiff = HtmlDiff::create($oldHtml, $newHtml, $config);
100 $firstContent = $firstHtmlDiff->build();
102 $secondHtmlDiff = HtmlDiff::create($oldHtml2, $newHtml2, $config);
103 $secondHtmlDiff->getConfig()->setMatchThreshold(50);
105 $secondContent = $secondHtmlDiff->build();
110 #### Full Configuration with Defaults:
114 $config = new HtmlDiffConfig();
116 // Percentage required for list items to be considered a match.
117 ->setMatchThreshold(80)
119 // Set the encoding of the text to be diffed.
120 ->setEncoding('UTF-8')
122 // If true, a space will be added between the <del> and <ins> tags of text that was replaced.
123 ->setInsertSpaceInReplace(false)
125 // Option to disable the new Table Diffing feature and treat tables as regular text.
126 ->setUseTableDiffing(true)
128 // Pass an instance of \Doctrine\Common\Cache\Cache to cache the calculated diffs.
129 ->setCacheProvider(null)
131 // Set the cache directory that HTMLPurifier should use.
132 ->setPurifierCacheLocation(null)
134 // Group consecutive deletions and insertions instead of showing a deletion and insertion for each word individually.
135 ->setGroupDiffs(true)
137 // List of characters to consider part of a single word when in the middle of text.
138 ->setSpecialCaseChars(array('.', ',', '(', ')', '\''))
140 // List of tags to treat as special case tags.
141 ->setSpecialCaseTags(array('strong', 'b', 'i', 'big', 'small', 'u', 'sub', 'sup', 'strike', 's', 'p'))
143 // List of tags (and their replacement strings) to be diffed in isolation.
144 ->setIsolatedDiffTags(array(
145 'ol' => '[[REPLACE_ORDERED_LIST]]',
146 'ul' => '[[REPLACE_UNORDERED_LIST]]',
147 'sub' => '[[REPLACE_SUB_SCRIPT]]',
148 'sup' => '[[REPLACE_SUPER_SCRIPT]]',
149 'dl' => '[[REPLACE_DEFINITION_LIST]]',
150 'table' => '[[REPLACE_TABLE]]',
151 'strong' => '[[REPLACE_STRONG]]',
152 'b' => '[[REPLACE_B]]',
153 'em' => '[[REPLACE_EM]]',
154 'i' => '[[REPLACE_I]]',
155 'a' => '[[REPLACE_A]]',
163 See [CONTRIBUTING][contributing] file.
165 ## Contributor Code of Conduct
167 Please note that this project is released with a [Contributor Code of
168 Conduct][contributor_covenant]. By participating in this project
169 you agree to abide by its terms. See [CODE_OF_CONDUCT][code_of_conduct] file.
173 * [SavageTiger][] for contributing many improvements and fixes to caxy/php-htmldiff!
174 * [rashid2538][] for the port to PHP and the base for our project: [rashid2538/php-htmldiff][upstream]
175 * [willdurand][] for an excellent post on [open sourcing libraries][].
176 Much of this documentation is based off of the examples in the post.
178 Did we miss anyone? If we did, let us know or put in a pull request!
182 php-htmldiff is available under [GNU General Public License, version 2][gnu]. See the [LICENSE][license] file for details.
186 * Tests, tests, and more tests! (mostly unit tests) - need more tests before we can major refactoring / cleanup for a v1 release
187 * Add documentation for setting up a cache provider (doctrine cache)
188 * Maybe add abstraction layer for cache + adapter for doctrine cache
189 * Make HTML Purifier an optional dependency - possibly use abstraction layer for purifiers so alternatives could be used (or none at all for performance)
190 * Expose configuration for HTML Purifier (used in table diffing) - currently only cache dir is configurable through HtmlDiffConfig object
191 * Add option to enable using HTML Purifier to purify all input
192 * Performance improvements (we have 1 benchmark test, we should probably get more)
193 * Algorithm improvements - trimming alike text at start and ends, store nested diff results in memory to re-use (like we do w/ caching)
194 * Benchmark using DOMDocument vs. alternatives vs. string parsing
196 * Look into removing dependency on php-simple-html-dom-parser library - possibly find alternative or no library at all. Consider how this affects performance.
197 * Refactoring (but... tests first)
198 * Overall design/architecture improvements
199 * API improvements so a new HtmlDiff isn't required for each new diff (especially so that configuration can be re-used)
200 * Split demo application to separate repository
201 * Add documentation on alternative htmldiff engines and perhaps some comparisons
204 [badge_score]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
205 [badge_status]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/build-status/master
206 [badge_coverage]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
207 [badge_packagist]: https://packagist.org/packages/caxy/php-htmldiff
208 [badge_resolve]: http://isitmaintained.com/project/caxy/php-htmldiff "Average time to resolve an issue"
209 [badge_issues]: http://isitmaintained.com/project/caxy/php-htmldiff "Percentage of issues still open"
210 [upstream]: https://github.com/rashid2538/php-htmldiff
211 [htmldiffbundle]: https://github.com/caxy/HtmlDiffBundle
212 [differences]: https://github.com/caxy/php-htmldiff/blob/master/doc/differences.rst
213 [changelog]: https://github.com/caxy/php-htmldiff/blob/master/CHANGELOG.md
214 [contributing]: https://github.com/caxy/php-htmldiff/blob/master/CONTRIBUTING.md
215 [gnu]: http://www.gnu.org/licenses/gpl-2.0.html
216 [license]: https://github.com/caxy/php-htmldiff/blob/master/LICENSE
217 [code_of_conduct]: https://github.com/caxy/php-htmldiff/blob/master/CODE_OF_CONDUCT.md
218 [composer]: http://getcomposer.org/
219 [contributor_covenant]: http://contributor-covenant.org/
220 [SavageTiger]: https://github.com/SavageTiger
221 [rashid2538]: https://github.com/rashid2538
222 [willdurand]: https://github.com/willdurand
223 [open sourcing libraries]: http://williamdurand.fr/2013/07/04/on-open-sourcing-libraries/