-
Notifications
You must be signed in to change notification settings - Fork 52
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updating the readme with installation and usage information
- Loading branch information
1 parent
a348aa3
commit 95dbb29
Showing
4 changed files
with
285 additions
and
63 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| # Contributor Covenant Code of Conduct | ||
|
|
||
| ## Our Pledge | ||
|
|
||
| In the interest of fostering an open and welcoming environment, we as | ||
| contributors and maintainers pledge to making participation in our project and | ||
| our community a harassment-free experience for everyone, regardless of age, body | ||
| size, disability, ethnicity, gender identity and expression, level of experience, | ||
| nationality, personal appearance, race, religion, or sexual identity and | ||
| orientation. | ||
|
|
||
| ## Our Standards | ||
|
|
||
| Examples of behavior that contributes to creating a positive environment | ||
| include: | ||
|
|
||
| * Using welcoming and inclusive language | ||
| * Being respectful of differing viewpoints and experiences | ||
| * Gracefully accepting constructive criticism | ||
| * Focusing on what is best for the community | ||
| * Showing empathy towards other community members | ||
|
|
||
| Examples of unacceptable behavior by participants include: | ||
|
|
||
| * The use of sexualized language or imagery and unwelcome sexual attention or | ||
| advances | ||
| * Trolling, insulting/derogatory comments, and personal or political attacks | ||
| * Public or private harassment | ||
| * Publishing others' private information, such as a physical or electronic | ||
| address, without explicit permission | ||
| * Other conduct which could reasonably be considered inappropriate in a | ||
| professional setting | ||
|
|
||
| ## Our Responsibilities | ||
|
|
||
| Project maintainers are responsible for clarifying the standards of acceptable | ||
| behavior and are expected to take appropriate and fair corrective action in | ||
| response to any instances of unacceptable behavior. | ||
|
|
||
| Project maintainers have the right and responsibility to remove, edit, or | ||
| reject comments, commits, code, wiki edits, issues, and other contributions | ||
| that are not aligned to this Code of Conduct, or to ban temporarily or | ||
| permanently any contributor for other behaviors that they deem inappropriate, | ||
| threatening, offensive, or harmful. | ||
|
|
||
| ## Scope | ||
|
|
||
| This Code of Conduct applies both within project spaces and in public spaces | ||
| when an individual is representing the project or its community. Examples of | ||
| representing a project or community include using an official project e-mail | ||
| address, posting via an official social media account, or acting as an appointed | ||
| representative at an online or offline event. Representation of a project may be | ||
| further defined and clarified by project maintainers. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| Instances of abusive, harassing, or otherwise unacceptable behavior may be | ||
| reported by contacting the project team at [email protected]. All | ||
| complaints will be reviewed and investigated and will result in a response that | ||
| is deemed necessary and appropriate to the circumstances. The project team is | ||
| obligated to maintain confidentiality with regard to the reporter of an incident. | ||
| Further details of specific enforcement policies may be posted separately. | ||
|
|
||
| Project maintainers who do not follow or enforce the Code of Conduct in good | ||
| faith may face temporary or permanent repercussions as determined by other | ||
| members of the project's leadership. | ||
|
|
||
| ## Attribution | ||
|
|
||
| This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, | ||
| available at [http://contributor-covenant.org/version/1/4][version] | ||
|
|
||
| [homepage]: http://contributor-covenant.org | ||
| [version]: http://contributor-covenant.org/version/1/4/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| Contributing | ||
| ============ | ||
|
|
||
| First of all, **thank you** for contributing, **you are awesome**! | ||
|
|
||
| Here are a few rules to follow in order to ease code reviews, and discussions before | ||
| maintainers accept and merge your work. | ||
|
|
||
| You MUST follow the [PSR-1](http://www.php-fig.org/psr/1/) and | ||
| [PSR-2](http://www.php-fig.org/psr/2/). If you don't know about any of them, you | ||
| should really read the recommendations. Can't wait? Use the [PHP-CS-Fixer | ||
| tool](http://cs.sensiolabs.org/). | ||
|
|
||
| You MUST run the test suite. | ||
|
|
||
| You MUST write (or update) unit tests. | ||
|
|
||
| You SHOULD write documentation. | ||
|
|
||
| Please, write [commit messages that make | ||
| sense](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), | ||
| and [rebase your branch](http://git-scm.com/book/en/Git-Branching-Rebasing) | ||
| before submitting your Pull Request. | ||
|
|
||
| One may ask you to [squash your | ||
| commits](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) | ||
| too. This is used to "clean" your Pull Request before merging it (we don't want | ||
| commits such as `fix tests`, `fix 2`, `fix 3`, etc.). | ||
|
|
||
| Also, while creating your Pull Request on GitHub, you MUST write a description | ||
| which gives the context and/or explains why you are creating it. | ||
|
|
||
| Thank you! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,91 +1,90 @@ | ||
| [](https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master) | ||
| [](https://scrutinizer-ci.com/g/caxy/php-htmldiff/build-status/master) | ||
| [](https://scrutinizer-ci.com/g/caxy/php-htmldiff/?branch=master) | ||
| [](https://packagist.org/packages/caxy/php-htmldiff) | ||
| [](http://isitmaintained.com/project/caxy/php-htmldiff "Average time to resolve an issue") | ||
| [](http://isitmaintained.com/project/caxy/php-htmldiff "Percentage of issues still open") | ||
|
|
||
| php-htmldiff | ||
| ======= | ||
| *A library for comparing two HTML files/snippets and highlighting the differences using simple HTML.* | ||
|
|
||
| This HTML Diff implementation is a PHP port of the ruby implementation found at https://github.com/myobie/htmldiff. | ||
| ============ | ||
|
|
||
| This is also available in C# at https://github.com/Rohland/htmldiff.net. | ||
| [][badge_score] | ||
| [][badge_status] | ||
| [][badge_coverage] | ||
| [][badge_packagist] | ||
| [][badge_resolve] | ||
| [][badge_issues] | ||
|
|
||
| License | ||
| ------- | ||
| php-htmldiff is available under [GNU General Public License, version 2] (http://www.gnu.org/licenses/gpl-2.0.html). | ||
| php-htmldiff is a library for comparing two HTML files/snippets and highlighting the differences using simple HTML. | ||
|
|
||
| Differences from rashid2538/php-htmldiff | ||
| ======================================== | ||
| ## Code Styling and Clean-up | ||
| * Added namespaces, split up classes to their own files, some code styling changes | ||
| 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. | ||
|
|
||
| ## Enhancements | ||
| * Allow the specialCaseOpeningTags and specialCaseClosingTags properties to be modified by passing an array into the constructor or using set/add/remove functions | ||
| * Updated the demo to accept input and diff via AJAX | ||
| * Added static properties for the default config variables | ||
| For more information on these modifications, read the [differences from rashid2538/php-htmldiff][differences] or view the [CHANGELOG][changelog]. | ||
|
|
||
| ## Bug Fixes | ||
| * Fixed an index out of range bug (may have been fixed on the original repo since): https://github.com/caxy/php-htmldiff/commit/c9ba1fab6777cd47427477f8d747293bb01ef1e8 | ||
| * Check for empty oldText or newText before processing del or ins in processReplaceOperation function | ||
| ## Installation | ||
|
|
||
| ## New Features | ||
| #### Isolated Diffing of certain HTML elements | ||
| This is the one of the largest changes from the original repository. | ||
| The recommended way to install php-htmldiff is through [Composer][composer]. | ||
| Require the [caxy/php-htmldiff][badge_packagist] package by running following command: | ||
|
|
||
| See the release notes for tag 0.0.6 for more information: https://github.com/caxy/php-htmldiff/releases/tag/0.0.6 | ||
| ```sh | ||
| composer require caxy/php-htmldiff | ||
| ``` | ||
|
|
||
| #### List Diffing | ||
| 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. | ||
| This will resolve the latest stable version. | ||
|
|
||
| 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. | ||
| Otherwise, install the library and setup the autoloader yourself. | ||
|
|
||
| #### New option to group together diffed words by not matching on whitespace-only. Option is enabled by default. | ||
| 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. | ||
| ### Working with Symfony | ||
|
|
||
| Old Text | ||
| > testing some text here and there | ||
| If you are using Symfony, you can use the [caxy/HtmlDiffBundle][htmldiffbundle] to make life easy! | ||
|
|
||
| New Text | ||
| > testing other words here and there | ||
| ## Usage | ||
|
|
||
| With $groupDiffs = false (original functionality) | ||
| > testing <del>some</del><ins>other</ins> <del>text</del><ins>words</ins> here and there | ||
| (WIP) | ||
|
|
||
| With $groupDiffs = true (new feature) | ||
| > testing <del>some text</del><ins>other words</ins> here and there | ||
| ```php | ||
| use Caxy\HtmlDiff\HtmlDiff; | ||
|
|
||
| #### Change diffing to strike through entire words/numbers if they contain periods or commas within the word | ||
| This change introduced a new property `$specialCaseChars`, which defaults to the following characters: `.` `,` `(` `)` `'` | ||
| $htmlDiff = new HtmlDiff($oldHtml, $newHtml); | ||
| $content = $htmlDiff->build(); | ||
| ``` | ||
|
|
||
| This feature can be "disabled" by simply setting the $specialCaseChars to an empty array i.e. `$diff->setSpecialCaseChars(array())` | ||
| ## Configuration | ||
|
|
||
| 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. | ||
| WIP | ||
|
|
||
| For example, diffing `10,000.50` against `11,100.75` gives you: | ||
| ## Contributing | ||
|
|
||
| Original Functionality: | ||
| > <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> | ||
| See [CONTRIBUTING][contributing] file. | ||
|
|
||
| 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: | ||
| > <del class="diffmod">10,000.50</del><ins class="diffmod">11,100.75</ins> | ||
| ## Contributor Code of Conduct | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| #### Added option to insert a space between `<del>` and `<ins>` tags. Disabled by default. | ||
| This was a requirement for one our applications that uses this library. | ||
| ## Credits | ||
|
|
||
| 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. | ||
| * [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. | ||
|
|
||
| Enable it by calling `$diff->setInsertSpaceInReplace(true);` | ||
| Did we miss anyone? If we did, let us know or put in a pull request! | ||
|
|
||
| Original Functionality | ||
| > <del>Old</del><ins>New</ins> | ||
| ## License | ||
|
|
||
| New Functionality | ||
| > <del>Old</del> <ins>New</ins> | ||
| php-htmldiff is available under [GNU General Public License, version 2][gnu]. See the [LICENSE][license] file for details. | ||
|
|
||
| ## Upcoming Features (someday) | ||
| * Table Diffing (similar to the list diffing updates) - this feature was started a while back, but put on hold. | ||
| [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/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| Differences from rashid2538/php-htmldiff | ||
| ======================================== | ||
|
|
||
| .. contents:: Table of Contents | ||
|
|
||
| Code Styling and Clean-up | ||
| ------------------------- | ||
|
|
||
| * Added namespaces, split up classes to their own files, some code styling changes | ||
|
|
||
| Enhancements | ||
| ------------ | ||
|
|
||
| * Allow the specialCaseOpeningTags and specialCaseClosingTags properties to be modified by passing an array into the constructor or using set/add/remove functions | ||
| * Updated the demo to accept input and diff via AJAX | ||
| * Added static properties for the default config variables | ||
|
|
||
| Bug Fixes | ||
| --------- | ||
|
|
||
| * Fixed an index out of range bug (may have been fixed on the original repo since): c9ba1fa_ | ||
| * Check for empty oldText or newText before processing del or ins in processReplaceOperation function | ||
|
|
||
| New Features | ||
| ------------ | ||
|
|
||
| Isolated Diffing of certain HTML elements | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| This is the one of the largest changes from the original repository. | ||
|
|
||
| For more information, see the release notes for tag `0.0.6`_ | ||
|
|
||
| List Diffing | ||
| ^^^^^^^^^^^^ | ||
|
|
||
| Similar to the Isolated Diffing feature, but specifically for HTML lists. | ||
|
|
||
| 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. | ||
|
|
||
| Table Diffing | ||
| ^^^^^^^^^^^^^ | ||
|
|
||
| Similar to the Isolated Diffing and List Diffing features, but specifically for HTML tables. | ||
|
|
||
| More information to come on this soon. | ||
|
|
||
| New option to group together diffed words by not matching on whitespace-only. Option is enabled by default. | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| 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. | ||
|
|
||
| Old Text:: | ||
|
|
||
| testing some text here and there | ||
|
|
||
| New Text:: | ||
|
|
||
| testing other words here and there | ||
|
|
||
| With $groupDiffs = false (original functionality):: | ||
|
|
||
| testing <del>some</del><ins>other</ins> <del>text</del><ins>words</ins> here and there | ||
|
|
||
| With $groupDiffs = true (new feature):: | ||
|
|
||
| testing <del>some text</del><ins>other words</ins> here and there | ||
|
|
||
| Change diffing to strike through entire words/numbers if they contain periods or commas within the word | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| This change introduced a new property ``$specialCaseChars``, which defaults to the following characters: ``.`` ``,`` ``(`` ``)`` ``'`` | ||
|
|
||
| This feature can be "disabled" by simply setting the $specialCaseChars to an empty array i.e. ``$diff->setSpecialCaseChars(array())`` | ||
|
|
||
| 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. | ||
|
|
||
| For example, diffing ``10,000.50`` against ``11,100.75`` gives you: | ||
|
|
||
| Original Functionality:: | ||
|
|
||
| <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> | ||
|
|
||
| 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:: | ||
|
|
||
| <del class="diffmod">10,000.50</del><ins class="diffmod">11,100.75</ins> | ||
|
|
||
| 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. | ||
|
|
||
| Added option to insert a space between ``<del>`` and ``<ins>`` tags. Disabled by default. | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| This was a requirement for one our applications that uses this library. | ||
|
|
||
| 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. | ||
|
|
||
| Enable it by calling ``$diff->setInsertSpaceInReplace(true);`` | ||
|
|
||
| Original Functionality:: | ||
|
|
||
| <del>Old</del><ins>New</ins> | ||
|
|
||
| New Functionality:: | ||
|
|
||
| <del>Old</del> <ins>New</ins> | ||
|
|
||
| .. _c9ba1fa: https://github.com/caxy/php-htmldiff/commit/c9ba1fab6777cd47427477f8d747293bb01ef1e8 | ||
| .. _0.0.6: https://github.com/caxy/php-htmldiff/releases/tag/0.0.6 | ||
|
|