Download the PHP package matecat/icu-intl without Composer

matecat/icu-intl

A PHP port of ICU4J's MessagePattern parser with locale utilities. Parses ICU MessageFormat patterns into an inspectable AST and provides locale data support for internationalization in PHP.

This package focuses on:

• ICU MessagePattern parser: Parses ICU MessageFormat patterns into a precise token stream and AST (Abstract Syntax Tree), exposing the internal structure of messages (literals, arguments, selects, plurals, nested sub-messages, offsets, quoted text, etc.).
• Locale utilities: Access language data, plural rules, and locale validation for internationalization support.

This package does not provide locale-aware date/number formatting itself — it provides the pattern model and utilities so you can build formatters or validators that interoperate with PHP's intl extension or other formatting libraries.

Contents

• Features
• Installation
• Namespaces
• Quick Usage
• High-level API
• Exceptions
• Development
• Project Structure

Authors

• Domenico Lupinetti — Ostico — [email protected] / [email protected]

Features

ICU MessagePattern Parser

• Full tokenization of ICU MessageFormat patterns (braces, argument names/indexes, type specifiers, selectors, offsets, quoted text, etc.).
• AST representation of a parsed message pattern (message, message parts, argument placeholders, plural/select blocks, and their sub-messages).
• Utilities for traversing, validating, and reconstructing patterns.
• Error reporting with position information for malformed patterns.
• Mirrored behavior of ICU4J MessagePattern parsing logic (same parsing rules and edge-case handling).

Locale Utilities

• Languages: Comprehensive language data including localized names, RTL detection, and language code validation.
• Plural Rules: CLDR-based plural rules for 140+ languages to determine the correct plural form for any number.
• Language Domains: Domain-specific language groupings for translation workflows.

Installation

Install via Composer

Requirements

• PHP 8.3+
• ext-mbstring required
• ext-intl recommended for full formatting integration (not required for parsing)
• Composer for installation and development tasks

Namespaces

Quick Usage

ICU MessagePattern Parser

Basic parse and inspect

Simple placeholders

Plural example

Nested selects and plurals

Locale Utilities

Languages

Plural Rules

Plural Compliance Validation

The MessagePatternValidator validates that plural/selectordinal selectors comply with CLDR plural categories for a given locale. It provides per-argument warnings for detailed feedback.

Simplified API (recommended)

The validator can work directly with a pattern string, without needing to create a MessagePattern object first:

Factory Method (with pre-parsed MessagePattern)

Use the fromPattern() factory method when you have a pre-parsed MessagePattern or want to validate the same pattern against multiple locales:

Working with Warnings

Exception Handling

More Examples

Validation Behavior Summary

Pattern Comparison for Translations

The MessagePatternComparator validates that translated ICU patterns maintain the same complex forms (plural, select, choice, selectordinal) as the source pattern. This ensures translations don't accidentally lose required argument structures.

Basic Usage

Factory Methods

Use factory methods when you have pre-configured validators or pre-parsed patterns:

Exception Handling

Helper Methods

Validation Rules

Language Domains

Notes about formatting

This library focuses on parsing and structure. If you want to format values using parsed plural/select patterns:

• Use PHP's Intl MessageFormatter (intl extension) for end-to-end ICU MessageFormat formatting (it accepts message strings and values).
• Or, implement a custom formatter that walks the AST and applies number/date formatting from ext-intl or other libraries.

High-level API

Quick reference for the public classes and the most-used methods.

Matecat\ICU\MessagePattern

• __construct(?string $pattern = null, string $apostropheMode = MessagePattern::APOSTROPHE_DOUBLE_OPTIONAL)
• parse(string $pattern): self
• parseChoiceStyle(string $pattern): self
• parsePluralStyle(string $pattern): self
• parseSelectStyle(string $pattern): self
• clear(): void
• clearPatternAndSetApostropheMode(string $mode): void
• getApostropheMode(): string
• getPatternString(): string
• hasNamedArguments(): bool
• hasNumberedArguments(): bool
• autoQuoteApostropheDeep(): string
• parts(): PartAccessor — returns the part accessor for querying parsed tokens
• validateArgumentName(string $name): int (static helper)
• appendReducedApostrophes(string $s, int $start, int $limit, string &$out): void (static helper)
• Implements Iterator<Part> to iterate parts.

Matecat\ICU\Parsing\PartAccessor

Accessed via $pattern->parts():

• countParts(): int
• getPart(int $index): Part
• getPartType(int $index): TokenType
• getSubstring(Part $part): string
• partSubstringMatches(Part $part, string $s): bool
• getNumericValue(Part $part): float (returns MessagePattern::NO_NUMERIC_VALUE when not numeric)
• getPluralOffset(int $pluralStart): float
• getPatternIndex(int $partIndex): int
• getLimitPartIndex(int $start): int

Matecat\ICU\Tokens\Part

Represents a parsed token/part with accessors:

• getType(): TokenType
• getIndex(): int
• getLength(): int
• getValue(): int
• getLimit(): int
• getArgType(): ?ArgType
• Part::MAX_LENGTH
• Part::MAX_VALUE

Matecat\ICU\Tokens\TokenType (enum)

Token types used by the parser: MSG_START, MSG_LIMIT, ARG_START, ARG_NAME, ARG_NUMBER, ARG_INT, ARG_DOUBLE, ARG_TYPE, ARG_STYLE, ARG_SELECTOR, ARG_LIMIT, INSERT_CHAR, REPLACE_NUMBER, SKIP_SYNTAX, etc.

Matecat\ICU\Tokens\ArgType (enum)

Argument classifications: NONE, SIMPLE, CHOICE, PLURAL, SELECT, SELECTORDINAL.

Matecat\ICU\MessagePatternValidator

• __construct(string $language = 'en-US', ?string $patternString = null) - Creates a validator with the specified locale and optional pattern string
• static fromPattern(string $language, MessagePattern $pattern): MessagePatternValidator - Factory method to create a validator from a pre-parsed MessagePattern (useful for validating the same pattern against multiple locales)
• setPatternString(string $patternString): static - Sets the pattern string for lazy parsing, resets any stored parsing exception, and clears the internal pattern (fluent interface)
• getPattern(): MessagePattern - Returns the parsed MessagePattern instance (triggers parsing if not already done)
• containsComplexSyntax(): bool - Returns true if the pattern contains plural, select, choice, or selectordinal
• isValidSyntax(): bool - Returns true if the pattern string has valid ICU MessageFormat syntax, false if there were parsing errors
• getSyntaxException(): ?string - Returns the parsing exception message if the pattern has invalid syntax, null otherwise
• validatePluralCompliance(): ?PluralComplianceWarning - Validates if plural forms comply with the locale's expected categories. Returns null if valid, a warning object if there are issues. Throws PluralComplianceException for invalid CLDR categories, or InvalidArgumentException/OutOfBoundsException for parsing errors.

Matecat\ICU\MessagePatternComparator

Compares source and target ICU MessageFormat patterns for translation validation. Ensures target patterns maintain the same complex forms (plural, select, choice, selectordinal) as source patterns.

• __construct(string $sourceLocale, string $targetLocale, string $sourcePattern, string $targetPattern) - Creates a comparator with source/target locales and pattern strings
• static fromValidators(MessagePatternValidator $sourceValidator, MessagePatternValidator $targetValidator): MessagePatternComparator - Factory method to create a comparator from pre-configured validators
• static fromPatterns(string $sourceLocale, string $targetLocale, MessagePattern $sourcePattern, MessagePattern $targetPattern): MessagePatternComparator - Factory method to create a comparator from pre-parsed patterns (useful for reusing parsed patterns across multiple locale comparisons)
• validate(bool $validateSource = false, bool $validateTarget = false): ComparisonResult - Validates that all complex forms in source exist in target. Optionally validates plural/ordinal compliance against CLDR rules for the source and/or target locale. Returns a ComparisonResult with sourceWarnings and targetWarnings properties (each PluralComplianceWarning|null, null if validation was not requested or no issues found). Throws MissingComplexFormException if target is missing complex forms or has mismatched types. Throws PluralComplianceException if a selector is not a valid CLDR category name.
• sourceContainsComplexSyntax(): bool - Returns true if source contains plural, select, choice, or selectordinal
• targetContainsComplexSyntax(): bool - Returns true if target contains plural, select, choice, or selectordinal
• getSourceLocale(): string - Returns the source locale
• getTargetLocale(): string - Returns the target locale
• getSourceValidator(): MessagePatternValidator - Returns the source pattern validator
• getTargetValidator(): MessagePatternValidator - Returns the target pattern validator

Matecat\ICU\Comparator\ComparisonResult (readonly)

Result object returned by MessagePatternComparator::validate(). Contains optional plural compliance warnings for source and target patterns.

• __construct(?PluralComplianceWarning $sourceWarnings = null, ?PluralComplianceWarning $targetWarnings = null)
• sourceWarnings: ?PluralComplianceWarning - Plural compliance warnings for the source pattern, or null if validation was not requested or no issues were found
• targetWarnings: ?PluralComplianceWarning - Plural compliance warnings for the target pattern, or null if validation was not requested or no issues were found
• hasWarnings(): bool - Returns true if either side has warnings

Matecat\ICU\Plurals\PluralComplianceWarning (readonly)

Returned when plural selectors have compliance issues that don't warrant an exception.

• __construct(array $argumentWarnings)
• getArgumentWarnings(): array<PluralArgumentWarning> - Get all argument-level warnings
• getAllMissingCategories(): array<string> - Get all missing categories across all arguments
• getAllWrongLocaleSelectors(): array<string> - Get all wrong locale selectors across all arguments
• getMessages(): array<string> - Get all warning messages as an array
• getMessagesAsString(): string - Human-readable warning message (joins all messages with newlines)
• Implements Stringable interface

Matecat\ICU\Plurals\PluralArgumentWarning (readonly)

Detailed warning information for a single plural/selectordinal argument.

• argumentName: string - The argument name (e.g., 'count', 'num_guests')
• argumentType: ArgType - The argument type (PLURAL or SELECTORDINAL)
• expectedCategories: array<string> - Valid CLDR categories for this argument type and locale
• foundSelectors: array<string> - All selectors found in this argument
• missingCategories: array<string> - Expected categories not found
• numericSelectors: array<string> - Explicit numeric selectors found (e.g., =0, =1)
• wrongLocaleSelectors: array<string> - Valid CLDR categories that don't apply to this locale
• getArgumentTypeLabel(): string - Returns 'plural' or 'selectordinal'
• getMessage(): string - Human-readable message for this argument
• Implements Stringable interface

Matecat\ICU\Plurals\PluralComplianceException

Thrown when a selector is not a valid CLDR category name (e.g., 'some', 'foo').

• expectedCategories: array<string> - Valid CLDR categories
• foundSelectors: array<string> - All selectors found in the message
• invalidSelectors: array<string> - Non-existent CLDR category names
• missingCategories: array<string> - (Always empty, for interface compatibility)

Matecat\ICU\Exceptions\MissingComplexFormException

Thrown when a target pattern is missing a complex form that exists in the source pattern, or when the complex form type doesn't match.

• argumentName: string - The name of the argument with the missing/mismatched complex form
• sourceArgType: ArgType - The argument type in the source pattern (PLURAL, SELECT, CHOICE, SELECTORDINAL)
• targetArgType: ?ArgType - The argument type in the target pattern (null if argument is missing entirely)
• sourceLocale: string - The source locale
• targetLocale: string - The target locale

Matecat\Locales\Languages

• getInstance(): Languages (singleton)
• getLanguages(): array
• getLanguage(string $rfc3066code): ?array
• isRTL(string $rfc3066code): bool
• getPluralsCount(string $rfc3066code): int (static)

Matecat\ICU\Plurals\PluralRules

• getCardinalFormIndex(string $locale, int $n): int (static) - Returns the plural form index for a number
• getCardinalCategoryName(string $locale, int $n): string (static) - Returns the CLDR category name ('zero', 'one', ' two', 'few', 'many', 'other')
• getCardinalCategories(string $locale): array (static) - Returns all available cardinal category names for a locale
• getOrdinalCategories(string $locale): array (static) - Returns all available ordinal category names for a locale
• getOrdinalFormIndex(string $locale, int $n): int (static) - Returns the ordinal form index for a number
• isValidCategory(string $selector): bool (static) - Checks if a selector is a valid CLDR category name

Constants

• CATEGORY_ZERO = 'zero'
• CATEGORY_ONE = 'one'
• CATEGORY_TWO = 'two'
• CATEGORY_FEW = 'few'
• CATEGORY_MANY = 'many'
• CATEGORY_OTHER = 'other'
• VALID_CATEGORIES = ['zero', 'one', 'two', 'few', 'many', 'other']

Matecat\Locales\LanguageDomains

• getInstance(): LanguageDomains (singleton)
• getDomains(): array
• getDomain(string $domainKey): ?array

Exceptions

• Matecat\ICU\Exceptions\InvalidArgumentException — syntax errors and invalid argument patterns
• Matecat\ICU\Exceptions\OutOfBoundsException — excessive sizes, nesting, and indexing errors
• Matecat\ICU\Exceptions\UnmatchedBracesException — unmatched { or } in patterns
• Matecat\ICU\Exceptions\BadChoicePatternSyntaxException — invalid choice pattern syntax
• Matecat\ICU\Exceptions\BadPluralSelectPatternSyntaxException — invalid plural/select pattern syntax
• Matecat\ICU\Exceptions\InvalidNumericValueException — bad numeric value syntax in patterns
• Matecat\ICU\Exceptions\MissingComplexFormException — missing or mismatched complex forms in pattern comparisons
• Matecat\ICU\Plurals\PluralComplianceException — invalid CLDR plural category names
• Matecat\Locales\InvalidLanguageException — invalid language codes

Development

Run tests

or

Run static analysis

Project Structure

License

This project is licensed under the GNU Lesser General Public License v3.0 or later.

• SPDX-License-Identifier: LGPL-3.0-or-later
• See the LICENSE file for the full license text.
• More info: https://www.gnu.org/licenses/lgpl-3.0.html

Credits

This PHP port mirrors ideas from ICU4J MessagePattern.java.

• See LICENSE for project license and attribution to ICU4J sources: https://github.com/unicode-org/icu
• Plural rules based on CLDR (Unicode Common Locale Data Repository): https://cldr.unicode.org/