README

Description

Allows parsing data of various structures, meaning the population and validation of data into a defined structure. For example, converting an API request into a Data Transfer Object (DTO).

Heavily inspired by the well-known TypeScript library zod.

Requirements

php: ^8.3

Installation

Through Composer as chubbyphp/chubbyphp-parsing.

composer require chubbyphp/chubbyphp-parsing "^2.6"

Quick Start

use Chubbyphp\Parsing\Parser;

$p = new Parser();

// Define a schema
$userSchema = $p->object([
    'name' => $p->string()->minLength(1)->maxLength(100),
    'email' => $p->string()->email(),
    'age' => $p->int()->minimum(0)->maximum(150),
]);

// Parse and validate data
$user = $userSchema->parse([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'age' => 30,
]);

Schema Types

Primitives

Schema	Description	Documentation
`string()`	String validation with length, pattern, format checks	StringSchema
`int()`	Integer validation with numeric constraints	IntSchema
`float()`	Float validation with numeric constraints	FloatSchema
`bool()`	Boolean validation	BoolSchema
`dateTime()`	DateTime validation with range constraints	DateTimeSchema

Complex Types

Schema	Description	Documentation
`array()`	Arrays with item validation	ArraySchema
`assoc()`	Associative arrays with field schemas	AssocSchema
`object()`	Objects/DTOs with field schemas	ObjectSchema
`tuple()`	Fixed-length arrays with positional types	TupleSchema
`record()`	Key-value maps with uniform value types	RecordSchema

Union Types

Schema	Description	Documentation
`union()`	Value matches one of several schemas	UnionSchema
`discriminatedUnion()`	Tagged unions with a discriminator field	DiscriminatedUnionSchema

Special Types

Schema	Description	Documentation
`const()`	Exact value matching	ConstSchema
`backedEnum()`	PHP BackedEnum validation	BackedEnumSchema
`lazy()`	Recursive/self-referencing schemas	LazySchema
`respectValidation()`	Integration with Respect/Validation	RespectValidationSchema

Common Schema Methods

All schemas support these methods:

$schema->nullable();              // Allow null values
$schema->default($value);         // Provide default when input is null
$schema->preParse($fn);           // Transform input before parsing
$schema->postParse($fn);          // Transform output after parsing
$schema->parse($input);           // Parse and throw on error
$schema->safeParse($input);       // Parse and return Result object
$schema->catch($fn);              // Handle errors and provide fallback

Error Handling

use Chubbyphp\Parsing\ErrorsException;

try {
    $schema->parse($input);
} catch (ErrorsException $e) {
    $e->errors->jsonSerialize();                   // JSON structure
    $e->errors->toApiProblemInvalidParameters();   // RFC 7807 format
    $e->errors->toTree();                          // Hierarchical structure
}

See Error Handling for detailed documentation.

Documentation

Schema Types: doc/Schema/
Error Handling: doc/ErrorHandling.md
Migration: 1.x to 2.x

Copyright

2026 Dominik Zogg

chubbyphp/chubbyphp-parsing

包简介

关键字：

README 文档