README

A lightweight PSR HTTP messages validator component for PHP applications.

The component provides infrastructure for validating PSR-7 HTTP messages against JSON Schema, composed as reusable validators and a PSR-15 middleware.

Features

• PHP 8.4+
• PSR-7 and PSR-15 compliant
• JSON Schema validation through opis/json-schema
• Strong static typing
• Immutable design
• Framework agnostic
• Composable validator chains
• Dedicated exception contract for validation failures

Installation

composer require gilsegura/psr-validator

Usage

Schema factories

A schema factory produces a JSON Schema object. Schemas can be loaded from a file or from a raw JSON string.

use Psr\Validator\SchemaFactory\FileFactory;
use Psr\Validator\SchemaFactory\RawFactory;

$fromFile = new FileFactory('/path/to/schema.json');

$fromRaw = new RawFactory('{"type": "object", "required": ["id"]}');

$schema = $fromFile();

Both factories validate their input at construction time and throw a SchemaFactoryException when the file or content is not valid.

Schema validation

SchemaValidator validates a decoded payload against a schema and returns a list of validation errors. An empty list means the payload is valid.

use Psr\Validator\Schema\SchemaValidator;

$validator = new SchemaValidator();

$errors = $validator($data, $schema);

if ($errors === []) {
    // valid
}

Each error contains its property path, JSON pointer, message, the violated constraint and the offending value.

Message validators

Message validators receive a PSR-7 message, validate it and return it unchanged on success. They throw a ValidationExceptionInterface on failure.

RequestValidator, ServerRequestValidator and ResponseValidator apply a sequence of message validators to their respective message type, while ValidatorChain composes several validators into one.

use Psr\Validator\ServerRequestValidator;

$validator = new ServerRequestValidator(
    $bodyValidator,
    $headersValidator,
);

$request = $validator($serverRequest);

Middleware

ValidationMiddleware is a PSR-15 middleware that validates the incoming server request and the outgoing response.

use Psr\Validator\Middleware\ValidationMiddleware;

$middleware = new ValidationMiddleware(
    $serverRequestValidator,
    $responseValidator,
);

$response = $middleware->process($request, $handler);

Exceptions

The component defines a single exception contract, ValidationExceptionInterface, which extends \Throwable. Every failure raised by the component implements it, so a caller can catch all validation errors through one type.

use Psr\Validator\Exception\ValidationExceptionInterface;

try {
    $request = $validator($serverRequest);
} catch (ValidationExceptionInterface $e) {
    // handle any validation failure
}

Concrete exceptions (ValidatorException, SchemaFactoryException) carry a human-readable message and the original error as previous. They do not carry transport-specific codes; mapping a failure to an HTTP status is left to the application.

License

MIT. See LICENSE.