Download the PHP package webman/validation without Composer

English | 中文

Webman Validation

Webman's validation component, based on illuminate/validation, provides manual validation, annotation-based validation, parameter-level validation, and reusable rule sets.

Installation

Basic Concepts

• Rule Set Reuse: Define reusable rules, messages, attributes, and scenes by extending support\validation\Validator, which can be reused in manual and annotation validation.
• Annotation (Attribute) Validation - Method-Level: Use the PHP 8 attribute #[Validate] to bind validation to controller methods.
• Annotation (Attribute) Validation - Parameter-Level: Use the PHP 8 attribute #[Param] to bind validation to controller method parameters.
• Exception Handling: Throws support\validation\ValidationException on validation failure; the exception class is configurable via config.
• Database Validation: If database validation is involved, you need to install composer require webman/database.

Manual Validation

Basic Usage

Note
validate() will throw support\validation\ValidationException if validation fails. If you prefer not to throw exceptions, use fails() as shown below.

Custom Messages and Attributes

Validate Without Exception (Get Error Messages)

If you don't want exceptions, use fails() and read errors from the MessageBag:

Rule Set Reuse (Custom Validator)

Manual Validation Reuse

Use Scenes (Optional)

Scenes are optional. They are only used when you call withScene(...) to validate a subset of fields.

Annotation Validation (Method-Level)

Direct Rules

Reusing Rule Sets

Multiple Validation Overlays

Validation Data Source

Use in to specify where validation data comes from:

• query – HTTP query parameters from $request->get()
• body – HTTP body from $request->post()
• path – Path/route parameters from $request->route->param()

in can be a string or array; when it's an array, values are merged in order and later sources override earlier ones. When in is omitted, it defaults to the equivalent of ['query', 'body', 'path'].

Parameter-Level Validation (Param)

Basic Usage

Validation Data Source

Parameter-level validation also supports the in parameter to specify data source:

Rules Support String or Array

Custom Messages / Attribute

Reusing Rule Constants

Method-Level + Parameter-Level Mixing

Automatic Rule Inference (Signature-Based)

When a method uses #[Validate], or any parameter on that method uses #[Param], this package will infer and auto-complete basic validation rules from the PHP method signature, then merge them with your existing rules and run validation.

Examples: #[Validate] Equivalent Expansion

1) Enable #[Validate] without writing rules:

Equivalent to:

2) Only partial rules provided, the rest is inferred:

Equivalent to:

3) Default values / nullable types:

Equivalent to:

Exception Handling

Default Exception

Validation failure throws support\validation\ValidationException, which inherits from Webman\Exception\BusinessException and does not log errors.

Default response behavior is handled by BusinessException::render():

• Non-JSON requests: return a plain string message, e.g. token is required.
• JSON requests: return JSON response, e.g. {"code": 422, "msg": "token is required.", "data":....}

Customize with a custom exception

• Global config: exception in config/plugin/webman/validation/app.php

Multi-Language Support

The component includes built-in Chinese and English language packs and supports project overrides. Loading order:

1. Project language pack resource/translations/{locale}/validation.php
2. Component built-in vendor/webman/validation/resources/lang/{locale}/validation.php
3. Illuminate built-in English (fallback)

Note
The default language of webman is configured in config/translation.php, and it can also be changed using the function locale('en');.

Local Override Example

resource/translations/en/validation.php

Middleware Auto-Loading

After installation, the component automatically loads the validation middleware via config/plugin/webman/validation/middleware.php, no manual registration required.

CLI Generator

Use make:validator to generate a validator class (generated under app/validation by default).

Tip
You need to install composer require webman/console

Basic

• Generate an empty template

• Overwrite if the file already exists

Generate rules from a table

• Generate rules from a table schema (infers $rules from column type/nullability/length; default excluded columns depend on ORM: laravel uses created_at/updated_at/deleted_at, thinkorm uses create_time/update_time/delete_time)

• Select a database connection (multi-connection)

Scenes

• Generate CRUD scenes: create/update/delete/detail

The update scene includes the primary key (to locate the record) plus the other fields; delete/detail include only primary key fields by default.

ORM selection (laravel(illuminate/database) vs think-orm)

• Auto (default): uses the available ORM; if both exist, defaults to illuminate
• Force

Example

Unit Testing

Enter the webman/validation root directory and execute:

All Validation Rules Reference

Available Validation Rules

[!IMPORTANT]

• Webman Validation is based on illuminate/validation, with rule names consistent with Laravel, and the rules themselves have no Webman-specific modifications.
• The middleware validates data from $request->all() (GET+POST) by default and merges route parameters, excluding uploaded files; for file-related rules, manually merge $request->file() into the data or call Validator::make manually.
• current_password depends on authentication guards, exists/unique depend on database connections and query builders, and these rules are unavailable without integrating the corresponding components.

The following lists all available validation rules and their functions:

Boolean Values

Strings

Numbers

Arrays

Dates

Files

Database

Utilities

accepted

The field under validation must be "yes", "on", 1, "1", true, or "true". This is commonly used for scenarios like confirming agreement to terms of service.

accepted_if:anotherfield,value,...

The field under validation must be "yes", "on", 1, "1", true, or "true" when another field equals the specified value. This is useful for conditional agreement scenarios.

active_url

The field under validation must have a valid A or AAAA record. The rule first extracts the hostname using parse_url and then validates it with dns_get_record.

after:date

The field under validation must be a value after the given date. The date is converted to a valid DateTime using strtotime:

You can also pass another field name for comparison:

You can use the fluent date rule builder:

afterToday and todayOrAfter can conveniently express "must be after today" or "must be today or later":

after_or_equal:date

The field under validation must be after or equal to the given date. For more details, see the after rule.

You can use the fluent date rule builder:

anyOf

Rule::anyOf allows specifying "pass if any one of the rule sets is satisfied". For example, the following rule means username is either an email address or an alphanumeric string with underscores/dashes of at least 6 characters:

alpha

The field under validation must consist of Unicode letters (\p{L} and \p{M}).

To allow only ASCII (a-z, A-Z), add the ascii option:

alpha_dash

The field under validation can only contain Unicode alphanumeric characters (\p{L}, \p{M}, \p{N}), as well as ASCII dashes (-) and underscores (_).

To allow only ASCII (a-z, A-Z, 0-9), add the ascii option:

alpha_num

The field under validation can only contain Unicode alphanumeric characters (\p{L}, \p{M}, \p{N}).

To allow only ASCII (a-z, A-Z, 0-9), add the ascii option:

array

The field under validation must be a PHP array.

When the array rule includes additional parameters, the keys in the input array must be in the parameter list. In the example, the admin key is not in the allowed list, so it is invalid:

It is recommended to explicitly specify the allowed keys for arrays in actual projects.

ascii

The field under validation can only contain 7-bit ASCII characters.

bail

When the first validation rule for a field fails, stop validating the other rules for that field.

This rule only affects the current field. For "stop on first failure globally", use Illuminate's validator directly and call stopOnFirstFailure().

before:date

The field under validation must be before the given date. The date is converted to a valid DateTime using strtotime. Similar to the after rule, you can pass another field name for comparison.

You can use the fluent date rule builder:

beforeToday and todayOrBefore can conveniently express "must be before today" or "must be today or earlier":

before_or_equal:date

The field under validation must be before or equal to the given date. The date is converted to a valid DateTime using strtotime. Similar to the after rule, you can pass another field name for comparison.

You can use the fluent date rule builder:

between:min,max

The field under validation must have a size between the given min and max (inclusive). Strings, numbers, arrays, and files are evaluated using the same rules as size.

boolean

The field under validation must be convertible to a boolean value. Acceptable inputs include true, false, 1, 0, "1", "0".

You can use the strict parameter to allow only true or false:

confirmed

The field under validation must have a matching field {field}_confirmation. For example, if the field is password, password_confirmation is required.

You can also specify a custom confirmation field name, such as confirmed:repeat_username, which requires repeat_username to match the current field.

contains:foo,bar,...

The field under validation must be an array and must contain all the given parameter values. This rule is often used for array validation and can be constructed using Rule::contains:

doesnt_contain:foo,bar,...

The field under validation must be an array and must not contain any of the given parameter values. You can use Rule::doesntContain to construct:

current_password

The field under validation must match the current authenticated user's password. You can specify the authentication guard via the first parameter:

[!WARNING] This rule depends on the authentication component and guard configuration; do not use it without integrating authentication.

date

The field under validation must be a valid (non-relative) date recognized by strtotime.

date_equals:date

The field under validation must equal the given date. The date is converted to a valid DateTime using strtotime.

date_format:format,...

The field under validation must match one of the given formats. Use either date or date_format. This rule supports all formats of PHP DateTime.

You can use the fluent date rule builder:

decimal:min,max

The field under validation must be a number with the specified number of decimal places:

declined

The field under validation must be "no", "off", 0, "0", false, or "false".

declined_if:anotherfield,value,...

The field under validation must be "no", "off", 0, "0", false, or "false" when another field equals the specified value.

different:field

The field under validation must be different from field.

digits:value

The field under validation must be an integer with a length of value.

digits_between:min,max

The field under validation must be an integer with a length between min and max.

dimensions

The field under validation must be an image and satisfy the dimension constraints:

Available constraints: _minwidth, _maxwidth, _minheight, _maxheight, width, height, ratio.

ratio is the aspect ratio, which can be expressed as a fraction or float:

Due to the many parameters in this rule, it is recommended to use Rule::dimensions to construct:

distinct

When validating an array, the field values must not be duplicated:

By default, loose comparison is used. For strict comparison, add strict:

You can add ignore_case to ignore case differences:

doesnt_start_with:foo,bar,...

The field under validation must not start with the specified values.

doesnt_end_with:foo,bar,...

The field under validation must not end with the specified values.

email

The field under validation must be a valid email address. This rule relies on egulias/email-validator, defaulting to RFCValidation, but other validation methods can be specified:

Available validation methods:

You can use the fluent rule builder:

[!WARNING] dns and spoof require the PHP intl extension.

encoding:encoding_type

The field under validation must match the specified character encoding. This rule uses mb_check_encoding to detect the encoding of files or strings. It can be used with the file rule builder:

ends_with:foo,bar,...

The field under validation must end with one of the specified values.

enum

Enum is a class-based rule used to validate if the field value is a valid enum value. Pass the enum class name during construction. For validating basic type values, use Backed Enum:

You can use only/except to restrict enum values:

You can use when for conditional restrictions:

exclude

The field under validation will be excluded from the data returned by validate/validated.

exclude_if:anotherfield,value

The field under validation will be excluded from the data returned by validate/validated when anotherfield equals value.

For complex conditions, use Rule::excludeIf:

exclude_unless:anotherfield,value

The field under validation will be excluded from the data returned by validate/validated unless anotherfield equals value. If value is null (e.g., exclude_unless:name,null), the field is retained only if the comparison field is null or does not exist.

exclude_with:anotherfield

The field under validation will be excluded from the data returned by validate/validated when anotherfield exists.

exclude_without:anotherfield

The field under validation will be excluded from the data returned by validate/validated when anotherfield does not exist.

exists:table,column

The field under validation must exist in the specified database table.

Basic Usage of Exists Rule

If column is not specified, the field name is used by default. Thus, this example validates if the state column exists in the states table.

Specifying a Custom Column Name

You can append the column name after the table name:

To specify a database connection, prepend the connection name to the table:

You can also pass a model class name, and the framework will resolve the table name:

To customize query conditions, use the Rule rule builder:

You can also specify the column name directly in Rule::exists:

When validating if a group of values exists, combine with the array rule:

When array and exists coexist, a single query is generated to validate all values.

extensions:foo,bar,...

The uploaded file's extension must be in the allowed list:

[!WARNING] Do not rely solely on extension validation for file types; it is recommended to use it with mimetypes.

file

The field under validation must be a successfully uploaded file.

filled

When the field exists, its value must not be empty.

gt:field

The field under validation must be greater than the given field or value. The two fields must be of the same type. Strings, numbers, arrays, and files are evaluated using the same rules as size.

gte:field

The field under validation must be greater than or equal to the given field or value. The two fields must be of the same type. Strings, numbers, arrays, and files are evaluated using the same rules as size.

hex_color

The field under validation must be a valid hexadecimal color value.

image

The field under validation must be an image (jpg, jpeg, png, bmp, gif, or webp).

[!WARNING] SVG is not allowed by default due to XSS risks. To allow it, add allow_svg: image:allow_svg.

in:foo,bar,...

The field under validation must be in the given list of values. You can use Rule::in to construct:

When combined with the array rule, every value in the input array must be in the in list:

in_array:anotherfield.*

The field under validation must exist in the value list of anotherfield.

in_array_keys:value.*

The field under validation must be an array and must contain at least one of the given values as a key:

integer

The field under validation must be an integer.

You can use the strict parameter to require the field type to be integer; string representations of integers will be considered invalid:

[!WARNING] This rule only checks if it passes PHP's FILTER_VALIDATE_INT; to enforce numeric types, use it with numeric.

ip

The field under validation must be a valid IP address.

ipv4

The field under validation must be a valid IPv4 address.

ipv6

The field under validation must be a valid IPv6 address.

json

The field under validation must be a valid JSON string.

lt:field

The field under validation must be less than the given field. The two fields must be of the same type. Strings, numbers, arrays, and files are evaluated using the same rules as size.

lte:field

The field under validation must be less than or equal to the given field. The two fields must be of the same type. Strings, numbers, arrays, and files are evaluated using the same rules as size.

lowercase

The field under validation must be lowercase.

list

The field under validation must be a list array. The keys in a list array must be consecutive numbers from 0 to count($array) - 1.

mac_address

The field under validation must be a valid MAC address.

max:value

The field under validation must be less than or equal to value. Strings, numbers, arrays, and files are evaluated using the same rules as size.

max_digits:value

The field under validation must be an integer with a length not exceeding value.

mimetypes:text/plain,...

The file's MIME type must be in the list:

The MIME type is guessed by reading the file content, which may differ from the client-provided MIME.

mimes:foo,bar,...

The file's MIME type must correspond to the given extension:

Although the parameters are extensions, this rule reads the file content to determine the MIME. The extension-to-MIME mapping is from:

https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types

MIME Types and Extensions

This rule does not validate if the "filename extension" matches the "actual MIME". For example, mimes:png will consider photo.txt with PNG content as valid. To validate extensions, use extensions.

min:value

The field under validation must be greater than or equal to value. Strings, numbers, arrays, and files are evaluated using the same rules as size.

min_digits:value

The field under validation must be an integer with a length of at least value.

multiple_of:value

The field under validation must be a multiple of value.

missing

The field under validation must not exist in the input data.

missing_if:anotherfield,value,...

The field under validation must not exist when anotherfield equals any value.

missing_unless:anotherfield,value

The field under validation must not exist unless anotherfield equals any value.

missing_with:foo,bar,...

The field under validation must not exist when any of the specified fields exist.

missing_with_all:foo,bar,...

The field under validation must not exist when all specified fields exist.

not_in:foo,bar,...

The field under validation must not be in the given list of values. You can use Rule::notIn to construct:

not_regex:pattern

The field under validation must not match the given regular expression.

This rule uses PHP preg_match. The regex must include delimiters, e.g., 'email' => 'not_regex:/^.+$/i'.

[!WARNING] When using regex / not_regex, if the regex contains |, it is recommended to declare rules in array form to avoid conflicts with the | separator.

nullable

The field under validation may be null.

numeric

The field under validation must be numeric.

You can use the strict parameter to allow only integer or float types; numeric strings will be considered invalid:

present

The field under validation must exist in the input data.

present_if:anotherfield,value,...

The field under validation must exist when anotherfield equals any value.

present_unless:anotherfield,value

The field under validation must exist unless anotherfield equals any value.

present_with:foo,bar,...

The field under validation must exist when any of the specified fields exist.

present_with_all:foo,bar,...

The field under validation must exist when all specified fields exist.

prohibited

The field under validation must be missing or empty. A field is "empty" if:

prohibited_if:anotherfield,value,...

The field under validation must be missing or empty when anotherfield equals any value. A field is "empty" if:

For complex conditions, use Rule::prohibitedIf:

prohibited_if_accepted:anotherfield,...

The field under validation must be missing or empty when anotherfield is "yes", "on", 1, "1", true, or "true".

prohibited_if_declined:anotherfield,...

The field under validation must be missing or empty when anotherfield is "no", "off", 0, "0", false, or "false".

prohibited_unless:anotherfield,value,...

The field under validation must be missing or empty unless anotherfield equals any value. A field is "empty" if:

prohibits:anotherfield,...

When the field under validation exists and is not empty, all fields in anotherfield must be missing or empty. A field is "empty" if:

regex:pattern

The field under validation must match the given regular expression.

This rule uses PHP preg_match. The regex must include delimiters, e.g., 'email' => 'regex:/^.+@.+$/i'.

[!WARNING] When using regex / not_regex, if the regex contains |, it is recommended to declare rules in array form to avoid conflicts with the | separator.

required

The field under validation must exist and not be empty. A field is "empty" if:

required_if:anotherfield,value,...

The field under validation must exist and not be empty when anotherfield equals any value.

For complex conditions, use Rule::requiredIf:

required_if_accepted:anotherfield,...

The field under validation must exist and not be empty when anotherfield is "yes", "on", 1, "1", true, or "true".

required_if_declined:anotherfield,...

The field under validation must exist and not be empty when anotherfield is "no", "off", 0, "0", false, or "false".

required_unless:anotherfield,value,...

The field under validation must exist and not be empty unless anotherfield equals any value. If value is null (e.g., required_unless:name,null), the field is allowed to be empty only if the comparison field is null or does not exist.

required_with:foo,bar,...

The field under validation must exist and not be empty when any specified field exists and is not empty.

required_with_all:foo,bar,...

The field under validation must exist and not be empty when all specified fields exist and are not empty.

required_without:foo,bar,...

The field under validation must exist and not be empty when any specified field is empty or does not exist.

required_without_all:foo,bar,...

The field under validation must exist and not be empty when all specified fields are empty or do not exist.

required_array_keys:foo,bar,...

The field under validation must be an array and must contain at least the specified keys.

sometimes

Apply subsequent validation rules only when the field exists. Commonly used for fields that are "optional but must be valid if present":

same:field

The field under validation must be the same as field.

size:value

The field under validation must have a size equal to the given value. For strings, it is the character count; for numbers, it is the specified integer (use with numeric or integer); for arrays, it is the element count; for files, it is the size in KB. Example:

starts_with:foo,bar,...

The field under validation must start with one of the specified values.

string

The field under validation must be a string. To allow null, use with nullable.

timezone

The field under validation must be a valid timezone identifier (from DateTimeZone::listIdentifiers). Parameters supported by this method can be passed:

unique:table,column

The field under validation must be unique in the specified table.

Specifying Custom Table/Column Names:

You can directly specify the model class name:

You can specify the column name (defaults to the field name if not specified):

Specifying Database Connection:

Ignoring a Specific ID:

[!WARNING] ignore should not receive user input; only use system-generated unique IDs (auto-increment IDs or model UUIDs), otherwise there may be SQL injection risks.

You can also pass a model instance:

If the primary key is not id, specify the primary key name:

By default, the field name is used as the unique column, but you can specify the column name:

Adding Extra Conditions:

Ignoring Soft-Deleted Records:

If the soft-delete column name is not deleted_at:

uppercase

The field under validation must be uppercase.

url

The field under validation must be a valid URL.

You can specify allowed protocols:

ulid

The field under validation must be a valid ULID.

uuid

The field under validation must be a valid RFC 9562 UUID (versions 1, 3, 4, 5, 6, 7, or 8).

You can specify the version: