README

A simple, strict, canonical Roman numeral validator and converter.

This library supports modern, canonical Roman numerals only and provides clear validation diagnostics when input is invalid and/or non-canonical.

This library intentionally rejects non-canonical forms to prevent subtle logical errors and ambiguous interpretations.

It is designed to be:

• accurate
• easy to understand
• easy to use
• well-documented
• safe for reuse in other projects

The public class interface is stable and fully covered by PHPUnit tests.

Features

• Convert integers to canonical Roman numerals
• Validate Roman numeral strings
• Reject non-canonical forms (e.g. VIIII, IL, IXC)
• Enforce modern Roman numeral rules
• Provide detailed validation errors with positional metadata
• No dependencies
• No objects to instantiate (you can use just static methods/functions)
• PHP 8.2+

Installation

Install via Composer:

composer require dickdonohue/roman-numeral

After installation, a CLI tool is available at vendor/bin/roman-numeral.

Usage

Integer to Roman numeral

use RomanNumeral\RomanNumeral;

echo RomanNumeral::intToRoman(944);
// CMXLIV

Validating a Roman numeral

use RomanNumeral\RomanNumeral;

$result = RomanNumeral::validate('XIV');
/*
[
  'valid'  => true,
  'value'  => 14,
  'errors' => null
]
*/

Handling non-canonical input

$result = RomanNumeral::validate('VIIII');

/* $result is a keyed array
[
  'valid'  => false,
  'value'  => null,
  'errors' => [
    [
      'message'  => 'Non-canonical Roman numeral. Canonical form is IX.',
      'position' => 0,
      'symbol'   => null
    ]
  ]
]
*/

Canonical rules enforced

• Allowed symbols: I V X L C D M
• Repeats:
  • I, X, C, M may repeat up to three times
  • V, L, D may not repeat
• Allowed subtractive pairs:
  • IV, IX, XL, XC, CD, CM
• Only one symbol may be subtracted at a time
• Symbols must appear in descending value order
• Maximum supported value is 3999 (MMMCMXCIX)

Testing

Run the test suite:

composer test

Run tests with readable output:

composer test:testdox

Miscellaneous

When I was a child, we had a clock in our kitchen with Roman Numerals. As a child, I really did not like it. But this was my first experience with representing numbers as something other than Arabic (decimal) numbers! That happens all the time when writing programs. It makes me wonder if this early-childhood experience actually helped lead me to becoming a successful computer programmer.

Recently, I became aware of copyright issues for the makers of the classic, stop-motion Christmas show, "Rudolf the Red-Nosed Reindeer" because they listed the year of copyright incorrectly using Roman numerals. The copyright year is shown as "MCLXIV". Unfortunately, that equates to 1164. That invalidated their copyright. (Fortunately, they had correctly filed copyrights to songs, characters, and other aspects of the show.) The correct Roman numeral should have been "MCMLXIV" (1964). I thought to myself, if only they had a nice, little library that they could have used to validate their roman numeral!

So that prompted me to create this little project as my first semi-useful project published on GitHub.

This project was developed with assistance from ChatGPT.

Fun fact: The longest valid, canonical Roman numeral string will never be more than 9 characters long. The longest string is for the value 3888 (MMMDCCCLXXXVIII).