Diff is a small standalone PHP library for representing differences between data structures, computing such differences, and applying them as patches. It is extremely well tested and allows users to define their own comparison strategies.
Diff does not provide any support for computing or representing the differences between unstructured data, ie text.
A full history of the different versions of Diff can be found in the release notes.
Diff 3.x:
Diff 2.x:
To add this package as a local, per-project dependency to your project, simply add a
dependency on diff/diff
to your project's composer.json
file.
Here is a minimal example of a composer.json
file that just defines a dependency on
Diff 3.x:
{
"require": {
"diff/diff": "~3.0"
}
}
The Diff library can be subdivided into several components. The main components are:
There are two support components, which are nevertheless package public:
A diff consists out of diff operations. These can be atomic operations such as add, change and remove. These can also be diffs themselves, when dealing with nested structures. Hence the composite pattern is used.
Diff operations implement the DiffOp interface.
The available operations 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 operationsThese can all be found in src/DiffOp.
The Diff
class can be set to be either associative or non-associative. In case of the later, only
DiffOpAdd
and DiffOpRemove
are allowed in it.
To compute the difference between two data structures, an instance of Differ is used.
The Differ
interface has a single method.
/**
* Takes two arrays, computes the diff, and returns this diff as an array of DiffOp.
*
* @param array $oldValues The first array
* @param array $newValues The second array
*
* @throws Exception
* @return DiffOp[]
*/
public function doDiff( array $oldValues, array $newValues ): array;
Implementations provided by Diff:
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.CallbackListDiffer
: Differ that only looks at the values of the arrays and compares them with a callback.OrderedListDiffer
: Differ that looks at the order of the values and the values of the arrays.All differ functionality can be found in src/Differ.
To apply a diff as a patch onto a data structure, an instance of Patcher is used.
The Patcher
interface has a single method.
/**
* Applies the applicable operations from the provided diff to
* the provided base value.
*
* @param array $base
* @param Diff $diffOps
*
* @return array
*/
public function patch( array $base, Diff $diffOps ): array;
Implementations provided by Diff:
ListPatcher
: Applies non-associative diffs to a base. With default options does the reverse of ListDiffer
MapPatcher
: Applies diff to a base, recursively if needed. With default options does the reverse of MapDiffer
All classes part of the patcher component can be found in src/Patcher
The ValueComparer
interface contains one method:
/**
* @param mixed $firstValue
* @param mixed $secondValue
*
* @return bool
*/
public function valuesAreEqual( $firstValue, $secondValue ): bool;
Implementations provided by Diff:
StrictComparer
: Value comparer that uses PHPs native strict equality check (ie ===).CallbackComparer
: Adapter around a comparison callback that implements the ValueComparer
interface.ComparableComparer
: Value comparer for objects that provide an equals method taking a single argument.All classes part of the ValueComparer component can be found in src/Comparer
The ArrayComposer
interface contains one method:
/**
* Returns an array containing all the entries from arrayOne that are not present
* in arrayTwo.
*
* Implementations are allowed to hold quantity into account or to disregard it.
*
* @param array $firstArray
* @param array $secondArray
*
* @return array
*/
public function diffArrays( array $firstArray, array $secondArray ): array;
Implementations provided by Diff:
NativeArrayComparer
: Adapter for PHPs native array_diff method.StrategicArrayComparer
: Computes the difference between two arrays by comparing elements with a ValueComparer
.StrictArrayComparer
: Does strict comparison of values and holds quantity into account.OrderedArrayComparer
: Computes the difference between two ordered arrays by comparing elements with a ValueComparer
.All classes part of the ArrayComparer component can be found in src/ArrayComparer
$diff = new Diff( array(
'email' => new DiffOpAdd( 'nyan@c.at' ),
'awesome' => new DiffOpChange( 42, 9001 ),
) );
$oldVersion = array(
'awesome' => 42,
);
$newVersion = array(
'email' => 'nyan@c.at',
'awesome' => 9001,
);
$differ = new MapDiffer();
$diff = $differ->doDiff( $oldVersion, $newVersion );
$oldVersion = array(
/* ... */
);
$diff = new Diff( /* ... */ );
$patcher = new MapPatcher();
$newVersion = $patcher->patch( $oldVersion, $diff );