validators

Utopia Validators is a lightweight, dependency-free PHP library that provides a consistent, testable API for common HTTP-oriented validation concerns. It ships more than two dozen validator classes covering text length and character sets, numeric ranges, booleans, network primitives such as IP, Host, Hostname, Domain, and URL, plus structured JSON shape checks. Every validator implements the same isValid, getDescription, getType, and isArray contract, so validators can be swapped or composed interchangeably.

Composition helpers such as AllOf, AnyOf, NoneOf, and Multiple, along with wrappers like Nullable, let developers build complex validation rules out of simple primitives without writing custom glue code. The library also includes a purpose-built FCM validator for Google service-account credentials used with Firebase Cloud Messaging’s HTTP v1 API, reflecting its origin inside API frameworks like Utopia and Appwrite, where request payloads need strict, descriptive validation before they reach business logic.

What You Get

• 25+ validator classes covering text, numeric, boolean, network, and JSON input types
• A shared Validator contract (isValid, getDescription, getType, isArray) every rule implements
• Composition helpers (AllOf, AnyOf, NoneOf, Multiple) for combining simple rules into complex validation logic
• Network-focused validators for IP, Host, Hostname, Domain, and URL values
• JSON shape validators, including an object/array-aware JSON validator and an FCM service-account credential validator

Common Use Cases

• Validating REST API request payloads before they reach controller logic
• Enforcing input constraints (length, character set, numeric range) on user-submitted form fields
• Checking network-facing values such as hostnames, domains, and URLs supplied in configuration or API requests
• Validating Firebase Cloud Messaging service-account JSON before using it to send push notifications

Under The Hood

Architecture A single abstract Validator base class defines a minimal four-method contract (isValid, getDescription, getType, isArray) that every concrete rule under the Validator namespace implements directly, with no manager or registry layer in between. Consumers instantiate and call validators directly, or chain them through the Multiple, AllOf, AnyOf, and NoneOf composition classes, which recursively delegate isValid to an internal array of child Validator instances. The JSON namespace mirrors the same pattern for structured payloads, decoding JSON strings internally before applying shape and field checks. Because every validator is self-contained with no shared mutable state or external dependencies, adding a new validator type requires no changes elsewhere, giving the codebase a flat, additive, low-coupling design.

Tech Stack The library targets PHP 8.5+ exclusively (composer.json requires php >=8.5) with zero runtime dependencies, using PSR-4 autoloading to map the Utopia namespace to src/. Testing runs on PHPUnit via phpunit.xml, and static analysis runs on PHPStan via phpstan.neon, including a project-authored PHPStan extension that restricts test code to assertSame over assertEquals. There is no build step, bundler, or external HTTP/database client involved; validation logic relies purely on PHP’s standard library (preg_match, filter_var, json_decode, mb_strlen). This specific GitHub repository mirrors a monorepo package, so day-to-day CI workflows run upstream rather than in this repo directly.

Code Quality Dedicated PHPUnit test files mirror the source tree one-to-one, giving comprehensive per-class coverage across text, numeric, network, and JSON validators. Code uses declare(strict_types=1) throughout along with typed properties and constructor promotion, and static analysis is enforced through PHPStan plus a custom rule banning assertEquals in favor of the stricter assertSame. Error handling favors returning descriptive strings from getDescription() over throwing exceptions, a deliberate and consistently applied pattern rather than a swallowed-error shortcut. Naming is self-documenting and consistent throughout (Text, Range, WhiteList, AllOf), with shared type constants centralized on the base class.

API Design The public API is highly ergonomic: every validator is instantiated directly with constructor arguments, PHP 8 named-argument syntax is supported for clarity, and each class exposes exactly the same four methods regardless of complexity. getDescription() doubles as a built-in human-readable error message generator, removing boilerplate many validation libraries leave to the caller. Composed validators (Multiple, AllOf, AnyOf, NoneOf) implement the identical interface as leaf validators, so calling code never special-cases composition. The README documents installation, basic usage, the full validator list, and a worked JSON shape-validation example, which is unusually thorough documentation for a package this size.