PHPackages                             wscore/validator - 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. wscore/validator

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

wscore/validator
================

Validation and filtration for values such as form input.

0.3.3(6y ago)19[5 issues](https://github.com/WScore/Validator/issues)MITPHP

Since Jul 25Pushed 6y ago1 watchersCompare

[ Source](https://github.com/WScore/Validator)[ Packagist](https://packagist.org/packages/wscore/validator)[ RSS](/packages/wscore-validator/feed)WikiDiscussions master Synced 3d ago

READMEChangelogDependencies (1)Versions (10)Used By (0)

Validation
==========

[](#validation)

A validation component for,

- a single value as well as arrays,
- nested form inputs,
- one-to-many form inputs, and
- multi-byte support (i.e. Japanese),

### License

[](#license)

MIT License

### Installation

[](#installation)

t.b.w.

Simple Usage
------------

[](#simple-usage)

### Validating a Value

[](#validating-a-value)

Create a `ValidationBuilder` instance, then create a validator;

```
$vb = new ValidatorBuilder();
$validator = $vb->text([
    StringLength::class => ['max' => 12],
]);
```

- To create a validation, do: `$vb->{type}($option_array)`.
    - `type`: type of validation, as defined in the subsequent section.
    - `option_array`: array of options. `StringLength` is a filter (also called validator).
        - `multiple`: boolean. optional. to validate against a multiple (i.e. array) value.
        - `type`: string. optional. can specify type in the option as well.
        - `filters`: array. deprecated way to specify filters.
        - all other options are considered as filters.

The `$result` contains the validation status and validated value.

```
$result = $validator->verify($value);
if ($result->isValid()) {
    echo $result->value(); // validated value
} else {
    var_dump($result->getErrorMessage()); // error messages
}
```

### Validating a Form Input

[](#validating-a-form-input)

```
$form = $vb->form()
    ->add('name', $vb->text([
        Required::class,
        StringCases::class => [StringCases::TO_LOWER, StringCases::UC_WORDS],
    ]))
    ->add('email', $vb->email([
        Required::class,
        StringCases::class => [StringCases::TO_LOWER],
        ConfirmWith::class => [ConfirmWith::FIELD => 'email_check'],
    ]));
$result = $form->verify([ // or simply verify $_POST here...
    'name' => 'MY NAME',
    'email' => 'Email@Example.Com',
    'email_check' => 'Email@Example.Com',
]);
```

Another way to create a validation, do: `$vb($option_array)`, where the type maybe specified in `$option_array`.

The `$result` contains child result for each element in the form.

```
if ($result->isValid()) {
    echo $result->getChild('name')->value();  // 'My Name'
    echo $result->getChild('email')->value(); // 'email@example.com'
} else {
    // access elements in the form.
    foreach($result as $key => $element) {
        if (!$element->isValid()) {
            echo $element->getErrorMessage(); // error messages
        }
    }
}
```

### Nested Form

[](#nested-form)

Simply add another form object in a form object.

```
$address = $vb->form()
    ->add('zip', $vb([
        'type' => 'digits',
        Required::class,
        StringLength::class => [StringLength::LENGTH => 5],
    ]))
    ->add('address', $vb([
        'type' => 'text',
        Required::class,
    ]))
    ->add('region', $vb([
        'type' => 'text',
        Required::class,
        InArray::class => [
            InArray::REPLACE => [
                'abc' => 'ABC Country',
                'def' => 'DEF Region',
            ],
        ],
    ]));

$form = $vb->form()
    ->add('name', $vb->text([Required::class]))
    ->add('address', $address);
```

A valid input may look like;

```
$input = [
    'name' => 'test-nested',
    'address' => [
        'zip' => '12345',
        'address' => 'city, street 101',
        'region' => 'abc',
    ]
];
$result = $form->verify($input);
echo $result->getChild('address')->getChild('region')->value(); // 'ABC Country'
```

### One-To-Many Forms

[](#one-to-many-forms)

use `addRepeatedForm` method to add a one-to-many form in another form.

```
$posts = $vb->form()
    ->add('title', $vb->text([
        Required::class,
    ]))
    ->add('publishedAt', $vb->date())
    ->add('size', $vb->integer([
        Required::class,
    ]));
$form = $vb->form()
    ->add('name', $vb->text([Required::class]))
    ->addRepeatedForm('posts', $posts);
```

A valid input may look like:

```
$input = [
    'name' => 'test-one-to-many',
    'posts' => [
        ['title' => 'first title', 'size' => 1234],
        ['title' => 'more tests here', 'publishedAt' => '2019-04-01', 'size' => 2345],
    ],
];
$result = $form->verify($input);
```

### Validating an Array

[](#validating-an-array)

To validate an array input, specify `multiple` when constructing a chain, as;

```
$tests = $vb->text([
    'multiple' => true, // specify multiple!
    StringLength::class => [StringLength::LENGTH => 3],
]);
$result = $tests->verify(['test', 'me']);
```

The filters, such as `StringLength` in the example above, will be applied to each of the value in the array.

To apply filters on to the whole array, specify filters as such;

```
$tests = $vb->text([
    'multiple' => [
        Required::class,
    ],
    StringLength::class => [StringLength::LENGTH => 5],
]);
$result = $tests->verify(['test', 'me']);
```

Locale
------

[](#locale)

specify locale (i.e. 'en', 'ja', etc.) when building the `ValidationBuilder`:

```
$vb = new ValidatorBuilder('ja');
```

Or specify the folder in which the builder can find the message and type definition files:

```
$vb = new ValidatorBuilder('/dir/to/my/locale');
```

The folder must contain: `validation.message.php` and `validation.types.php` files.

### `validation.message.php`

[](#validationmessagephp)

A php file that returns an array of error messages,

```
return [
    'filter_error_type' => 'error message here',
    ...
];
```

### `validation.types.php`

[](#validationtypesphp)

A php file that returns an array of filters for each type,

```
return [
    'type-name' => [
        'filter-name',
        'filter-with-option' => ['options' => 'here'],
    ], ...
];
```

Predefined Types
----------------

[](#predefined-types)

t.b.w.

### Text

[](#text)

- Validates a valid UTF-8 string, maximum 1MB of `string`.
- predefined filters:
    - ValidateUtf8String
    - DefaultValue: empty string

### email

[](#email)

- Validates a valid UTF-8 string, maximum 1MB of input, and a valid email `string`.
- predefined filters:
    - ValidateUtf8String
    - DefaultValue: empty string
    - Match: EMAIL

### integer

[](#integer)

- Validates a valid UTF-8 numeric string, and casted to an `integer`.
- predefined filters:
    - ValidateInteger
    - DefaultValue: NULL

### float

[](#float)

- Validates a valid UTF-8 numeric string, and casted to a `float`.
- predefined filters:
    - ValidateFloat
    - DefaultValue: NULL

### date

[](#date)

- Validates a valid UTF-8 date format string, and convert to a `\DateTimeImmutable` object.
- predefined filters:
    - ValidateDateTime
    - DefaultValue: NULL

### datetime

[](#datetime)

- Validates a valid UTF-8 date format string, and convert to a `\DateTimeImmutable` object.
- predefined filters:
    - ValidateDateTime
    - DefaultValue: NULL

### month

[](#month)

- Validates a valid UTF-8 date format string, and convert to a `\DateTimeImmutable` object.
- predefined filters:
    - ValidateDateTime
    - DefaultValue: NULL

### digits

[](#digits)

- Validates a valid UTF-8 string with digits only, and casted to a `string`.
- predefined filters:
    - ValidateDateTime
    - DefaultValue: empty string

### time

[](#time)

### timeHi

[](#timehi)

### dateYMD

[](#dateymd)

Predefined Filters
------------------

[](#predefined-filters)

### FilterArrayToValue

[](#filterarraytovalue)

- convert array input to a single text value.
- arguments: `['fields' => ['y', 'm'], 'format' => '%d.%d', 'implode' => '...']`
    - `fields`: required. specify list of array key names.
    - `format`: optional. spritnf format for the array values.
    - `implode`: optional. if `format` is not defined, implode values with the character (default is '-').

sample code:

```
$filter = new FilterArrayToValue([
    'fields' => ['y', 'm', 'd'],
    'format' => '%d.%02d.%02d',
]);
```

### ValidateMbString

[](#validatembstring)

- convert Japanese kana style.
- arguments: `['type' => 'convert']`
    - type: required. conversion option for `mb_convert_kana`. default is MB\_ZEN\_KANA.
- available type values:
    - `FilterMbString::MB_ZEN_KANA`: convert han-kaku-kana to zen-kaku-kana.
    - `FilterMbString::MB_HANKAKU`: convert zen-kaku-alphabets and digits to han-kaku.
    - `FilterMbString::MB_MB_ZENKAKU`: convert all characters to zen-kaku.
    - `FilterMbString::MB_HAN_KANA`: convert all characters to han-kaku, if possible.
    - `FilterMbString::MB_HIRAGANA`: convert all kana to zen-kaku-hiragana.
    - `FilterMbString::MB_KATAKANA`: convert all kana to zen-kaku-katakana.
- not tested, yet.

```
$filter = new FilterMbString(['type' => FilterMbString::MB_HANKAKU]);
$result = $filter(new Result('ｚｅｎｋａｋｕ＠ｅｘａｍｐｌｅ．ｃｏｍ'));
echo $result->value(); // zenkaku@example.com
```

### ValidateValidUtf8

[](#validatevalidutf8)

- checks if the input value is a valid UTF-8 characters.
- priority: FilterInterface::PRIORITY\_SECURITY\_FILTERS
- errors: on error, replaces the input value with an empty string ('').
    - `FilterValidUtf8::INVALID_CHAR` : invalid UTF-8 characters.
    - `FilterValidUtf8::ARRAY_INPUT` : input is an array.

### ValidateDateTime

[](#validatedatetime)

- converts string input into `\DateTimeImmutable` object.
- arguments: `['format' => 'YY.m.d']`.
    - format: optional. if set uses `\DateTimeImmutable::createFromFormat`

```
$filter = new ConvertDateTime(['format' => 'm/d/Y']);
$result = $filter(new Result('04/01/2019'));
$date = $result->value(); // should be DateTimeImmutable object.
```

### ValidateInteger

[](#validateinteger)

- checks the input value is numeric, and converts the value to an integer.
- errors: if the value is not numeric, or the value is an array.
- arguments: none.

### ValidateFloat

[](#validatefloat)

- checks the input value is numeric, and converts the value to a float.
- errors: if the value is not numeric, or the value is an array.
- arguments: none.

### ValidateLetterType

[](#validatelettertype)

- sanitize the input value consisted of certain type of letters.
    - arguments: `[ValidateLetterType::TYPE => ValidateLetterType::DIGITS_ONLY]`
        - `ValidateLetterType::TYPE`: required. specify types from the following.
            - `ValidateLetterType::DIGITS_ONLY`: only numbers (0-9).
            - `ValidateLetterType::AL_NUM_ONLY`: only alpha numeric characters (0-9a-zA-Z).
            - `ValidateLetterType::CODE_ONLY`: only some codes (-\_0-9a-zA-Z).

### DefaultValue

[](#defaultvalue)

- set value to a default `$default` if the input is null or empty.
- arguments: `['default' => 'some value']`
    - default: optional. if not set uses empty string ('').

### Required

[](#required)

- validates the input value is not null nor empty string.
- aborts further validations if failed.
- arguments: `[Required::NULLABLE => true]`.
    - `Required::NULLABLE`: deprecated. use `Nullable` instead. default false. breaks validation chain if the value is empty (i.e. either null, empty string, or empty array).

### RequiredIf

[](#requiredif)

- validates the input value is not null nor empty string, if the name `field` is set, or if `field` value is `value`.
- aborts further validations if failed.
- arguments: `[RequiredIf::FIELD => 'other', RequiredIf::VALUE => 'val']`
    - `RequiredIf::FIELD`: string. required. set other field name to refer to.
    - `RequiredIf::VALUE`: string, integer, float, or array. optional. set value (or values in array) if the other field has the specified value.
    - `Required::NULLABLE`: deprecated. use `Nullable` instead. default false. breaks validation chain if the value is empty (i.e. either null, empty string, or empty array).

```
$required = new RequiredIf([
    RequiredIf::FIELD => 'type',
    RequiredIf::VALUE => 'check-me',
    RequiredIf::NULLABLE => true,
]);
```

### Nullable

[](#nullable)

- breaks validation chain/loop if the input value is empty. stops further validations which may fail if the input is an empty value. thus, this filter allows NULLABLE value, regardless of the subsequent filter.
- use it for non-required field but have certain filters (RegEx) which may fail if the input is empty.
- arguments: none.

### StringLength

[](#stringlength)

- checks the input value's character length. set any of the arguments, `length`, `max`, or `min`, but probably does not make sense to set all options.
- arguments: `['length' => 5, 'max' => 6, 'min' => 7, 'message' => 'error message']`
    - length: optional. specify the exact length of the input string.
    - max: optional. set the maximum length of the input string.
    - min: optional. set the minimum length of the input string.
    - message: optional. set error message.

### ConfirmWith

[](#confirmwith)

- confirm the input value by comparing with another input value.
- arguments: `['with' => 'field_name_to_confirm_with']`
    - with: optional. if not set, uses `{name}_confirmation`
- not tested, yet.

### InArray

[](#inarray)

- checks the input value is defined in the given arrays.
- arguments: `['choices' => ['A', 'B',...]` or `['replace' => ['a' => 'A', 'b' => 'B']]`. must specify either `choices` or `replace` option.
    - choices: optional array. specify the available choices as an array.
    - replace: optional hashed array. replace the value.
    - strict: optional. strict option when checking the value. default true.

```
$filter = new InArray([
    'choices' => [
        $obj1->getKey(), $obj1,
        $obj2->getKey(), $obj2,
    ],
    'replace' => true,
    'strict' => true,
]);
```

### RegEx

[](#regex)

- checks for regular expression.
- arguments: `[RegEx::PATTERN => '[A-D][0-9]{1}', RegEx::MESSAGE => 'error message']`
    - `RegEx::PATTERN`: required. set regular expression pattern. the pattern is valuated as `/\A{$pattern}\z/us`.
    - `RegEx::MESSAGE`: optional. set error message.
- not tested, yet.

### ValidateMatch

[](#validatematch)

- validates input string for valid UTF-8 and predefined types using `filter_var`.
- as a default, error message is selected based on the type.
- arguments: `[Match::TYPE=> 'filter_var_filter']`
    - `Match::TYPE`: required. string from available type below:
        - `Match::IP`: validates IP address.
        - `Match::EMAIL`: validates email address.
        - `Match::URL`: validates URL.
        - `Match::MAC`: validates MAC address.
- not tested, yet.

### StringCases

[](#stringcases)

### StringTrim

[](#stringtrim)

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity59

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 ~320 days

Recently: every ~37 days

Total

8

Last Release

2431d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8ed783829e6fa0bd4b0def8c04ccfdfb2fc99f9e61e4a9470acad9e5abc5fcac?d=identicon)[asaokamei](/maintainers/asaokamei)

---

Top Contributors

[![asaokamei](https://avatars.githubusercontent.com/u/747030?v=4)](https://github.com/asaokamei "asaokamei (345 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wscore-validator/health.svg)

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

###  Alternatives

[webmozart/assert

Assertions to validate method input/output with nice error messages.

7.6k894.0M1.2k](/packages/webmozart-assert)[bensampo/laravel-enum

Simple, extensible and powerful enumeration implementation for Laravel.

2.0k15.9M104](/packages/bensampo-laravel-enum)[swaggest/json-schema

High definition PHP structures with JSON-schema based validation

48612.5M73](/packages/swaggest-json-schema)[stevebauman/purify

An HTML Purifier / Sanitizer for Laravel

5325.6M19](/packages/stevebauman-purify)[ashallendesign/laravel-config-validator

A package for validating your Laravel app's config.

217905.3k5](/packages/ashallendesign-laravel-config-validator)[crazybooot/base64-validation

Laravel validators for base64 encoded files

1341.9M8](/packages/crazybooot-base64-validation)

PHPackages © 2026

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