README

Oihana PHP – Standards is a library of constants, enumerations, and helpers based on major international standards (ISO, UN, UN/CEFACT, etc.).

It is designed for strong typing, validation, and easy lookups in your PHP applications.

📑 Table of Contents

1. Installation
2. Features
   • Namespace Overview
   • Available Enumerations
3. Core Helper Methods
4. Usage Examples
5. License
6. Author

📦 Installation

Requires PHP 8.4+

Install via Composer:

composer require oihana/php-standards

✨ Features

• Ready-to-use enumerations for currencies, languages, scripts, country codes, measurement units, package types, and more.
• Built-in helpers for validation, lookups, and cross-conversions (e.g., code ↔ name ↔ symbol).
• Clear namespace organization for quick navigation and maintainability.

🗂 Namespace Overview

📚 Available Enumerations

🔧 Core Helper Methods (ConstantsTrait)

All constant classes use oihana\reflections\traits\ConstantsTrait, which provides:

💡 Usage Examples

Basic Enum Access

use org\iso\ISO4217;
use org\iso\ISO639_1;

$usd = ISO4217::USD; // 'USD'
$en  = ISO639_1::EN;  // 'en'

Validation & Listing

use org\iso\ISO4217;

ISO4217::validate('EUR');             // OK
$isValid = ISO4217::includes('JPY');  // true
$all     = ISO4217::getAll();         // ['AED' => 'AED', ...]
$values  = ISO4217::enums();          // ['AED', 'AFN', ...]

UN/CEFACT Unit Cross-Lookups

use org\unece\uncefact\MeasureCode;
use org\unece\uncefact\MeasureName;
use org\unece\uncefact\MeasureSymbol;

$code   = MeasureCode::KILOGRAM;        // 'KGM'
$name   = MeasureCode::getName($code);  // 'Kilogram'
$symbol = MeasureCode::getSymbol($code);// 'kg'

// Reverse lookups
$fromName   = MeasureCode::getFromName('Kilogram'); // 'KGM'
$fromSymbol = MeasureCode::getFromSymbol('kg');     // 'KGM'

UN/CEFACT Package Conversion

use org\unece\uncefact\PackageCode;
use org\unece\uncefact\PackageName;

$bx   = PackageCode::BOX;            // 'BX'
$name = PackageCode::getName($bx);   // 'Box'
$code = PackageName::getCode('Box'); // 'BX'

ISO 3166-1 Country Codes

use org\iso\ISO3166_1;

$fr = ISO3166_1::FR;        // 'FR'
ISO3166_1::validate('US');  // OK
$all = ISO3166_1::getAll(); // ['FR' => 'FR', ...]

UN M49 Country Codes

use org\unstats\UNM49;

$fr = UNM49::FRA; // 'FRA'

Utility: ISO 8601 Durations

The Iso8601Duration class (PHP 8.4+) provides robust handling of duration strings using property hooks.

use org\iso\Iso8601Duration;
use DateTime;

// 1. Create a duration
$duration = new Iso8601Duration('P1M5D'); // 1 Month and 5 Days

// 2. Use helper methods to add/subtract
$date = new DateTime('2024-01-10');
$newDate = $duration->addTo($date);

echo $newDate->format('Y-m-d'); // '2024-02-15'

// 3. Properties are synchronized
$duration->iso = 'PT2H30M'; // Change duration to 2 hours 30 minutes
echo $duration->toSeconds(); // 9000

$date2 = new DateTime('2024-01-01 10:00:00');
echo $duration->subtractFrom($date2)->format('Y-m-d H:i:s'); // '2024-01-01 07:30:00'

// 4. Create from DateInterval
$interval = $date->diff($newDate);
$durationFromInterval = new Iso8601Duration($interval);
echo $durationFromInterval->iso; // 'P1M5D'

Utility: ISO 8601 Times

The Iso8601Time class (PHP 8.4+) provides robust handling of time-only strings.

use org\iso\Iso8601Time;
use DateTimeImmutable;
use DateTimeZone;

// 1. Create from an ISO string
$time = new Iso8601Time('T14:30:00Z');

// 2. Access properties
echo $time->hours;   // 14
echo $time->minutes; // 30
echo $time->iso;     // "T14:30:00Z"

// 3. Properties are synchronized
$time->iso = 'T08:15:00+02:00';
echo $time->hours; // 8
echo $time->time->getTimezone()->getName(); // '+02:00'

// 4. Create from DateTimeInterface
$dt = new DateTimeImmutable('23:59:59', new DateTimeZone('-05:00'));
$timeFromDt = new Iso8601Time($dt);
echo $timeFromDt->iso; // 'T23:59:59-05:00' 

Helper: ISO 8601 Conversion & Validation

toIso8601Duration()

Converts a DateInterval object directly into a normalized ISO 8601 string.

use function org\iso\helpers\toIso8601Duration;
use DateTime;
use DateInterval;

// From a diff
$start = new DateTime('2024-01-01');
$end = new DateTime('2024-03-15');
$interval = $start->diff($end);

echo toIso8601Duration($interval); // 'P2M14D'

// From a new interval
$interval = new DateInterval('PT1H30M');
echo toIso8601Duration($interval); // 'PT1H30M'

toIso8601Time()

Converts a DateTimeInterface object into a normalized ISO 8601 time string.

use function org\iso\helpers\toIso8601Time;
use DateTimeImmutable;
use DateTimeZone;

$dt_utc = new DateTimeImmutable('14:30:00', new DateTimeZone('UTC'));
echo toIso8601Time($dt_utc); // "T14:30:00Z"

$dt_offset = new DateTimeImmutable('08:15:30', new DateTimeZone('+02:00'));
echo toIso8601Time($dt_offset); // "T08:15:30+02:00"

isIso8601Duration() and isIso8601Time()

Validates if a string conforms to the ISO 8601 specification.

use function org\iso\helpers\isIso8601Time;
use function org\iso\helpers\isIso8601Duration;

// Time Validation
isIso8601Time('T14:30:00Z');      // true
isIso8601Time('T14:30:00', true); // true (strict)
isIso8601Time('14:30:00', true); // false (strict requires 'T')
isIso8601Time('T25:00:00');      // false (invalid hour)
isIso8601Time('T12:60:00');      // false (invalid minute)

// Duration Validation
isIso8601Duration('P1Y2M3D');  // true
isIso8601Duration('PT4H30M');  // true
isIso8601Duration('P1YT');     // false (strict mode)
isIso8601Duration('P');        // false
isIso8601Duration('INVALID');  // false 

📜 License

MPL 2.0 — Mozilla Public License Version 2.0

👤 Author

• Marc ALCARAZ (aka eKameleon)
• 📧 marc@ooop.fr
• 🌐 http://www.ooop.fr