Plugin to allow visitor contributions to WordPress posts, wiki style.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 7.2 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. php-htmldiff
  2. ============
  3. [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/quality-score.png?b=master)][badge_score]
  4. [![Build Status](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/build.png?b=master)][badge_status]
  5. [![Code Coverage](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/coverage.png?b=master)][badge_coverage]
  6. [![Packagist](https://img.shields.io/packagist/dt/caxy/php-htmldiff.svg)][badge_packagist]
  7. [![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/caxy/php-htmldiff.svg)][badge_resolve]
  8. [![Percentage of issues still open](http://isitmaintained.com/badge/open/caxy/php-htmldiff.svg)][badge_issues]
  9. php-htmldiff is a library for comparing two HTML files/snippets and highlighting the differences using simple HTML.
  10. This HTML Diff implementation was forked from [rashid2538/php-htmldiff][upstream] and has been modified with new features,
  11. bug fixes, and enhancements to the original code.
  12. For more information on these modifications, read the [differences from rashid2538/php-htmldiff][differences] or view the [CHANGELOG][changelog].
  13. ## Installation
  14. The recommended way to install php-htmldiff is through [Composer][composer].
  15. Require the [caxy/php-htmldiff][badge_packagist] package by running following command:
  16. ```sh
  17. composer require caxy/php-htmldiff
  18. ```
  19. This will resolve the latest stable version.
  20. Otherwise, install the library and setup the autoloader yourself.
  21. ### Working with Symfony
  22. If you are using Symfony, you can use the [caxy/HtmlDiffBundle][htmldiffbundle] to make life easy!
  23. ## Usage
  24. ```php
  25. use Caxy\HtmlDiff\HtmlDiff;
  26. $htmlDiff = new HtmlDiff($oldHtml, $newHtml);
  27. $content = $htmlDiff->build();
  28. ```
  29. ## Configuration
  30. The configuration for HtmlDiff is contained in the `Caxy\HtmlDiff\HtmlDiffConfig` class.
  31. There are two ways to set the configuration:
  32. 1. [Configure an Existing HtmlDiff Object](#configure-an-existing-htmldiff-object)
  33. 2. [Create and Use a HtmlDiffConfig Object](#create-and-use-a-htmldiffconfig-object)
  34. #### Configure an Existing HtmlDiff Object
  35. When a new `HtmlDiff` object is created, it creates a `HtmlDiffConfig` object with the default configuration.
  36. You can change the configuration using setters on the object:
  37. ```php
  38. use Caxy\HtmlDiff\HtmlDiff;
  39. // ...
  40. $htmlDiff = new HtmlDiff($oldHtml, $newHtml);
  41. // Set some of the configuration options.
  42. $htmlDiff->getConfig()
  43. ->setMatchThreshold(80)
  44. ->setInsertSpaceInReplace(true)
  45. ;
  46. // Calculate the differences using the configuration and get the html diff.
  47. $content = $htmlDiff->build();
  48. // ...
  49. ```
  50. #### Create and Use a HtmlDiffConfig Object
  51. You can also set the configuration by creating an instance of
  52. `Caxy\HtmlDiff\HtmlDiffConfig` and using it when creating a new `HtmlDiff`
  53. object using `HtmlDiff::create`.
  54. This is useful when creating more than one instance of `HtmlDiff`:
  55. ```php
  56. use Caxy\HtmlDiff\HtmlDiff;
  57. use Caxy\HtmlDiff\HtmlDiffConfig;
  58. // ...
  59. $config = new HtmlDiffConfig();
  60. $config
  61. ->setMatchThreshold(95)
  62. ->setInsertSpaceInReplace(true)
  63. ;
  64. // Create an HtmlDiff object with the custom configuration.
  65. $firstHtmlDiff = HtmlDiff::create($oldHtml, $newHtml, $config);
  66. $firstContent = $firstHtmlDiff->build();
  67. $secondHtmlDiff = HtmlDiff::create($oldHtml2, $newHtml2, $config);
  68. $secondHtmlDiff->getConfig()->setMatchThreshold(50);
  69. $secondContent = $secondHtmlDiff->build();
  70. // ...
  71. ```
  72. #### Full Configuration with Defaults:
  73. ```php
  74. $config = new HtmlDiffConfig();
  75. $config
  76. // Percentage required for list items to be considered a match.
  77. ->setMatchThreshold(80)
  78. // Set the encoding of the text to be diffed.
  79. ->setEncoding('UTF-8')
  80. // If true, a space will be added between the <del> and <ins> tags of text that was replaced.
  81. ->setInsertSpaceInReplace(false)
  82. // Option to disable the new Table Diffing feature and treat tables as regular text.
  83. ->setUseTableDiffing(true)
  84. // Pass an instance of \Doctrine\Common\Cache\Cache to cache the calculated diffs.
  85. ->setCacheProvider(null)
  86. // Set the cache directory that HTMLPurifier should use.
  87. ->setPurifierCacheLocation(null)
  88. // Group consecutive deletions and insertions instead of showing a deletion and insertion for each word individually.
  89. ->setGroupDiffs(true)
  90. // List of characters to consider part of a single word when in the middle of text.
  91. ->setSpecialCaseChars(array('.', ',', '(', ')', '\''))
  92. // List of tags to treat as special case tags.
  93. ->setSpecialCaseTags(array('strong', 'b', 'i', 'big', 'small', 'u', 'sub', 'sup', 'strike', 's', 'p'))
  94. // List of tags (and their replacement strings) to be diffed in isolation.
  95. ->setIsolatedDiffTags(array(
  96. 'ol' => '[[REPLACE_ORDERED_LIST]]',
  97. 'ul' => '[[REPLACE_UNORDERED_LIST]]',
  98. 'sub' => '[[REPLACE_SUB_SCRIPT]]',
  99. 'sup' => '[[REPLACE_SUPER_SCRIPT]]',
  100. 'dl' => '[[REPLACE_DEFINITION_LIST]]',
  101. 'table' => '[[REPLACE_TABLE]]',
  102. 'strong' => '[[REPLACE_STRONG]]',
  103. 'b' => '[[REPLACE_B]]',
  104. 'em' => '[[REPLACE_EM]]',
  105. 'i' => '[[REPLACE_I]]',
  106. 'a' => '[[REPLACE_A]]',
  107. ))
  108. ;
  109. ```
  110. ## Contributing
  111. See [CONTRIBUTING][contributing] file.
  112. ## Contributor Code of Conduct
  113. Please note that this project is released with a [Contributor Code of
  114. Conduct][contributor_covenant]. By participating in this project
  115. you agree to abide by its terms. See [CODE_OF_CONDUCT][code_of_conduct] file.
  116. ## Credits
  117. * [rashid2538][] for the port to PHP and the base for our project: [rashid2538/php-htmldiff][upstream]
  118. * [willdurand][] for an excellent post on [open sourcing libraries][].
  119. Much of this documentation is based off of the examples in the post.
  120. Did we miss anyone? If we did, let us know or put in a pull request!
  121. ## License
  122. php-htmldiff is available under [GNU General Public License, version 2][gnu]. See the [LICENSE][license] file for details.
  123. [badge_score]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
  124. [badge_status]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/build-status/master
  125. [badge_coverage]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
  126. [badge_packagist]: https://packagist.org/packages/caxy/php-htmldiff
  127. [badge_resolve]: http://isitmaintained.com/project/caxy/php-htmldiff "Average time to resolve an issue"
  128. [badge_issues]: http://isitmaintained.com/project/caxy/php-htmldiff "Percentage of issues still open"
  129. [upstream]: https://github.com/rashid2538/php-htmldiff
  130. [htmldiffbundle]: https://github.com/caxy/HtmlDiffBundle
  131. [differences]: https://github.com/caxy/php-htmldiff/blob/master/doc/differences.rst
  132. [changelog]: https://github.com/caxy/php-htmldiff/blob/master/CHANGELOG.md
  133. [contributing]: https://github.com/caxy/php-htmldiff/blob/master/CONTRIBUTING.md
  134. [gnu]: http://www.gnu.org/licenses/gpl-2.0.html
  135. [license]: https://github.com/caxy/php-htmldiff/blob/master/LICENSE
  136. [code_of_conduct]: https://github.com/caxy/php-htmldiff/blob/master/CODE_OF_CONDUCT.md
  137. [composer]: http://getcomposer.org/
  138. [contributor_covenant]: http://contributor-covenant.org/
  139. [rashid2538]: https://github.com/rashid2538
  140. [willdurand]: https://github.com/willdurand
  141. [open sourcing libraries]: http://williamdurand.fr/2013/07/04/on-open-sourcing-libraries/