Extension:Diff

Diff is a small library for creating and representing diffs between data structures. It is a standalone PHP library that can be used by PHP applications (such as MediaWiki extensions). It does thus not expose functionality to the user on its own.

Diff provides classes to represent diffs and the operations they consist of, as well as service objects to compute such diffs or apply them as a patch.

Requirements
Diff requires:


 * PHP 5.3 or above
 * (For running the PHPUnit tests: PHPUnit 3.7 or later)
 * (If used as MediaWiki extension: MediaWiki 1.16 or later)

As MediaWiki extension
Once you have downloaded the code, place the Diff directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file:

As standalone library
Include Diff/Diff.php. This file includes an autoloader allowing you to directly reference the diff classes without first including their files. If you want to use your own autoloader, you can find the list of diff classes in Diff/Diff.classes.php.

Usage
The Diff library can be subdevided into 3 components.

DiffOp
First and formost are the objects to represent diffs. Diffs are represented by the Diff class, which is an aggregate for diff operations, think "add" and "remove", that all extend from DiffOp. Diff itself is a DiffOp, since the library supports recursion, and thus has the need to be able to represent nested diffs.

The available DiffOps are:


 * DiffOpAdd - addition of a value (newValue)
 * DiffOpChange - modification of a value (oldValue, newValue)
 * DiffOpRemove - removal of a value (oldValue)
 * Diff - a collection of diff operations

These can all be found in.

The Diff class can be set to be either associative or non-assocative. In case of the later, only DiffOpAdd and DiffOpRemove are allowed in it.

Differ
Often you need to construct a diff between two arrays, rather then creating it manually. To do this, the Diff library includes a few classes implementing the Differ interface, which contains one very simple method.

The Differs that come with the library are:


 * ListDiffer: Differ that only looks at the values of the arrays (and thus ignores key differences).
 * MapDiffer: Differ that does an associative diff between two arrays, with the option to do this recursively.

Both Differ objects come with a few options that can be used to change their behaviour.

All differ functionality can be found in.

Patcher
The third component that comes with the Diff library is a set of classes implementing the Patcher interface. This interface contains a single simple method:

Diff comes with two clases implementing the Patcher interface:


 * ListPatcher: Applies non-associative diffs to a base. With default options does the reverse of ListDiffer
 * MapPatcher: Applies diff to a base, recursivly if needed. With default options does the reverse of MapDiffer

All classes part of the patcher component can be found in

Comparer
Added in 0.6

TODO

Merger
Added in 0.7

TODO

Examples

 * DiffOp:


 * Differ


 * Patcher

Version
This is a copy of the release notes file on Git, which might be more up to date than this page.

Version 0.6
2013-05-08


 * Compatibility changes


 * The tests can now run independently of MediaWiki
 * The tests now require PHPUnit 3.7 or later


 * Additions


 * Added phpunit.php runner in the tests directory
 * Added Diff\Comparer\ValueComparer interface with CallbackComparer and StrictComparer implementations
 * Added MapPatcher::setValueComparer to facilitate patching maps containing objects
 * Added PHPUnit configuration file using the new tests/bootstrap.php


 * Removals


 * GenericArrayObject has been removed from this package. Diff derives from ArrayObject rather than GenericArrayObject. Its interface has not changed expect for the points below.
 * The getObjectType method in Diff (previously defined in GenericArrayObject) is now private rather than public.
 * Adding a non-DiffOp element to a Diff will now result in an InvalidArgumentException rather than a MWException.
 * Removed Diff\Exception

Version 0.5
2013-02-26


 * Additions


 * Added DiffOpFactory
 * Added DiffOp::toArray
 * Added CallbackListDiffer
 * Added MapDiffer::setComparisonCallback


 * Deprecations


 * Hard deprecated ListDiff, MapDiff and IDiff


 * Removals


 * Removed Diff::getApplicableDiff

Version 0.4
2013-01-08


 * Additions


 * Split off diffing code from MapDiff and ListDiff to dedicated Differ classes
 * Added dedicated Patcher classes, which are used for the getApplicableDiff functionality


 * Deprecations


 * Deprecated ListDiff:newFromArrays and MapDiff::newFromArrays
 * Deprecated ListDiff::newEmpty and MapDiff::newEmpty
 * Deprecated Diff::getApplicableDiff
 * Soft deprecated DiffOp interface in favour of DiffOp
 * Soft deprecated IDiff interface in favour of Diff
 * Soft deprecated MapDiff and ListDiff in favour of Diff


 * Removals


 * Removed parentKey functionality from Diff
 * Removed constructor from Diff interface
 * Removed Diff::newEmpty

Version 0.3
2012-11-21


 * Improved entry point and setup code. Diff.php is now the main entry point for both MW extension and standalone library
 * ListDiffs with only add operations can now be applied on top of bases that do not have their key
 * Added IDiff::removeEmptyOperations
 * Improved type hinting
 * Improved test coverage
 * Added constructor tests for MapDiff and ListDiff
 * Added extra tests for Diff and MapDiff
 * Test coverage is now 100%
 * Removed static method from IDiff interface since this is not allowed in strict mode

Version 0.2
2012-11-01


 * Fixed tests to work with PHP 5.4 and above
 * Added translations
 * Added some profiling calls

Version 0.1
2012-9-25

Initial release with these features:


 * Classes to represent diffs or collections of diff operations: Diff, MapDiff, ListDiff
 * Classes to represent diff operations: Diff, MapDiff, ListDiff, DiffOpAdd, DiffOpChange, DiffOpRemove
 * Methods to compute list and maps diffs
 * Support for recursive diffs of arbitrary depth
 * Works as MediaWiki extension or as standalone library

Internationalization
is fully internationalized. Translation of messages is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Authors
Diff has been written by Jeroen De Dauw as Wikimedia Germany employee for the Wikidata project.

Test coverage
Diff has better unit test coverage then any other MediaWiki extension [citation needed].