202 lines
7.2 KiB
Markdown
202 lines
7.2 KiB
Markdown
php-htmldiff
|
|
============
|
|
|
|
[][badge_score]
|
|
[][badge_status]
|
|
[][badge_coverage]
|
|
[][badge_packagist]
|
|
[][badge_resolve]
|
|
[][badge_issues]
|
|
|
|
php-htmldiff is a library for comparing two HTML files/snippets and highlighting the differences using simple HTML.
|
|
|
|
This HTML Diff implementation was forked from [rashid2538/php-htmldiff][upstream] and has been modified with new features,
|
|
bug fixes, and enhancements to the original code.
|
|
|
|
For more information on these modifications, read the [differences from rashid2538/php-htmldiff][differences] or view the [CHANGELOG][changelog].
|
|
|
|
## Installation
|
|
|
|
The recommended way to install php-htmldiff is through [Composer][composer].
|
|
Require the [caxy/php-htmldiff][badge_packagist] package by running following command:
|
|
|
|
```sh
|
|
composer require caxy/php-htmldiff
|
|
```
|
|
|
|
This will resolve the latest stable version.
|
|
|
|
Otherwise, install the library and setup the autoloader yourself.
|
|
|
|
### Working with Symfony
|
|
|
|
If you are using Symfony, you can use the [caxy/HtmlDiffBundle][htmldiffbundle] to make life easy!
|
|
|
|
## Usage
|
|
|
|
```php
|
|
use Caxy\HtmlDiff\HtmlDiff;
|
|
|
|
$htmlDiff = new HtmlDiff($oldHtml, $newHtml);
|
|
$content = $htmlDiff->build();
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The configuration for HtmlDiff is contained in the `Caxy\HtmlDiff\HtmlDiffConfig` class.
|
|
|
|
There are two ways to set the configuration:
|
|
|
|
1. [Configure an Existing HtmlDiff Object](#configure-an-existing-htmldiff-object)
|
|
2. [Create and Use a HtmlDiffConfig Object](#create-and-use-a-htmldiffconfig-object)
|
|
|
|
#### Configure an Existing HtmlDiff Object
|
|
|
|
When a new `HtmlDiff` object is created, it creates a `HtmlDiffConfig` object with the default configuration.
|
|
You can change the configuration using setters on the object:
|
|
|
|
```php
|
|
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();
|
|
|
|
// ...
|
|
|
|
```
|
|
|
|
#### Create and Use a HtmlDiffConfig Object
|
|
|
|
You can also set the configuration by creating an instance of
|
|
`Caxy\HtmlDiff\HtmlDiffConfig` and using it when creating a new `HtmlDiff`
|
|
object using `HtmlDiff::create`.
|
|
|
|
This is useful when creating more than one instance of `HtmlDiff`:
|
|
|
|
```php
|
|
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();
|
|
|
|
// ...
|
|
```
|
|
|
|
#### Full Configuration with Defaults:
|
|
|
|
```php
|
|
|
|
$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)
|
|
|
|
// 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 to treat as special case tags.
|
|
->setSpecialCaseTags(array('strong', 'b', 'i', 'big', 'small', 'u', 'sub', 'sup', 'strike', 's', 'p'))
|
|
|
|
// 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]]',
|
|
))
|
|
;
|
|
|
|
```
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING][contributing] file.
|
|
|
|
## Contributor Code of Conduct
|
|
|
|
Please note that this project is released with a [Contributor Code of
|
|
Conduct][contributor_covenant]. By participating in this project
|
|
you agree to abide by its terms. See [CODE_OF_CONDUCT][code_of_conduct] file.
|
|
|
|
## Credits
|
|
|
|
* [rashid2538][] for the port to PHP and the base for our project: [rashid2538/php-htmldiff][upstream]
|
|
* [willdurand][] for an excellent post on [open sourcing libraries][].
|
|
Much of this documentation is based off of the examples in the post.
|
|
|
|
Did we miss anyone? If we did, let us know or put in a pull request!
|
|
|
|
## License
|
|
|
|
php-htmldiff is available under [GNU General Public License, version 2][gnu]. See the [LICENSE][license] file for details.
|
|
|
|
[badge_score]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
|
|
[badge_status]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/build-status/master
|
|
[badge_coverage]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
|
|
[badge_packagist]: https://packagist.org/packages/caxy/php-htmldiff
|
|
[badge_resolve]: http://isitmaintained.com/project/caxy/php-htmldiff "Average time to resolve an issue"
|
|
[badge_issues]: http://isitmaintained.com/project/caxy/php-htmldiff "Percentage of issues still open"
|
|
[upstream]: https://github.com/rashid2538/php-htmldiff
|
|
[htmldiffbundle]: https://github.com/caxy/HtmlDiffBundle
|
|
[differences]: https://github.com/caxy/php-htmldiff/blob/master/doc/differences.rst
|
|
[changelog]: https://github.com/caxy/php-htmldiff/blob/master/CHANGELOG.md
|
|
[contributing]: https://github.com/caxy/php-htmldiff/blob/master/CONTRIBUTING.md
|
|
[gnu]: http://www.gnu.org/licenses/gpl-2.0.html
|
|
[license]: https://github.com/caxy/php-htmldiff/blob/master/LICENSE
|
|
[code_of_conduct]: https://github.com/caxy/php-htmldiff/blob/master/CODE_OF_CONDUCT.md
|
|
[composer]: http://getcomposer.org/
|
|
[contributor_covenant]: http://contributor-covenant.org/
|
|
[rashid2538]: https://github.com/rashid2538
|
|
[willdurand]: https://github.com/willdurand
|
|
[open sourcing libraries]: http://williamdurand.fr/2013/07/04/on-open-sourcing-libraries/
|