Download the PHP package duyler/openapi without Composer

Duyler OpenAPI Validator

OpenAPI 3.2 validator for PHP 8.4+

Features

• Full OpenAPI 3.2 Support - Complete implementation of OpenAPI 3.2 specification
• JSON Schema Validation - Full JSON Schema draft 2020-12 validation with 25+ validators
• PSR-7 Integration - Works with any PSR-7 HTTP message implementation
• Request Validation - Validate path parameters, query parameters, headers, cookies, and request body
• Response Validation - Validate status codes, headers, and response bodies
• Multiple Content Types - Support for JSON, form-data, multipart, text, and XML
• Built-in Format Validators - 12+ built-in validators (email, UUID, date-time, URI, IPv4/IPv6, etc.)
• Custom Format Validators - Easily register custom format validators
• Discriminator Support - Full support for polymorphic schemas with discriminators
  • Type Coercion - Optional automatic type conversion
  • PSR-6 Caching - Cache parsed OpenAPI documents for better performance
  • PSR-14 Events - Subscribe to validation lifecycle events
  • Error Formatting - Multiple error formatters (simple, detailed, JSON)
• Webhooks Support - Validate incoming webhook requests
• Schema Registry - Manage multiple schema versions
• Validator Compilation - Generate optimized validator code

Installation

Quick Start

Basic Usage

Usage

Loading OpenAPI Specifications

PSR-7 Integration

The validator works with any PSR-7 implementation:

Caching

Enable PSR-6 caching for improved performance:

Events

Subscribe to validation events using PSR-14:

Webhooks

Validate webhook requests:

Advanced Usage

Custom Format Validators

Register custom format validators for domain-specific validation:

Type Coercion

Enable automatic type conversion for query parameters and request body:

Error Formatters

Choose from built-in error formatters or create your own:

Discriminator Validation

Validate polymorphic schemas with discriminators:

Event-Driven Validation

Subscribe to validation lifecycle events:

Schema Registry

Manage multiple API versions:

Validator Pool

The validator pool uses WeakMap to reuse validator instances:

Validator Compilation

Generate optimized validator code:

Configuration Options

Builder Methods

Example Configuration

Supported JSON Schema Keywords

The validator supports the following JSON Schema draft 2020-12 keywords:

Type Validation

• type - String, number, integer, boolean, array, object, null
• enum - Enumerated values
• const - Constant value
• nullable - Allows null values (default: enabled)

Nullable Validation

By default, the nullable: true schema keyword allows null values for a property:

This behavior is enabled by default. To disable nullable validation and treat nullable: true as not allowing null values:

String Validation

• minLength / maxLength - String length constraints
• pattern - Regular expression pattern
• format - Format validation (email, uri, uuid, date-time, etc.)

Pattern Validation

All regular expressions in schemas are validated during schema parsing. If a pattern is invalid, an InvalidPatternException is thrown.

Supported Pattern Fields

• pattern - Regular expression for string validation
• patternProperties - Object with patterns for property keys
• propertyNames - Pattern for property name validation

Pattern Delimiters

The library automatically adds delimiters (/) to patterns without them. You can specify patterns with or without delimiters:

Both variants work identically.

Pattern Validation Errors

Invalid patterns are detected early and throw descriptive errors:

Numeric Validation

• minimum / maximum - Range constraints
• exclusiveMinimum / exclusiveMaximum - Exclusive ranges
• multipleOf - Numeric division

Array Validation

• items / prefixItems - Array item validation
• minItems / maxItems - Array length constraints
• uniqueItems - Unique item requirement
• contains / minContains / maxContains - Item presence validation

Object Validation

• properties - Property definitions
• required - Required properties
• additionalProperties - Additional property rules
• minProperties / maxProperties - Property count constraints
• patternProperties - Pattern-based property validation
• propertyNames - Property name validation
• dependentSchemas - Conditional schema application

Composition Keywords

• allOf - Must match all schemas
• anyOf - Must match at least one schema
• oneOf - Must match exactly one schema
• not - Must not match schema
• if / then / else - Conditional validation

Advanced Keywords

• $ref - Schema references
• discriminator - Polymorphic schemas
• unevaluatedProperties / unevaluatedItems - Dynamic evaluation

Error Handling

Validation Exceptions

All validation errors throw ValidationException which contains detailed error information:

Common Validation Errors

Error Formatters

Choose the appropriate error formatter for your use case:

Built-in Format Validators

The following format validators are included:

String Formats

Numeric Formats

Overriding Built-in Validators

Replace built-in validators with custom implementations:

Migration from league/openapi-psr7-validator

Key Differences

Migration Examples

Before (league/openapi-psr7-validator)

After (duyler/openapi)

Requirements

• PHP 8.4 or higher - Uses modern PHP features (readonly classes, match expressions, etc.)
• PSR-7 HTTP message - psr/http-message ^2.0 (e.g., nyholm/psr7)
• PSR-6 cache - psr/cache ^3.0 (e.g., symfony/cache, cache/cache)
• PSR-14 events - psr/event-dispatcher ^1.0 (e.g., symfony/event-dispatcher)

Testing

License

MIT