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.1"

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()->gte(0)->lte(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
`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
`literal()`	Exact value matching	LiteralSchema
`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->catch($fn);       // Handle errors and provide fallback
$schema->parse($input);    // Parse and throw on error
$schema->safeParse($input); // Parse and return Result object

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

2025 Dominik Zogg

chubbyphp / chubbyphp-parsing

Maintainers

Details