Download the PHP package stougeiro/schema without Composer

Schema

A lightweight structural gate for PHP payloads. Validates the shape before business logic validates the content.

✨ Features

• Structural gate pattern:
  Validates structure before business logic. A clean, intentional order.

• 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, number, numeric,
  bool, boolean, array, list, object, null,
  resource, callable, enum(a|b|c), const(value).

• Zero dependencies
  Pure PHP. No magic. No framework coupling.

🚦 What Schema Is

Schema validates the structure of your data — not the business rules.

It answers one question: "Is this payload shaped correctly?"

• Does the field exist?
• Is it the right type?
• Is the nesting correct?

It does NOT answer: "Is this value meaningful?"

• Is this email deliverable?
• Is this ID registered?
• Is this amount within limits?

That's a different concern, handled elsewhere.

🏗️ The Gate Pattern

Structural validation is cheap. Business validation is richer.

Schema runs first — not because it's faster, but because it's the right order. A malformed structure doesn't need business rules. A valid structure is ready for them.

Schema doesn't replace business validation — it precedes it.

📦 Installation

Install via Composer:

🚀 Usage

Schema supports multiple type validations. Before diving into examples, it's worth understanding the nuances between similar types:

bool vs boolean:

• bool is permissive — accepts true, false, 1, 0, "true", "false"
• boolean is strict — accepts only true and false

int / float vs number vs numeric:

• int and float are strict — native types only
• number accepts both int and float
• numeric also accepts numeric strings like "123" or "3.14"

array vs list:

• array accepts any array
• list accepts only sequential arrays (no gaps in keys)

Simple validation

Complex validation

🔥 Error Handling

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

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

⚡ Performance

Schema is designed to be lightweight. Zero dependencies, minimal overhead, static caching for repeated patterns.

For typical API payloads, validation runs almost instantly — fast enough to be a transparent gate in any request lifecycle.

Schema doesn't aim to be the fastest validator. It aims to be the right first step — structural validation before business validation, at a negligible cost.

🧠 Why Schema?

Modern PHP applications pass arrays everywhere — API payloads, configuration blocks, decoded JSON, event messages. PHP offers no native way to validate these structures.

Schema fills that gap — not as a business validator, but as a structural gatekeeper.

Why a gate?

Because structure should be confirmed before business rules apply. A payload with the wrong shape doesn't need business evaluation. It deserves a fast, clear rejection.

What Schema guarantees:

• The payload has the expected fields
• Each field has the expected type
• Nested structures match the expected shape
• Errors point exactly to where the structure breaks

What Schema leaves to you:

• Whether the email is deliverable
• Whether the amount is within limits
• Whether the ID exists in your database

Schema is a gate — it opens for well-shaped data and closes for malformed payloads. What happens after the gate is your domain's responsibility.

🤝 Contributions

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