Download the PHP package maatify/php-i18n without Composer

Key Features

• Governed structured keys: a key is scope.domain.key_part and can only exist inside an active, assigned (scope, domain).
• Exact language scopes: reads and writes address one exact language_code (or NULL, the unlocalized scope). No fallback, default or wildcard inside I18n; fallback is Host policy.
• Fail-soft reads, fail-hard writes: a runtime miss returns null or an empty DTO; a write violating governance throws a typed exception.
• Synchronous derived state: per-domain, per-language summary and per-key counters are updated in the same transaction and are rebuildable.
• Package-owned persistence: seven maa_i18n_* tables; no foreign key to, and no join with, any Host table.
• Shared transaction semantics: transactions, ordering and pagination come from maatify/persistence; an outer transaction on the same connection is joined, never committed or rolled back by I18n.
• Container-free Core: plain constructor wiring; an optional PHP-DI adapter is available but never required.

Requirements

composer.json is the source of truth for requirements and dependencies; this table reflects it.

Installation

Install the exact published Release Candidate from Packagist:

Then create the database objects once, on a fresh database, from schema/schema.i18n.sql. The file begins with DROP TABLE IF EXISTS for the seven tables, so never apply it over existing I18n data.

Quick Usage

Complete, runnable wiring: docs/guides/USAGE_GUIDE.md.

Public Runtime API

An overview only. The complete inventory (signatures, DTO fields, exceptions, sort keys) is I18N_PACKAGE_REFERENCE.md.

Critical Runtime Behavior

• Exact scope: getValue('ar', ...) reads ar only. null reads the unlocalized scope only. A miss never retries elsewhere.
• Empty is a value: the empty string is an authoritative translation, not a miss.
• Type is opaque metadata: any valid non-null string is an exact consumer-defined token. The Package defines no type vocabulary and does not assign behavior, render or sanitize values.
• Codes are not normalized: 'ar' and 'AR' are different; a code must be 1-16 characters and not whitespace-only. Whether a code is a real language is Host policy.
• Derived state: summary tables are maintained inside the write transaction; I18nStatsRebuilder::fullRebuild() repairs drift.
• No caching, no key deletion, no fallback.

Exception and Error Propagation

Every exception defined by the package implements Maatify\I18n\Exception\I18nExceptionInterface. Writes and identity lookups throw typed exceptions; runtime reads do not throw for data problems. PDOException and other external throwables propagate unchanged; a non-throwing PDO failure state becomes I18nStorageException. Catalog: Reference 6.2.

Security and Trust Boundaries

• Query values are bound parameters; table and column identifiers and sort columns come from constants and a fixed sort whitelist, never from input. Command and criteria inputs are validated for emptiness and length before storage is touched.
• Authorization, authentication, rate limiting and who may call management services are Host concerns.
• Translation values are opaque strings: escaping them for HTML, JSON or any other sink is the consumer's job.
• The schema file is destructive on an existing database (see Installation).
• See SECURITY.md for the vulnerability reporting and support policy.

Examples

Six maintained examples cover every material capability and run against a disposable MySQL in CI. See the capability map in the examples/ directory.

Schema

Reference section 8.

Documentation

Quality Status

Development and Testing

Every CI gate invokes a local command from the standalone repository root, so each can be reproduced locally with the same verification contract. Prerequisites: PHP 8.4+, Composer, actionlint available on PATH for composer check:workflows, and, for the real-MySQL gates, Docker with Compose v2. composer check:audit needs Composer 2.10 or newer (a verification-time capability, not a consumer requirement). The disposable MySQL is defined once in scripts/ci/with-mysql.sh; Integration, examples and the consumer harness all reuse it, with run-scoped temporary credentials and teardown.

composer verify runs the canonical Package verification gate set on the dependency versions currently installed or resolved, including Style and Workflow Lint. CI runs latest-compatible and lowest-supported dependency resolutions as separate compatibility modes; neither mode is part of composer verify, and composer verify does not run composer update.

The final aggregate job of the workflow is I18n Package CI Gate.

License

Proprietary. See LICENSE.

Author

Engineered by Mohamed Abdulalim (@megyptm)
Backend Lead & Technical Architect
https://www.maatify.dev