Wikidiff2

**MediaWiki extensions manual**
wikidiff2; Release status: stable
Implementation	PHP
Description	Faster diff plugin for MediaWiki
Author(s)	Tim Starling
Latest version	1.14.2 (2026-06-09)
MediaWiki	1.27+
Licence	GNU General Public License 2.0 or later
Download	releases.wikimedia.org - wikidiff2; browse repository (GitHub)
	Translate the Wikidiff2 extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

Wikidiff2 is a native extension for PHP that provides a faster diff engine to MediaWiki. It is partly based on the original wikidiff, and partly on MediaWiki's DifferenceEngine class. It produces diffs from input text (line-based or word-level) and can format these as HTML or JSON.

Wikidiff2 supports character-level diffs for text composed of characters from the Japanese and Thai alphabets and the unified Han, and it includes support for Thai segmentation for word-level diffs in that language. Japanese, Chinese, and Thai do not use spaces to separate words. The input is assumed to be UTF-8 encoded. Invalid UTF-8 may cause undesirable operation, such as truncation of the output, so the application should validate the input. The input text should have Unix-style line endings.

Installing

Debian or Ubuntu

apt-get install php-wikidiff2

On older versions of the package, you may need to run a command actually to enable the extension:

sudo phpenmod wikidiff2

Using PIE

Wikidiff2 can be compiled from source using PIE. First install libthai (it should be available from your OS or distro's packages, e.g., libthai-dev). Then run:

pie install wikimedia/wikidiff2

Manually

First, get and compile libthai (it should be available from your OS or distro's packages, e.g., libthai-dev).

You can download wikidiff2 through git (git clone https://gerrit.wikimedia.org/r/mediawiki/php/wikidiff2) or by downloading a tarball from https://releases.wikimedia.org/wikidiff2/.

Then compile wikidiff2. You need phpize (shipped with PHP).

cd wikidiff2
phpize
./configure
make
sudo make install

Make sure that your php option

extension = wikidiff2.so

is set. This is usually set in your "php.ini" file.

Configuration

The following "php.ini" parameters are supported:

wikidiff2.moved_line_threshold

Wikidiff2 estimates the similarity of added and deleted lines based on the changed character count. When the similarity of an added and deleted line is greater than this threshold, the lines are displayed as moved.

Range 0.0 .. 1.0. Default 0.4.

wikidiff2.change_threshold

Changed lines with a similarity value below this threshold will be split into a deleted line and added line. This helps matching up moved lines in some cases.

Range 0.0 .. 1.0. Default 0.2.

wikidiff2.moved_paragraph_detection_cutoff

When the number of added and deleted lines in a table diff is greater than this limit, no attempt to detect moved lines will be made.

Default 100.

wikidiff2.max_word_level_diff_complexity

When comparing two lines for changes within the line, a word-level diff will be done unless the product of the LHS word count and the RHS word count exceeds this limit.

Default 40000000.

MediaWiki

If the module is installed into PHP, MediaWiki will try and use it. See $wgExternalDiffEngine for configuration options.

Usage

The input is assumed to be UTF-8 encoded. Invalid UTF-8 may cause undesirable operation, such as truncation of the output, so the application should validate the input. The input text should have Unix-style line endings.

wikidiff2_do_diff

function wikidiff2_do_diff(string $text1, string $text2, int $numContextLines): string

Compare two strings $text1 and $text2, and produce output formatted as a fragment of an HTML table, that is, a series of elements.

$numContextLines is the number of copied context lines shown before and after each change. Before each block of context lines and changes, a line number will appear as an HTML comment inside a /, e.g.

This allows the application to localize line numbers.

wikidiff2_inline_diff

function wikidiff2_inline_diff(string $text1, string $text2, int $numContextLines): string

Compare two strings $text1 and $text2, and produce output formatted as inline HTML.

wikidiff2_inline_json_diff

function wikidiff2_inline_json_diff(string $text1, string $text2, int $numContextLines): string

Compare two strings $text1 and $text2 and produce output formatted as JSON. See the JSON diff format documentation.

wikidiff2_multi_format_diff

function wikidiff2_multi_format_diff(string $text1, string $text2, array $options = []): array

Compare two strings $text1 and $text2 with an associative array of options:

numContextLines: The number of context lines shown before and after each block
changeThreshold: The minimum similarity a pair of lines must have to be detected as a change and shown as a word-level diff. If present, this overrides php.ini wikidiff2.change_threshold.
movedLineThreshold: The minimum similarity a pair of lines must have to be detected as a moved line. If present, this overrides php.ini wikidiff2.moved_line_threshold.
maxMovedLines: The maximum number of added or deleted lines, above which no move detection will be performed. If present, this overrides the php.ini setting for mnoved_paragraph_detection_cutoff.
maxWordLevelDiffComplexity: The maximum complexity of a word-level diff. If the product of the word count in the LHS and RHS exceeds this value, a word-level diff will not be done. If present, this overrides php.ini wikidiff2.max_word_level_diff_complexity.
maxSplitSize: The maximum number of lines in $text2 which may be considered for a word-level diff against a single line of $text1. Default: 1.
initialSplitThreshold: The minimum similarity which must be maintained during a split detection search. The search terminates when the similarity falls below this level. Default: 0.1.
finalSplitThreshold: The minimum similarity that must be achieved to display the comparison between one line and several lines as a split. Default 0.6.
formats: An array of desired formats. Each format is one of the following strings: table, inline or inlineJSON. The default is ['table'].

The return value is an associative array of formatted outputs. The key of each element is the format name table, inline or inlineJSON, and the value is a string.

wikidiff2_version

function wikidiff2_version(): string {}

Produces the same thing as phpversion('wikidiff2').

Formats

HTML

The HTML diff, which consists of a number of HTML table rows with the rest of the document structure omitted, is available as a side-by-side or inline comparison. The characters "<", ">", and "&" will be HTML-escaped in the output. In the Wikidiff2 C++ library, you can access the side-by-side diff using the TableDiff class or the inline diff using the InlineDiff class. Both classes include an execute method that returns the diff of the text passed in as parameters. You can also access these execute methods using the PHP wrapper functions wikidiff2_do_diff (for the side-by-side diff) and wikidiff2_inline_diff (for the inline diff).

JSON

The JSON diff provides structured data to compose a visual, line-by-line comparison between two sets of text. In the Wikidiff2 C++ library, you can access the JSON diff using the InlineDiffJSON class, which includes an execute method that returns the diff of the text passed in as parameters. You can also access this execute method using the PHP wrapper function wikidiff2_inline_json_diff.

JSON diff schema

The JSON diff includes properties to identify changes between the two sets of text. For an example of a JSON diff, see the MediaWiki REST API compare revisions endpoint.

property	description
`diff` required \| array of objects	Each object in the `diff` array represents a line in a visual, line-by-line comparison between the two revisions.
`diff.type` required \| integer	The type of change represented by the diff object, either: `0`: A line with the same content in both revisions, included to provide context when viewing the diff. The API returns up to two context lines around each change. `1`: A line included in the `to` revision but not in the `from` revision. `2`: A line included in the `from` revision but not in the `to` revision. `3`: A line containing text that differs between the two revisions. (For changes to paragraph location as well as content, see type 5.) `4`: When a paragraph's location differs between the two revisions, a type 4 object represents the location in the `from` revision. `5`: When a paragraph's location differs between the two revisions, a type 5 object represents the location in the `to` revision. This type can also include word-level differences between the two revisions.
`diff.lineNumber` optional \| integer	The line number of the change based on the `to` revision.
`diff.text` required \| string	The text of the line, including content from both revisions. For a line containing text that differs between the two revisions, you can use `highlightRanges` to visually indicate added and removed text. For a line containing a new line, the API returns the text as `""` (empty string).
`diff.highlightRanges` optional \| array of objects	An array of objects that indicate where and in what style text should be highlighted to visually represent changes. Each object includes: `start` (integer): Where the highlighted text should start, in the number of bytes from the beginning of the line. `length` (integer): The length of the highlighted section, in bytes. `type` (integer): The type of highlight: `0` indicates an addition. `1` indicates a deletion.
`diff.moveInfo` optional \| object	Visual indicators to use when a paragraph's location differs between the two revisions. `moveInfo` objects occur in pairs within the diff. `id` (string): The ID of the paragraph described by the diff object. `linkId` (string): The ID of the corresponding paragraph. For type 4 diff objects, `linkId` represents the location in the `to` revision. For type 5 diff objects, `linkId` represents the location in the `from` revision. `linkDirection` (integer): A visual indicator of the relationship between the two locations. You can use this property to display an arrow icon within the diff. `0` indicates that the `linkId` paragraph is lower on the page than the `id` paragraph. `1` indicates that the `linkId` paragraph is higher on the page than the `id` paragraph.
`diff.offset` required \| object	The location of the line in bytes from the beginning of the page, including: `from` (integer): The first byte of the line in the `from` revision. A `null` value indicates that the line doesn't exist in the `from` revision. `to` (integer): The first byte of the line in the `to` revision. A `null` value indicates that the line doesn't exist in the `to` revision.

Links