PHPackages                             stougeiro/schema - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. stougeiro/schema

ActiveLibrary[Validation & Sanitization](/categories/validation)

stougeiro/schema
================

A lightweight foundation for defining and validating structured schemas in PHP.

v1.1.0(2w ago)048MITPHPPHP >=8.1

Since Feb 26Pushed 2w ago1 watchersCompare

[ Source](https://github.com/stougeiro/schema)[ Packagist](https://packagist.org/packages/stougeiro/schema)[ Fund](https://www.buymeacoffee.com/stougeiro)[ RSS](/packages/stougeiro-schema/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (6)Dependencies (2)Versions (7)Used By (0)

[![phpstan-level](https://camo.githubusercontent.com/942bdbddc7b2adea1d63ed80793492d06d72ef41911edcba33310d0745581548/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c253230392d627269676874677265656e)](https://camo.githubusercontent.com/942bdbddc7b2adea1d63ed80793492d06d72ef41911edcba33310d0745581548/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c253230392d627269676874677265656e)[![pest-php](https://camo.githubusercontent.com/6957f68f55027881b5ce079a2df50a003818f4631eb717ce685b6a3a886b6393/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d2532305061737365642d627269676874677265656e)](https://camo.githubusercontent.com/6957f68f55027881b5ce079a2df50a003818f4631eb717ce685b6a3a886b6393/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d2532305061737365642d627269676874677265656e)

Schema
======

[](#schema)

A lightweight and expressive **payload validation library** for PHP.
Designed to be minimalistic, predictable and framework‑agnostic, it provides a clean way to validate arrays and nested structures — with **clear error messages**, **type‑safe rules**, and **full path context** for deep schemas.

✨ Features
----------

[](#-features)

- **Simple, explicit schemas**:
    Define validation rules using native PHP arrays and nested `Schema` objects.
- **Full path error messages**:
    Errors show exactly *where* the validation failed:
    `Invalid required [user.address.zip]: expected [int], got ['ABC' (string)]`
- **Nested schema support**:
    Validate complex payloads with unlimited depth.
- **Optional fields**:
    Use `string:o` or `$schema->optional()` for optional nested schemas.
- **Nullable types**:
    Prefix any type with `?` (e.g., `?string`).
- **Enum & Const validation**
    `enum(a|b|c)` and `const(value)`.
- **Strict type matching**
    Supports: `string`, `int`, `float`, `bool`, `array`, `object`, `list`, `null`.
- **Zero dependencies**
    Pure PHP. No magic. No framework coupling.

---

📦 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require stougeiro/schema
```

🚀 Usage Example
---------------

[](#-usage-example)

### Simple validation

[](#simple-validation)

```
use STDW\Schema\Schema;

$schema = new Schema([
  'name' => 'string',
  'age' => 'int',
]);

$payload = [
  'name' => 'Sidney',
  'age' => 42,
];

$schema->validate($payload); // true
```

### Complex validation

[](#complex-validation)

```
/**
 * Using the global schema() helper (optional)
 *
 * For convenience, you may use the global schema() helper
 * instead of instantiating Schema manually.
 * It behaves exactly the same, but makes nested definitions easier to read
 * */

$schema = schema([
  'id' => 'int',
  'name' => 'string',
  'email' => 'string',
  'status' => 'enum(active|inactive|pending)',
  'metadata' => schema([
    'ip' => 'string',
    'userAgent' => 'string:o',
  ])->optional(),
]);

$payload = [
  'id'     => 1,
  'name'   => 'Sidney',
  'email'  => 'sidney@example.com',
  'status' => 'active',
  'metadata' => [
    'ip' => '127.0.0.1',
  ],
];

$schema->validate($payload); // true
```

🔥 Error Handling
----------------

[](#-error-handling)

`Schema::validate()` accepts an optional second parameter by reference that will contain the first validation error message when the payload is invalid:

```
use STDW\Schema\Schema;

$schema = new Schema([
  'name' => 'string',
  'age'  => 'int',
]);

$payload = [
  'name' => 'Sidney',
  'age'  => '12',
];

if ( ! $schema->validate($payload, $error)) {
  echo $error; // Invalid required [age]: expected [int], got ['12' (string)]
}
```

When using nested schemas, the error message includes the full path to the failing field:

```
$schema = new Schema([
  'template' => 'enum(user|product|payment)',
  'user' => new Schema([
    'id'    => 'int',
    'name'  => 'string',
    'email' => 'string',
  ]),
]);

$payload = [
  'template' => 'user',
  'user' => [
    'id'    => '12',
    'name'  => 'Sidney',
    'email' => 'sidney@example.com',
  ],
];

if ( ! $schema->validate($payload, $error)) {
  echo $error; // Invalid required [user.id]: expected [int], got ['12' (string)]
}
```

---

🧠 Why Schema?
-------------

[](#-why-schema)

Modern PHP applications frequently rely on arrays as data carriers — API payloads, DTOs, configuration blocks, decoded JSON, request bodies, and more. Yet PHP offers no native, structured way to validate these arrays. Most solutions introduce heavy abstractions, framework‑specific validators, annotations, attributes, or magic behavior that obscures what is actually happening.

Schema takes the opposite approach.

It embraces the simplicity of plain PHP arrays while providing a predictable, explicit and type‑safe validation layer. No hidden conventions. No reflection tricks. No framework dependencies. Just clear rules and clear errors.

Schema is built for developers who value:

- Explicitness over magic
    Every rule is visible and intentional. No guessing.
- Predictable behavior
    Validation is deterministic and easy to reason about.
- Readable error messages
    Full path context (user.address.zip) makes debugging payloads effortless.
- Nested structure support
    Deeply nested schemas behave exactly like shallow ones.
- Zero dependencies
    Works anywhere — CLI scripts, microservices, APIs, legacy systems, modern frameworks.
- Type safety and clarity
    Native types, nullable types, optional fields, enums, const values — all expressed simply.

Schema aims to be a small, expressive and reliable tool that solves one problem extremely well: validating structured data in PHP without unnecessary complexity.

---

🤝 Contributions
---------------

[](#-contributions)

Contributions are welcome. Feel free to open issues or submit pull requests.

[![](https://camo.githubusercontent.com/0cf29a542375e1a46e84d8bf5805a4e5c0a6ee98b6547ccdc0c55eed49d99c69/68747470733a2f2f63646e2e6275796d6561636f666665652e636f6d2f627574746f6e732f76322f64656661756c742d79656c6c6f772e706e67)](https://www.buymeacoffee.com/stougeiro)

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance97

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~177 days

Recently: every ~171 days

Total

6

Last Release

15d ago

Major Versions

v0.4.0 → v1.0.02026-07-29

PHP version history (2 changes)v0.1.0PHP ^8.1

v1.0.0PHP >=8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3516412?v=4)[S.Tougeiro](/maintainers/stougeiro)[@stougeiro](https://github.com/stougeiro)

---

Top Contributors

[![stougeiro](https://avatars.githubusercontent.com/u/3516412?v=4)](https://github.com/stougeiro "stougeiro (27 commits)")

---

Tags

phpschemavalidationdatacleanarchitecturestructureddddesigndomaintypedData Modelingtyped schema

###  Code Quality

TestsPest

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/stougeiro-schema/health.svg)

```
[![Health](https://phpackages.com/badges/stougeiro-schema/health.svg)](https://phpackages.com/packages/stougeiro-schema)
```

###  Alternatives

[evaisse/php-json-schema-generator

A JSON Schema Generator.

18321.8k1](/packages/evaisse-php-json-schema-generator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)