Skip to content

Commit eec5835

Browse files
jschroed91jschroed91
committed
Merge pull request #34 from caxy/documentation/updating-readme
Update the README and add additional documentation
2 parents a348aa3 + d2761bb commit eec5835

File tree

4 files changed

+391
-62
lines changed

4 files changed

+391
-62
lines changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at [email protected]. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at [http://contributor-covenant.org/version/1/4][version]
72+
73+
[homepage]: http://contributor-covenant.org
74+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
Contributing
2+
============
3+
4+
First of all, **thank you** for contributing, **you are awesome**!
5+
6+
Here are a few rules to follow in order to ease code reviews, and discussions before
7+
maintainers accept and merge your work.
8+
9+
You MUST follow the [PSR-1](http://www.php-fig.org/psr/1/) and
10+
[PSR-2](http://www.php-fig.org/psr/2/). If you don't know about any of them, you
11+
should really read the recommendations. Can't wait? Use the [PHP-CS-Fixer
12+
tool](http://cs.sensiolabs.org/).
13+
14+
You MUST run the test suite.
15+
16+
You MUST write (or update) unit tests.
17+
18+
You SHOULD write documentation.
19+
20+
Please, write [commit messages that make
21+
sense](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
22+
and [rebase your branch](http://git-scm.com/book/en/Git-Branching-Rebasing)
23+
before submitting your Pull Request.
24+
25+
One may ask you to [squash your
26+
commits](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html)
27+
too. This is used to "clean" your Pull Request before merging it (we don't want
28+
commits such as `fix tests`, `fix 2`, `fix 3`, etc.).
29+
30+
Also, while creating your Pull Request on GitHub, you MUST write a description
31+
which gives the context and/or explains why you are creating it.
32+
33+
Thank you!

‎README.md‎

Lines changed: 168 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,197 @@
1-
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master)
2-
[![Build Status](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/build.png?b=master)](https://scrutinizer-ci.com/g/caxy/php-htmldiff/build-status/master)
3-
[![Code Coverage](https://scrutinizer-ci.com/g/caxy/php-htmldiff/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master)
4-
[![Packagist](https://img.shields.io/packagist/dt/caxy/php-htmldiff.svg)](https://packagist.org/packages/caxy/php-htmldiff)
5-
[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/caxy/php-htmldiff.svg)](http://isitmaintained.com/project/caxy/php-htmldiff "Average time to resolve an issue")
6-
[![Percentage of issues still open](http://isitmaintained.com/badge/open/caxy/php-htmldiff.svg)](http://isitmaintained.com/project/caxy/php-htmldiff "Percentage of issues still open")
7-
81
php-htmldiff
9-
=======
10-
*A library for comparing two HTML files/snippets and highlighting the differences using simple HTML.*
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!
1134

12-
This HTML Diff implementation is a PHP port of the ruby implementation found at https://github.com/myobie/htmldiff.
35+
## Usage
1336

14-
This is also available in C# at https://github.com/Rohland/htmldiff.net.
37+
```php
38+
use Caxy\HtmlDiff\HtmlDiff;
1539

16-
License
17-
-------
18-
php-htmldiff is available under [GNU General Public License, version 2] (http://www.gnu.org/licenses/gpl-2.0.html).
40+
$htmlDiff = new HtmlDiff($oldHtml, $newHtml);
41+
$content = $htmlDiff->build();
42+
```
1943

20-
Differences from rashid2538/php-htmldiff
21-
========================================
22-
## Code Styling and Clean-up
23-
* Added namespaces, split up classes to their own files, some code styling changes
44+
## Configuration
2445

25-
## Enhancements
26-
* Allow the specialCaseOpeningTags and specialCaseClosingTags properties to be modified by passing an array into the constructor or using set/add/remove functions
27-
* Updated the demo to accept input and diff via AJAX
28-
* Added static properties for the default config variables
46+
The configuration for HtmlDiff is contained in the `Caxy\HtmlDiff\HtmlDiffConfig` class.
2947

30-
## Bug Fixes
31-
* Fixed an index out of range bug (may have been fixed on the original repo since): https://github.com/caxy/php-htmldiff/commit/c9ba1fab6777cd47427477f8d747293bb01ef1e8
32-
* Check for empty oldText or newText before processing del or ins in processReplaceOperation function
48+
There are two ways to set the configuration:
49+
1. [Configure an Existing HtmlDiff Object](#configure-an-existing-htmldiff-object)
50+
2. [Create and Use an HtmlDiffConfig Object](#create-and-use-an-htmldiffconfig-object)
3351

34-
## New Features
35-
#### Isolated Diffing of certain HTML elements
36-
This is the one of the largest changes from the original repository.
52+
#### Configure an Existing HtmlDiff Object
3753

38-
See the release notes for tag 0.0.6 for more information: https://github.com/caxy/php-htmldiff/releases/tag/0.0.6
54+
When a new `HtmlDiff` object is created, it creates a `HtmlDiffConfig` object with the default configuration.
55+
You can change the configuration using setters on the object:
3956

40-
#### List Diffing
41-
This is the latest new feature (as of last week-ish), and may need some tweaks still. It is similar to the Isolated Diffing feature, but specifically for HTML lists.
57+
```php
58+
use Caxy\HtmlDiff\HtmlDiff;
4259

43-
More information is to come on this, and there will definitely be some tweaks and configuration options added for this feature. Currently there is no easy way to enable/disable the feature, so if you're having issues with it I suggest using the 0.0.6 or earlier release.
60+
// ...
4461

45-
#### New option to group together diffed words by not matching on whitespace-only. Option is enabled by default.
46-
This was a specific requirement for an application we use this library for. The original library would replace single words at a time, but enabling this feature will group replacements instead. See example below.
62+
$htmlDiff = new HtmlDiff($oldHtml, $newHtml);
4763

48-
Old Text
49-
> testing some text here and there
64+
// Set some of the configuration options.
65+
$htmlDiff->getConfig()
66+
->setMatchThreshold(80)
67+
->setInsertSpaceInReplace(true)
68+
;
5069

51-
New Text
52-
> testing other words here and there
70+
// Calculate the differences using the configuration and get the html diff.
71+
$content = $htmlDiff->build();
5372

54-
With $groupDiffs = false (original functionality)
55-
> testing <del>some</del><ins>other</ins> <del>text</del><ins>words</ins> here and there
73+
// ...
5674

57-
With $groupDiffs = true (new feature)
58-
> testing <del>some text</del><ins>other words</ins> here and there
75+
```
5976

60-
#### Change diffing to strike through entire words/numbers if they contain periods or commas within the word
61-
This change introduced a new property `$specialCaseChars`, which defaults to the following characters: `.` `,` `(` `)` `'`
77+
#### Create and Use an HtmlDiffConfig Object
6278

63-
This feature can be "disabled" by simply setting the $specialCaseChars to an empty array i.e. `$diff->setSpecialCaseChars(array())`
79+
You can also set the configuration by creating an instance of
80+
`Caxy\HtmlDiff\HtmlDiffConfig` and using it when creating a new `HtmlDiff`
81+
object using `HtmlDiff::create`.
6482

65-
In the original library, special characters are treated as their own "words" even if they are in the middle of a word. This causes weird things to happen when diffing numbers that have a comma or a period in the middle of the number.
83+
This is useful when creating more than one instance of `HtmlDiff`:
6684

67-
For example, diffing `10,000.50` against `11,100.75` gives you:
85+
```php
86+
use Caxy\HtmlDiff\HtmlDiff;
87+
use Caxy\HtmlDiff\HtmlDiffConfig;
6888

69-
Original Functionality:
70-
> <del class="diffmod">10</del><ins class="diffmod">11</ins>,<del class="diffmod">000</del><ins class="diffmod">100</ins>.<del class="diffmod">50</del><ins class="diffmod">75</ins>
89+
// ...
7190

72-
This is very difficult to read, so the new feature allows you to add `.` and `,` to the $specialCaseChars array in order to get output that looks like:
73-
> <del class="diffmod">10,000.50</del><ins class="diffmod">11,100.75</ins>
91+
$config = new HtmlDiffConfig();
92+
$config
93+
->setMatchThreshold(95)
94+
->setInsertSpaceInReplace(true)
95+
;
7496

75-
Note: It will *not* treat the specialCaseChars as part of the word if it is at the beginning or end of the word, so normal periods or commas at the end of words will still be diffed like the original.
97+
// Create an HtmlDiff object with the custom configuration.
98+
$firstHtmlDiff = HtmlDiff::create($oldHtml, $newHtml, $config);
99+
$firstContent = $firstHtmlDiff->build();
76100

77-
#### Added option to insert a space between `<del>` and `<ins>` tags. Disabled by default.
78-
This was a requirement for one our applications that uses this library.
101+
$secondHtmlDiff = HtmlDiff::create($oldHtml2, $newHtml2, $config);
102+
$secondHtmlDiff->getConfig()->setMatchThreshold(50);
79103

80-
New property `$insertSpaceInReplace` was added, and setting it to true will simply add a space between the `<del>` and `<ins>` tags in replace operations, which was requested for easier reading.
104+
$secondContent = $secondHtmlDiff->build();
81105

82-
Enable it by calling `$diff->setInsertSpaceInReplace(true);`
106+
// ...
107+
```
83108

84-
Original Functionality
85-
> <del>Old</del><ins>New</ins>
109+
#### Full Configuration with Defaults:
86110

87-
New Functionality
88-
> <del>Old</del> <ins>New</ins>
111+
```php
89112

90-
## Upcoming Features (someday)
91-
* Table Diffing (similar to the list diffing updates) - this feature was started a while back, but put on hold.
113+
$config = new HtmlDiffConfig();
114+
$config
115+
// Percentage required for list items to be considered a match.
116+
->setMatchThreshold(80)
117+
118+
// Set the encoding of the text to be diffed.
119+
->setEncoding('UTF-8')
120+
121+
// If true, a space will be added between the <del> and <ins> tags of text that was replaced.
122+
->setInsertSpaceInReplace(false)
123+
124+
// Option to disable the new Table Diffing feature and treat tables as regular text.
125+
->setUseTableDiffing(true)
126+
127+
// Pass an instance of \Doctrine\Common\Cache\Cache to cache the calculated diffs.
128+
->setCacheProvider(null)
129+
130+
// Group consecutive deletions and insertions instead of showing a deletion and insertion for each word individually.
131+
->setGroupDiffs(true)
132+
133+
// List of characters to consider part of a single word when in the middle of text.
134+
->setSpecialCaseChars(array('.', ',', '(', ')', '\''))
135+
136+
// List of tags to treat as special case tags.
137+
->setSpecialCaseTags(array('strong', 'b', 'i', 'big', 'small', 'u', 'sub', 'sup', 'strike', 's', 'p'))
138+
139+
// List of tags (and their replacement strings) to be diffed in isolation.
140+
->setIsolatedDiffTags(array(
141+
'ol' => '[[REPLACE_ORDERED_LIST]]',
142+
'ul' => '[[REPLACE_UNORDERED_LIST]]',
143+
'sub' => '[[REPLACE_SUB_SCRIPT]]',
144+
'sup' => '[[REPLACE_SUPER_SCRIPT]]',
145+
'dl' => '[[REPLACE_DEFINITION_LIST]]',
146+
'table' => '[[REPLACE_TABLE]]',
147+
'strong' => '[[REPLACE_STRONG]]',
148+
'b' => '[[REPLACE_B]]',
149+
'em' => '[[REPLACE_EM]]',
150+
'i' => '[[REPLACE_I]]',
151+
'a' => '[[REPLACE_A]]',
152+
))
153+
;
154+
155+
```
156+
157+
## Contributing
158+
159+
See [CONTRIBUTING][contributing] file.
160+
161+
## Contributor Code of Conduct
162+
163+
Please note that this project is released with a [Contributor Code of
164+
Conduct][contributor_covenant]. By participating in this project
165+
you agree to abide by its terms. See [CODE_OF_CONDUCT][code_of_conduct] file.
166+
167+
## Credits
168+
169+
* [rashid2538][] for the port to PHP and the base for our project: [rashid2538/php-htmldiff][upstream]
170+
* [willdurand][] for an excellent post on [open sourcing libraries][].
171+
Much of this documentation is based off of the examples in the post.
172+
173+
Did we miss anyone? If we did, let us know or put in a pull request!
174+
175+
## License
176+
177+
php-htmldiff is available under [GNU General Public License, version 2][gnu]. See the [LICENSE][license] file for details.
178+
179+
[badge_score]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
180+
[badge_status]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/build-status/master
181+
[badge_coverage]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
182+
[badge_packagist]: https://packagist.org/packages/caxy/php-htmldiff
183+
[badge_resolve]: http://isitmaintained.com/project/caxy/php-htmldiff "Average time to resolve an issue"
184+
[badge_issues]: http://isitmaintained.com/project/caxy/php-htmldiff "Percentage of issues still open"
185+
[upstream]: https://github.com/rashid2538/php-htmldiff
186+
[htmldiffbundle]: https://github.com/caxy/HtmlDiffBundle
187+
[differences]: https://github.com/caxy/php-htmldiff/blob/master/doc/differences.rst
188+
[changelog]: https://github.com/caxy/php-htmldiff/blob/master/CHANGELOG.md
189+
[contributing]: https://github.com/caxy/php-htmldiff/blob/master/CONTRIBUTING.md
190+
[gnu]: http://www.gnu.org/licenses/gpl-2.0.html
191+
[license]: https://github.com/caxy/php-htmldiff/blob/master/LICENSE
192+
[code_of_conduct]: https://github.com/caxy/php-htmldiff/blob/master/CODE_OF_CONDUCT.md
193+
[composer]: http://getcomposer.org/
194+
[contributor_covenant]: http://contributor-covenant.org/
195+
[rashid2538]: https://github.com/rashid2538
196+
[willdurand]: https://github.com/willdurand
197+
[open sourcing libraries]: http://williamdurand.fr/2013/07/04/on-open-sourcing-libraries/

0 commit comments

Comments
 (0)