www.aleph1.co.uk Git - yaffs-website/blob - vendor/caxy/php-htmldiff/README.md

   1 php-htmldiff
   2 ============
   3
   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]
  10
  11 php-htmldiff is a library for comparing two HTML files/snippets and highlighting the differences using simple HTML.
  12
  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.
  15
  16 For more information on these modifications, read the [differences from rashid2538/php-htmldiff][differences] or view the [CHANGELOG][changelog].
  17
  18 ## Installation
  19
  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:
  22
  23 ```sh
  24 composer require caxy/php-htmldiff
  25 ```
  26
  27 This will resolve the latest stable version.
  28
  29 Otherwise, install the library and setup the autoloader yourself.
  30
  31 ### Working with Symfony
  32
  33 If you are using Symfony, you can use the [caxy/HtmlDiffBundle][htmldiffbundle] to make life easy!
  34
  35 ## Usage
  36
  37 ```php
  38 use Caxy\HtmlDiff\HtmlDiff;
  39
  40 $htmlDiff = new HtmlDiff($oldHtml, $newHtml);
  41 $content = $htmlDiff->build();
  42 ```
  43
  44 ## Configuration
  45
  46 The configuration for HtmlDiff is contained in the `Caxy\HtmlDiff\HtmlDiffConfig` class.
  47
  48 There are two ways to set the configuration:
  49
  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)
  52
  53 #### Configure an Existing HtmlDiff Object
  54
  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:
  57
  58 ```php
  59 use Caxy\HtmlDiff\HtmlDiff;
  60
  61 // ...
  62
  63 $htmlDiff = new HtmlDiff($oldHtml, $newHtml);
  64
  65 // Set some of the configuration options.
  66 $htmlDiff->getConfig()
  67     ->setMatchThreshold(80)
  68     ->setInsertSpaceInReplace(true)
  69 ;
  70
  71 // Calculate the differences using the configuration and get the html diff.
  72 $content = $htmlDiff->build();
  73
  74 // ...
  75
  76 ```
  77
  78 #### Create and Use a HtmlDiffConfig Object
  79
  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`.
  83
  84 This is useful when creating more than one instance of `HtmlDiff`:
  85
  86 ```php
  87 use Caxy\HtmlDiff\HtmlDiff;
  88 use Caxy\HtmlDiff\HtmlDiffConfig;
  89
  90 // ...
  91
  92 $config = new HtmlDiffConfig();
  93 $config
  94     ->setMatchThreshold(95)
  95     ->setInsertSpaceInReplace(true)
  96 ;
  97
  98 // Create an HtmlDiff object with the custom configuration.
  99 $firstHtmlDiff = HtmlDiff::create($oldHtml, $newHtml, $config);
 100 $firstContent = $firstHtmlDiff->build();
 101
 102 $secondHtmlDiff = HtmlDiff::create($oldHtml2, $newHtml2, $config);
 103 $secondHtmlDiff->getConfig()->setMatchThreshold(50);
 104
 105 $secondContent = $secondHtmlDiff->build();
 106
 107 // ...
 108 ```
 109
 110 #### Full Configuration with Defaults:
 111
 112 ```php
 113
 114 $config = new HtmlDiffConfig();
 115 $config
 116     // Percentage required for list items to be considered a match.
 117     ->setMatchThreshold(80)
 118
 119     // Set the encoding of the text to be diffed.
 120     ->setEncoding('UTF-8')
 121
 122     // If true, a space will be added between the <del> and <ins> tags of text that was replaced.
 123     ->setInsertSpaceInReplace(false)
 124
 125     // Option to disable the new Table Diffing feature and treat tables as regular text.
 126     ->setUseTableDiffing(true)
 127
 128     // Pass an instance of \Doctrine\Common\Cache\Cache to cache the calculated diffs.
 129     ->setCacheProvider(null)
 130
 131     // Set the cache directory that HTMLPurifier should use.
 132     ->setPurifierCacheLocation(null)
 133
 134     // Group consecutive deletions and insertions instead of showing a deletion and insertion for each word individually.
 135     ->setGroupDiffs(true)
 136
 137     // List of characters to consider part of a single word when in the middle of text.
 138     ->setSpecialCaseChars(array('.', ',', '(', ')', '\''))
 139
 140     // List of tags to treat as special case tags.
 141     ->setSpecialCaseTags(array('strong', 'b', 'i', 'big', 'small', 'u', 'sub', 'sup', 'strike', 's', 'p'))
 142
 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]]',
 156     ))
 157 ;
 158
 159 ```
 160
 161 ## Contributing
 162
 163 See [CONTRIBUTING][contributing] file.
 164
 165 ## Contributor Code of Conduct
 166
 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.
 170
 171 ## Credits
 172
 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.
 177
 178 Did we miss anyone? If we did, let us know or put in a pull request!
 179
 180 ## License
 181
 182 php-htmldiff is available under [GNU General Public License, version 2][gnu]. See the [LICENSE][license] file for details.
 183
 184 ## TODO
 185
 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
 195 * Benchmarking
 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
 202
 203
 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/