Skip to content

Commit 95dbb29

Browse files
jschroed91jschroed91
committed
Updating the readme with installation and usage information
1 parent a348aa3 commit 95dbb29

File tree

4 files changed

+285
-63
lines changed

4 files changed

+285
-63
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: 62 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,90 @@
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.*
11-
12-
This HTML Diff implementation is a PHP port of the ruby implementation found at https://github.com/myobie/htmldiff.
2+
============
133

14-
This is also available in C# at https://github.com/Rohland/htmldiff.net.
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]
1510

16-
License
17-
-------
18-
php-htmldiff is available under [GNU General Public License, version 2] (http://www.gnu.org/licenses/gpl-2.0.html).
11+
php-htmldiff is a library for comparing two HTML files/snippets and highlighting the differences using simple HTML.
1912

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
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.
2415

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
16+
For more information on these modifications, read the [differences from rashid2538/php-htmldiff][differences] or view the [CHANGELOG][changelog].
2917

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
18+
## Installation
3319

34-
## New Features
35-
#### Isolated Diffing of certain HTML elements
36-
This is the one of the largest changes from the original repository.
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:
3722

38-
See the release notes for tag 0.0.6 for more information: https://github.com/caxy/php-htmldiff/releases/tag/0.0.6
23+
```sh
24+
composer require caxy/php-htmldiff
25+
```
3926

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.
27+
This will resolve the latest stable version.
4228

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.
29+
Otherwise, install the library and setup the autoloader yourself.
4430

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.
31+
### Working with Symfony
4732

48-
Old Text
49-
> testing some text here and there
33+
If you are using Symfony, you can use the [caxy/HtmlDiffBundle][htmldiffbundle] to make life easy!
5034

51-
New Text
52-
> testing other words here and there
35+
## Usage
5336

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

57-
With $groupDiffs = true (new feature)
58-
> testing <del>some text</del><ins>other words</ins> here and there
39+
```php
40+
use Caxy\HtmlDiff\HtmlDiff;
5941

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: `.` `,` `(` `)` `'`
42+
$htmlDiff = new HtmlDiff($oldHtml, $newHtml);
43+
$content = $htmlDiff->build();
44+
```
6245

63-
This feature can be "disabled" by simply setting the $specialCaseChars to an empty array i.e. `$diff->setSpecialCaseChars(array())`
46+
## Configuration
6447

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.
48+
WIP
6649

67-
For example, diffing `10,000.50` against `11,100.75` gives you:
50+
## Contributing
6851

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>
52+
See [CONTRIBUTING][contributing] file.
7153

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>
54+
## Contributor Code of Conduct
7455

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.
56+
Please note that this project is released with a [Contributor Code of
57+
Conduct][contributor_covenant]. By participating in this project
58+
you agree to abide by its terms. See [CODE_OF_CONDUCT][code_of_conduct] file.
7659

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.
60+
## Credits
7961

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.
62+
* [rashid2538][] for the port to PHP and the base for our project: [rashid2538/php-htmldiff][upstream]
63+
* [willdurand][] for an excellent post on [open sourcing libraries][].
64+
Much of this documentation is based off of the examples in the post.
8165

82-
Enable it by calling `$diff->setInsertSpaceInReplace(true);`
66+
Did we miss anyone? If we did, let us know or put in a pull request!
8367

84-
Original Functionality
85-
> <del>Old</del><ins>New</ins>
68+
## License
8669

87-
New Functionality
88-
> <del>Old</del> <ins>New</ins>
70+
php-htmldiff is available under [GNU General Public License, version 2][gnu]. See the [LICENSE][license] file for details.
8971

90-
## Upcoming Features (someday)
91-
* Table Diffing (similar to the list diffing updates) - this feature was started a while back, but put on hold.
72+
[badge_score]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
73+
[badge_status]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/build-status/master
74+
[badge_coverage]: https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master
75+
[badge_packagist]: https://packagist.org/packages/caxy/php-htmldiff
76+
[badge_resolve]: http://isitmaintained.com/project/caxy/php-htmldiff "Average time to resolve an issue"
77+
[badge_issues]: http://isitmaintained.com/project/caxy/php-htmldiff "Percentage of issues still open"
78+
[upstream]: https://github.com/rashid2538/php-htmldiff
79+
[htmldiffbundle]: https://github.com/caxy/HtmlDiffBundle
80+
[differences]: https://github.com/caxy/php-htmldiff/blob/master/doc/differences.rst
81+
[changelog]: https://github.com/caxy/php-htmldiff/blob/master/CHANGELOG.md
82+
[contributing]: https://github.com/caxy/php-htmldiff/blob/master/CONTRIBUTING.md
83+
[gnu]: http://www.gnu.org/licenses/gpl-2.0.html
84+
[license]: https://github.com/caxy/php-htmldiff/blob/master/LICENSE
85+
[code_of_conduct]: https://github.com/caxy/php-htmldiff/blob/master/CODE_OF_CONDUCT.md
86+
[composer]: http://getcomposer.org/
87+
[contributor_covenant]: http://contributor-covenant.org/
88+
[rashid2538]: https://github.com/rashid2538
89+
[willdurand]: https://github.com/willdurand
90+
[open sourcing libraries]: http://williamdurand.fr/2013/07/04/on-open-sourcing-libraries/

‎doc/differences.rst‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
Differences from rashid2538/php-htmldiff
2+
========================================
3+
4+
.. contents:: Table of Contents
5+
6+
Code Styling and Clean-up
7+
-------------------------
8+
9+
* Added namespaces, split up classes to their own files, some code styling changes
10+
11+
Enhancements
12+
------------
13+
14+
* Allow the specialCaseOpeningTags and specialCaseClosingTags properties to be modified by passing an array into the constructor or using set/add/remove functions
15+
* Updated the demo to accept input and diff via AJAX
16+
* Added static properties for the default config variables
17+
18+
Bug Fixes
19+
---------
20+
21+
* Fixed an index out of range bug (may have been fixed on the original repo since): c9ba1fa_
22+
* Check for empty oldText or newText before processing del or ins in processReplaceOperation function
23+
24+
New Features
25+
------------
26+
27+
Isolated Diffing of certain HTML elements
28+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
29+
30+
This is the one of the largest changes from the original repository.
31+
32+
For more information, see the release notes for tag `0.0.6`_
33+
34+
List Diffing
35+
^^^^^^^^^^^^
36+
37+
Similar to the Isolated Diffing feature, but specifically for HTML lists.
38+
39+
More information is to come on this, and there will definitely be some tweaks and configuration options added for this
40+
feature. Currently there is no easy way to enable/disable the feature, so if you're having issues with it I suggest
41+
using the `0.0.6`_ or earlier release.
42+
43+
Table Diffing
44+
^^^^^^^^^^^^^
45+
46+
Similar to the Isolated Diffing and List Diffing features, but specifically for HTML tables.
47+
48+
More information to come on this soon.
49+
50+
New option to group together diffed words by not matching on whitespace-only. Option is enabled by default.
51+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52+
53+
This was a specific requirement for an application we use this library for. The original library would replace
54+
single words at a time, but enabling this feature will group replacements instead. See example below.
55+
56+
Old Text::
57+
58+
testing some text here and there
59+
60+
New Text::
61+
62+
testing other words here and there
63+
64+
With $groupDiffs = false (original functionality)::
65+
66+
testing <del>some</del><ins>other</ins> <del>text</del><ins>words</ins> here and there
67+
68+
With $groupDiffs = true (new feature)::
69+
70+
testing <del>some text</del><ins>other words</ins> here and there
71+
72+
Change diffing to strike through entire words/numbers if they contain periods or commas within the word
73+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
74+
75+
This change introduced a new property ``$specialCaseChars``, which defaults to the following characters: ``.`` ``,`` ``(`` ``)`` ``'``
76+
77+
This feature can be "disabled" by simply setting the $specialCaseChars to an empty array i.e. ``$diff->setSpecialCaseChars(array())``
78+
79+
In the original library, special characters are treated as their own "words" even if they are in the middle of a word.
80+
This causes weird things to happen when diffing numbers that have a comma or a period in the middle of the number.
81+
82+
For example, diffing ``10,000.50`` against ``11,100.75`` gives you:
83+
84+
Original Functionality::
85+
86+
<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>
87+
88+
This is very difficult to read, so the new feature allows you to add ``.`` and ``,`` to the ``$specialCaseChars`` array in order
89+
to get output that looks like::
90+
91+
<del class="diffmod">10,000.50</del><ins class="diffmod">11,100.75</ins>
92+
93+
Note: It will *not* treat the specialCaseChars as part of the word if it is at the beginning or end of the word,
94+
so normal periods or commas at the end of words will still be diffed like the original.
95+
96+
Added option to insert a space between ``<del>`` and ``<ins>`` tags. Disabled by default.
97+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98+
99+
This was a requirement for one our applications that uses this library.
100+
101+
New property ``$insertSpaceInReplace`` was added, and setting it to true will simply add a space between
102+
the ``<del>`` and ``<ins>`` tags in replace operations, which was requested for easier reading.
103+
104+
Enable it by calling ``$diff->setInsertSpaceInReplace(true);``
105+
106+
Original Functionality::
107+
108+
<del>Old</del><ins>New</ins>
109+
110+
New Functionality::
111+
112+
<del>Old</del> <ins>New</ins>
113+
114+
.. _c9ba1fa: https://github.com/caxy/php-htmldiff/commit/c9ba1fab6777cd47427477f8d747293bb01ef1e8
115+
.. _0.0.6: https://github.com/caxy/php-htmldiff/releases/tag/0.0.6
116+

0 commit comments

Comments
 (0)