Directorium Core

Liturgical-calendar engine for the traditional Roman rite — Introíbo ad altáre Dei.

Directorium Core is a clean-room PHP library that computes the traditional Roman liturgical calendar. For any date it resolves the office of the day, its rank/class, liturgical colour, season, commemorations, and the occurrence/concurrence between them — beginning with the 1962 Roman rubrics (= 1960) and growing to the other traditional systems. It is the authoritative engine behind the Directorium API, the directorium.app website, and the Ordo WordPress plugin.

The engine is independently validated day-by-day against external oracles (the missalemeum calendar, the SSPX ordo feed, and Divinum Officium's reference implementation), so its output is provably correct across centuries. The compiled calendar corpus ships as generated static data.

Status

v0.1.0 — the first tagged release, cut 2026-08-05 (see CHANGELOG.md).

Note the two version axes, which do not track each other: the release tag is cut by the automation, while Directorium::VERSION (0.5.0) is the engine version and corpusVersion the data version. They are separate on purpose — a golden-digest move is attributed to exactly one of them and never left unexplained.

Four editions (1962, 1954, 1955, Novus Ordo 2002) and four overlays resolve across a proven 1584–2200. The v1.2 Office/text layer carries the entire per-annum Little Office of the BVM — all eight hours — resolving into every 1962 day. See the roadmap, which predates v1.2.

Install

composer require directorium/core

Requires PHP 7.4+. No runtime dependencies.

Usage

Two free functions in the Directorium\Core namespace are the entry points:

use function Directorium\Core\day;
use function Directorium\Core\contract;

// The resolved office as typed value objects:
$day = day(new DateTimeImmutable('2026-06-30'));
foreach ($day->celebration() as $office) {
    echo $office->id()->toString(), ' — ', $office->rank()->label(), "\n";
}

// The versioned, JSON-ready output contract (what the Api/Site/Ordo build on):
$c = contract(new DateTimeImmutable('2026-06-30'), false, 'sspx', '1954');
echo $c['edition'];               // roman:divino-afflatu
echo $c['celebration'][0]['id'];  // the winning office

Both take optional $calendar (particular-calendar overlay) and $rubricSystem (edition) selectors. The integration guide covers the full API and worked examples; calendars and editions explains the editions (1962/1954/1955) and overlays (SSPX/FSSP/ICKSP) and how to select them.

Output contract

contract() returns the versioned, JSON-ready output contract — the public shape the Api, Site, and Ordo repos build on. It is versioned (currently 1.0.2) and grows only additively within 1.x. Every field, the three-version provenance scheme, the stability guarantees, and worked examples are documented in docs/design/output-contract.md.

Development

Work branches off develop and lands via merge-commit PRs with Conventional-Commit titles — never squash or rebase, which re-author the commit and destroy the ssh signature (commits must land verified). Releases are cut automatically by release-please (see docs/releasing.md). Local checks once the code lands:

composer install
composer exec phpcs        # PSR-12
composer exec phpstan      # static analysis
php tests/validate-oracle.php tests/fixtures/oracle.json   # day-by-day regression

Licence

© 2026 Directorium. Licensed under AGPL-3.0-or-later (see LICENSE). The compiled calendar dataset is released under CC0.