Download the PHP package rasuvaeff/schema without Composer

rasuvaeff/schema

Schema-as-code for PHP: one definition, two ports. The same Schema::object([...]) tree validates runtime input and feeds property-based tests a generator over the exact same value set — so the validator and the tests can never drift apart.

Using an AI coding assistant? llms.txt is a compact API reference designed for LLMs.

Русская версия

Why

Validation rules and test generators are usually written separately, in different places, by different versions of you. They drift: the queue consumer accepts status: 'pending', the property test never generates it, and the tests are blind to what production actually lets through. rasuvaeff/schema kills the drift by construction: one schema defines the set, parse() checks it, arbitrary() generates from it — the parity is pinned by the package's own property suite over random schema trees.

The pattern is proven elsewhere (pydantic + hypothesis in Python, Zod + fast-check in TypeScript); this is the PHP take, built on rasuvaeff/property-testing-core.

Requirements

• PHP 8.3 / 8.4 / 8.5
• ext-mbstring
• rasuvaeff/property-testing-core ^1.2 (runtime — the generator port is the product, not a test utility)

Installation

Usage

Define

Validate

Object semantics, pinned: an absent optional key is absent from the result (not null); a defaulted key is always present, carrying the validated, normalized default (an enum default may be given as its backed value and is stored as the instance). nullable() is about the value; optional() is about the key.

Generate

In property tests (with rasuvaeff/property-testing-testo) the schema is the generator:

Export

Refinements always export as the inner schema — an honest superset, recorded in nonRepresentable. A transform with a declared codec exports it, and the package's own law 2 checks the codec against the generator's actual output. An object's default annotation goes through the wire seam: an enum default instance is exported as its backed value.

Wire: toWire()

parse/arbitrary live in the PHP domain (an enum stays an instance); queues, HTTP and JSON storage need the wire form. toWire() is the projection: an enum instance becomes its backed value, containers convert recursively, a transform's declared wire callback is applied, everything else passes through.

The inverse pair of the generator's domain — arbitrary() produces PHP values, toWire() hands them to the wire. Found by the first consumer pilot (keppio): the queue property test needed exactly this projection.

Combinators

Order rule: combinators first, property modifiers last — ->min(1)->transform(...)->optional().

Hydrating into a DTO: into()

The parsed properties are passed to the constructor as named arguments, after defaults and strip() are settled. The DTO takes its properties as public promoted constructor arguments — that is what makes toWire() lossless. A constructor that throws becomes a parse error carrying the class names only. The export is the object schema's own. Keep the DTO's own invariants within the schema: a constructor stricter than the schema breaks the generator.

Patterns outside the generatable subset: regexUnchecked()

regex() only accepts patterns Gen::stringMatching can generate — \z, lookaround and backreferences are rejected at construction. regexUnchecked() is the explicit opt-out: you supply the generator, the schema keeps the pattern for parsing and export.

The parity law is then yours: everything the generator produces must match. Build matching values constructively; a Gen::filter() with the pattern as predicate only works when matches are common. The export records a regexUnchecked entry in nonRepresentable — nothing vouches that a JSON Schema (ECMA-262) validator reads the PCRE pattern the same way.

Testing: Testing\RoundTrip

The parity laws, defined once next to the schema instead of being copied into every consumer's test support. Framework-agnostic: each method checks one value and throws Testing\RoundTripException on violation, so it plugs into a property test (feed it $schema->arbitrary()) or a PHPUnit loop.

assertConsumerRoundTrip() checks that hydrate($payload) succeeds, that the schema's toWire($payload) equals your wire form of the hydrated object, and that wire → hydrate → wire is lossless. Failure messages carry the stage and value kinds only, never the values. assertWireRoundTrip() needs an invertible schema: a transform without a wire inverse, or a union whose members overlap (first success wins, so the wire form may re-parse through another member), breaks it by construction — prefer Schema::discriminated().

Security

Error messages never embed input values — kinds and sizes only (get_debug_type, lengths, counts). Payloads may carry secrets; errors travel to logs and Sentry. A transform callback that throws contributes its class name only.

Strings are JSON's domain: string() rejects invalid UTF-8 up-front (mb_check_encoding), before any length, format or pattern check, so the code-point length and the pattern engine never disagree about the input. A PCRE engine failure (e.g. backtrack limit exhausted) is reported as its own error — Pattern check failed (PCRE engine error: …) — never as a plain pattern mismatch.

API

The Schema facade is the single entry point; every factory returns a SchemaType subclass, all of them @api:

Testing helpers: Testing\RoundTrip (assertParses, assertWireRoundTrip, assertConsumerRoundTrip) and Testing\RoundTripException.

Results: ParseResult / ParseError (segments → $.tags[2] and RFC 6901), SchemaException, JsonSchemaExport + NonRepresentable / NonRepresentableException (strict export).

Examples

• examples/queue-payload.php — object schema with enum/default, error paths, generation from the same schema.

Development

No PHP/Composer on the host — Docker:

See AGENTS.md for the full command set and invariants.

License

BSD-3-Clause. See LICENSE.md.