Download the PHP package mewtonium/vanguard without Composer

Vanguard - PHP Attribute-Based Validation Library

[!CAUTION] 🛑 This package is intended for demo purposes only and is not suitable for production use. Please do not use it in live or production environments. 🛑

Vanguard is a simple, attribute-based validation library for PHP, providing a clean and easy way to validate data using attributes on class properties.

Features

• Simple attribute-based validation.
• Dependency-free - no external libraries required.
• Supports common validation rules, with more to be added in future.
  • Comparison and range-based rules (Between, GreaterOrEqual, GreaterThan, LessOrEqual, LessThan) also validate strings as dates when applicable.
  • Equal can check strings as either a date string, or a standard value.
  • Scalar rules such as Url, Numeric, Integer, Boolean, Alpha, AlphaNum and Regex.
• Write your own rules by implementing a simple contract — see Writing Custom Rules.
• Supports for a custom error message on any rule.

Installation

Usage

Add the Vanguard trait to any class, add a few Rule attributes to properties and call validate() - simple!

Validation Rules

Note: Vanguard performs validation only. It does not sanitise or modify your input data in any way — ensure you handle sanitisation separately, if needed.

Here are all the currently supported validation rules:

• Alpha
• AlphaNum
• Between
• Boolean
• Email
• Equal
• GreaterOrEqual
• GreaterThan
• In
• Integer
• LessOrEqual
• LessThan
• MaxLength
• MinLength
• Numeric
• Regex
• Required
• Url

Alpha

Validates that the value contains letters only.

AlphaNum

Validates that the value contains letters and numbers only.

Between

Validates whether the value lies within the inclusive range of min and max.

Boolean

Validates that the value is a boolean. Accepts true, false, 1, 0, '1' and '0'.

Email

Validates that the value is a valid email address using filter_var.

Equal

Validates if the value is equal to the given value. If both are strings and resemble date strings, it compares them as dates.

GreaterOrEqual

Validates if the value is greater than or equal to the given value.

GreaterThan

Validates if the value is strictly greater than the given value.

In

Validate that the value exists within a predefined list of values.

Integer

Validates that the value is an integer (or an integer-like string). Booleans are rejected.

LessOrEqual

Checks if the value is less than or equal to the given value.

LessThan

Validates if the value is strictly less than the given value.

MaxLength

Validates that a string or array has no more than the given number of characters or items.

MinLength

Validates that a string or array has at least the given number of characters or items.

Numeric

Validates that the value is numeric (an integer, float, or numeric string).

Regex

Validates that the value matches a given PCRE pattern.

Note: The pattern is supplied by you in the form definition — never derive it from end-user input. Authoring a pattern vulnerable to catastrophic backtracking (ReDoS) is your responsibility.

Required

Validate that the value is not null, an empty string, or an empty array.

Url

Validates that the value is a valid URL using filter_var.

Writing Custom Rules

Write your own rule by extending the abstract BaseRule class and adding the #[\Attribute(\Attribute::TARGET_PROPERTY)] attribute. BaseRule gives you the injected $field/$value properties and the custom-message plumbing — you only implement passes() and the default message():

BaseRule implements the Mewtonium\Vanguard\Contracts\Rule contract (passes() + message()); a non-null message passed to the rule takes priority over the default returned by message().

Here's another example — a rule that uses a regular expression to reject values with leading or trailing whitespace:

Preparing values before validation

A rule may implement the Mewtonium\Vanguard\Contracts\PreparesValue contract to transform a value before passes() runs. Vanguard calls prepare(mixed $value): mixed and validates the returned value, so $this->value inside passes() is the prepared value. This is how the built-in date rules cast Y-m-d strings to DateTimeInterface.

A date-based rule can reuse the Mewtonium\Vanguard\Concerns\PreparesDate trait, which implements prepare() for you. The property's own value is prepared automatically; prepare any date arguments you accept in the constructor, then compare them in passes():

Strict vs. lenient date parsing

By default the PreparesDate trait is strict: a string that isn't a valid date throws a \DateException. Set $lenient = true when your rule should accept plain, non-date strings and date strings. An unrecognised string is then left untouched instead of throwing an exception.

Which one you want depends on what the rule does. For example:

• Equal is lenient. It checks equality, which is just as valid for a plain string ('active') as for a date ('2025-01-01'), so non-date strings have to be allowed through.
• GreaterThan, LessThan, Between (and the like) are strict. "Greater than" only makes sense for numbers and dates, so a non-date string is treated as a mistake and rejected.

If your rule needs lenient mode, set it in the constructor before preparing any values:

Custom Validation Message

All validation rules support a custom error message. You can specify a custom message by passing the message argument:

Handling Validation Errors

When validation fails, errors are stored in an ErrorBag instance:

Available methods:

Example Output

For the example in the "Usage" section, calling $errors->all() would return:

Changelog

See the full changelog here.

License

This project is open-source and available under the MIT license.