chubbyphp-parsing

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

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' => '[email protected]',
    '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
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

2026 Dominik Zogg