Developer and arbiter guide

Integrate OpenPairing with PHP or the command line

Minimal examples for installing the engine, pairing a round, producing standings and checking a TRF26 tournament. The runtime is stateless, offline and uses no database.

01

Install and check the runtime

Requires PHP 8.3 or later. ext-gmp is recommended for medium and large tournaments.

composer install
composer check
php bin/openpairing.php --version

02

Pair rounds and calculate standings from the CLI

php bin/openpairing.php tournament.trf > pairing.json
php bin/openpairing.php --input-format=json tournament.json > pairing.json
php bin/openpairing.php --standings tournament.trf > standings.json
php bin/openpairing.php --standings --tie-breaks=DE/P,BH/C1/P,SB/C1 state.json

Use output only when the exit code is 0. Errors and ambiguous inputs fail explicitly.

03

Use the public PHP API

Decode canonical state and return a structured result, never a partial success.

<?php
require __DIR__ . '/vendor/autoload.php';

use OpenPairing\Engine\Dutch\DutchPairingEngine;
use OpenPairing\Format\Json\CanonicalJson;

$json = file_get_contents('tournament.json');
$state = (new CanonicalJson())->decode($json);
$result = (new DutchPairingEngine())->pair($state);

if ($result->violations !== []) {
    throw new RuntimeException(json_encode($result->toArray()['violations']));
}

echo json_encode($result->toArray(), JSON_PRETTY_PRINT);

For Burstein tournaments use BursteinPairingEngine. Internal matching classes are not part of the stable API.

04

Choose canonical JSON or TRF26

Canonical JSON

Schema openpairing.tournament/1 contains round, system, scoring, players and history.

JSON example →

TRF26

The codec requires the system in record 192 and rejects incompatible or ambiguous inputs.

TRF26 support →

05

Verify with PTC and generate cases with RTG

php bin/openpairing-ptc.php completed.trf > ptc-report.json
php bin/openpairing-rtg.php --players=80 --rounds=9 --seed=20260815 > generated.trf
php bin/openpairing-ptc.php generated.trf > generated-report.json
Transparent status: OpenPairing is open-source software with publishable internal verification. No page claims or implies a FIDE certification that has not been obtained.