Download the PHP package k2gl/array-reader without Composer

k2gl/array-reader

Read typed values out of an untyped array — query strings, form input, CSV rows, decoded JSON, config, environment — without the isset(...) && is_string(...) ? ... : null dance, and without dropping to mixed in the eyes of PHPStan / Psalm.

Without it you write the same guard for every field and still end up with mixed:

Why install it: one tiny, zero-dependency class family that turns messy input arrays into typed values, lets you choose how forgiving the conversion is, fails loudly on missing data, and keeps static analysis green.

Install

Requires PHP 8.1+. No runtime dependencies.

Pick a reader

There are three readers. They expose the same methods and differ only in how they handle a value whose type doesn't match what you asked for. Here is one input read by each:

ArrayReader — safe casting (use this by default)

Converts the obvious string/number/bool representations and rejects anything ambiguous or lossy. Ideal for data that arrives as strings: $_GET, $_POST, CSV rows, environment variables.

StrictArrayReader — exact type only

Accepts a value only if it is already the requested type (the lone convenience: an int may be read as float). Ideal for data you already trust to be well-typed, e.g. a decoded JSON document.

LooseArrayReader — PHP's native cast

Casts any scalar with PHP's own rules and never rejects a scalar — so malformed input passes through silently. Reach for it only when you explicitly want that behaviour.

Reading values

For every scalar type each reader offers two accessors:

• strict int($key) — returns the value, or throws: MissingKeyException when the key is absent, TypeMismatchException when the value cannot be produced as the requested type.
• lenient intOr($key, $default = null) — returns the value, or $default when the key is absent or the value cannot be produced. Pass a non-null default and the return type is non-null too (conditional return types, so PHPStan / Psalm narrow it for you).

Arrays, lists and nesting

array(), list() and nested() never cast — in every reader they only validate shape:

Read a list of nested objects ({"items": [{...}, {...}]}) as a list of readers with nestedList() / nestedListOr():

Typed scalar lists

ints(), strings(), floats() and bools() read a list and produce every element through the same cast pipeline as the scalar accessors, so the reader's mode applies element by element. They turn ids[]=1&ids[]=2, CSV columns or JSON arrays into a list<int> / list<string> / … without a manual array_map().

For lists of enums or dates see the sections below; for any other element type listOf() maps each element of a list through a caster of your own — the "array of objects to DTOs" payload:

Enums

enum() / enumOr() read a backed enum: the enum's backing scalar is produced through the same cast pipeline (so the reader's cast mode applies), then resolved with BackedEnum::tryFrom(). A value that is absent, cannot be produced as the backing type, or is not one of the enum's cases throws (strict) or returns the default (enumOr):

The cast mode applies to the backing scalar: with ArrayReader (safe) a numeric string "2" resolves an int-backed enum, StrictArrayReader requires the exact backing type, and LooseArrayReader coerces any scalar. Only backed enums are supported.

Dates

dateTime() / dateTimeOr() read a date/time string into a DateTimeImmutable. The value is read as a string through the cast pipeline, then parsed. Without a format any DateTimeImmutable-parsable string is accepted (ISO-8601, relative, @timestamp); pass a format and the input must match it exactly — surplus characters or parse warnings are rejected.

Nested keys (dot notation)

Every key-based accessor (has(), the scalar getters, enum(), dateTime(), nested(), the list accessors, …) accepts a dot path into nested arrays. A literal key always wins — a key that contains a dot keeps resolving to itself — and the path is only walked when no literal key matches, so this is fully backward compatible.

Lazy defaults and required keys

stringOrElse() / intOrElse() / floatOrElse() / boolOrElse() work like the *Or accessors, but the default comes from a callback that runs only when the value cannot be produced — handy when computing the default is expensive.

require() asserts that a set of keys (dot paths allowed) is present, failing once with all the missing keys instead of one at a time, and returns the reader for chaining.

Helpers and JSON

Error handling

Every exception implements K2gl\ArrayReader\Exception\ArrayReaderException, so you can catch the whole family at once:

Safe casting reference (ArrayReader)

What ArrayReader accepts beyond the exact type — anything else throws (strict) or returns the default (*Or):

Zero dependencies

array-reader has no runtime dependencies — its only require is php itself. Installing it pulls nothing else into your dependency tree: no transitive packages to audit, no version conflicts to resolve, and it is safe to drop into any application or library, including ones that must stay dependency-light.

License

MIT © Nick Harin. See LICENSE.