PHPackages                             polyprism/runtime - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. polyprism/runtime

ActiveLibrary[Utility & Helpers](/categories/utility)

polyprism/runtime
=================

Runtime helpers for PolyPrism's PHP domain-class emitter — Coerce + Normalise utilities used by generated property-hook setters. Zero third-party dependencies.

v0.2.1(1mo ago)01MITPHPPHP ^8.1

Since Jun 6Pushed 1mo agoCompare

[ Source](https://github.com/TravFitz/polyprism-runtime-php)[ Packagist](https://packagist.org/packages/polyprism/runtime)[ Docs](https://github.com/TravFitz/polyprism/tree/main/packages/runtime-php)[ RSS](/packages/polyprism-runtime/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (3)Used By (0)

polyprism/runtime
=================

[](#polyprismruntime)

Runtime helpers for PolyPrism's PHP **domain-class** emitter. Provides the `Coerce` and `Normalise` utilities that generated property-hook setters call into — and which you can also use directly in hand-written PHP for boundary-input normalisation.

> Primarily designed to back [`@polyprism/php-domain-class`](https://github.com/TravFitz/polyprism/tree/main/packages/php-domain-class)'s generated code. The other PHP generators (`@polyprism/php-class`, `@polyprism/php-readonly`) emit code with zero runtime dependencies — they don't need this package.

Requirements
------------

[](#requirements)

- **PHP 8.1 or later** for the runtime itself (`Coerce` + `Normalise` use only PHP 8.0-era syntax: union types, `final` classes, untyped class constants)
- No third-party dependencies

**If you're using `@polyprism/php-domain-class`-generated code:** that generated code uses PHP 8.4 **property hooks** (`public int $x { set(...) { ... } }`) and so requires PHP 8.4+ to run. But the runtime itself is broadly compatible — meaning you can `composer require polyprism/runtime` from a Magento 2.4+, Symfony 6+, or Laravel 10+ project today and use `Coerce::int(...)` / `Normalise::apply(...)` directly in hand-written classes, even if you can't yet adopt the generator's output.

Install
-------

[](#install)

```
composer require polyprism/runtime
```

The PolyPrism PHP domain-class generator emits `use Polyprism\Runtime\Coerce;` and `use Polyprism\Runtime\Normalise;` at the top of each model file — Composer's PSR-4 autoloader wires them up. For hand-written usage, import the same way.

What's in the box
-----------------

[](#whats-in-the-box)

### `Polyprism\Runtime\Coerce`

[](#polyprismruntimecoerce)

Static methods that mirror `@polyprism/runtime`'s coerce primitives. Each accepts a widened input type, returns the canonical PHP type, and throws `\TypeError` with the field path on invalid input.

MethodReturns`Coerce::int(int|string $v, string $path)``int``Coerce::float(float|int|string $v, string $p)``float``Coerce::bigint(int|string $v, string $path)``int` (64-bit signed)`Coerce::date(...mixed $v, string $path)``\DateTimeImmutable``Coerce::decimal(...mixed $v, string $path)``string`Notes:

- **Bigint maps to `int`** because PHP `int` is 64-bit signed on every supported platform. Strings outside `[PHP_INT_MIN, PHP_INT_MAX]` are rejected (not silently truncated). If you need arbitrary precision, annotate the field with `@type(...)` to point at a userland `BigInteger` class.
- **Decimal returns `string`** because PHP has no native decimal type. The method validates that the input is numerically shaped; float inputs are formatted with `%.17g` to preserve IEEE-754 round-trip precision.
- **Date strings** flow through `new \DateTimeImmutable($value)` (accepts ISO 8601, RFC 2822, English textual datetime). Int inputs are treated as Unix timestamps.

Error messages line up with the JS runtime's format:

```
TypeError: Cannot coerce "abc" to int for User.points

```

### `Polyprism\Runtime\Normalise`

[](#polyprismruntimenormalise)

```
Normalise::apply(string $value, array $ops): string
Normalise::applyNullable(?string $value, array $ops): ?string
```

Ops are class constants (use these in generated code, not raw strings):

- `Normalise::TRIM`
- `Normalise::LOWERCASE`
- `Normalise::UPPERCASE`
- `Normalise::NULL_EMPTY_TO_NULL` *(only meaningful on `applyNullable`)*

Ops are applied in declared order. `apply` ignores `NULL_EMPTY_TO_NULL` (it's only meaningful on the nullable path).

Versioning
----------

[](#versioning)

`polyprism/runtime` (Composer / Packagist) and `@polyprism/runtime` (npm) are versioned independently — they target different language runtimes and don't share code. The PHP package's floor is PHP 8.1 (broad Magento/Symfony/Laravel compatibility) and will float upward only when a new PHP feature meaningfully improves the runtime's contract. The npm runtime targets Node 22+ and follows the same float-the-floor policy.

### Hand-written usage example

[](#hand-written-usage-example)

```