Extension:Diff

Diff is a small diff library for structured data. It can be used as stand alone in any PHP application or as MediaWiki extension that can then be used by other extensions.

Diff provides classes representing diffs, diff operations and contains functions to generate various types of diffs. It does not contain any code to visualize diffs.

Requirements
Diff requires:


 * PHP 5.3 or above
 * (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.standalone.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
Diff contains a set of "diff operations" (things implementing IDiffOp). Each such operation represents a difference in a diff. A diff is thus a collection of such diff operations. Operations can be atomic, for instance an addition or a change of a value, or they can be composites that themselves are diffs and thus containing diff operations. This allows for arbitrary nesting needed for creating diffs of arrays and maps with depth > 1.

You can create a new diff either by starting of with an empty diff and adding operations to it, or you can create one from source data via one of the diff methods.


 * Atomic operations


 * DiffOpAdd - addition of a value
 * DiffOpChange - modification of a value
 * DiffOpRemove - removal of a value


 * Composite operations (ie diffs)


 * Diff - collection of arbitrary diff operations
 * ListDiff - collection of add and remove operations, for diffs between (non-associate) arrays
 * MapDiff - collection of arbitrary diff operations, for diffs between associative arrays (ie maps)


 * Diff methods


 * - Filters the diff for operations that can be applied to the provided object
 * - Filters the diff for operations that can be applied to the provided object
 * - Filters the diff for operations that can be applied to the provided object

Example
This shows a few things you can do and is by no means a comprehensive list of the libs capabilities :)

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

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