Download the PHP package torugo/property-validator without Composer

Property Validator

Validators and Handlers for class properties.
Commonly used to create DTOs (Data Transfer Objects).

Inspired by class-validator for Typescript.

Table of Contents

• Requirements
• Instalation
• Usage
  • Validating the data
  • Error Handling
  • Custom error message
• Validators
  • Common
  • IsEqualTo
  • IsOptional
  • IsRequired
  • SameAs
  • Type Checkers
  • IsArray
  • IsBoolean
  • IsDateTime
  • IsDouble
  • IsEnum
  • IsFloat
  • IsInt
  • IsInteger
  • IsNumeric
  • IsString
  • Arrays
  • ArrayContains
  • ArrayMaxSize
  • ArrayMinSize
  • ArrayKeyExists
  • ArrayNotContains
  • Date/Time
  • MaxDateTime
  • MinDateTime
  • Numbers
  • IsDivisibleBy
  • IsNegative
  • IsPositive
  • Max
  • Min
  • Range
  • Strings
  • Contains
  • IsAlpha
  • IsAlphanumeric
  • IsBase64
  • IsCnpj
  • IsCpf
  • IsEmail
  • IsIP
  • IsSemVer
  • IsTUID
  • IsURL
  • Length
  • Matches
  • MaxLength
  • MinLength
  • NotContains
• Handlers
  • Common
  • CopyFrom
  • Convertions
  • Explode
  • Implode
  • Join
  • Split
  • Strings
  • Append
  • PasswordHash
  • Prepend
  • SubString
  • Replace
  • ToLowerCase
  • ToTitleCase
  • ToUpperCase
  • Trim, LTrim and RTrim
• Setters
  • SetDateTime
  • SetFromCallback
  • Parameters
  • Examples
  • SetValueWhenEmpty
  • Parameters
  • Examples
  • SetValueWhenNull
  • Parameters
  • Examples
• Custom Validators
  • Templates
  • Validator class
• Contribute
• License

Requirements

• PHP 8.2+
• PHP mbstring extension installed and loaded.
• Composer 2+

Instalation

On your terminal type:

Or add to your require list on composer.json file:

Usage

This library is based on the PHP Attributes resource.

Example

Validating the data

There are two ways to validate property values:

1. by adding a method inside your class that calls PropertyValidator::validate like example above;
2. Or by calling it from anywhere passing an instance of the class.

Example

Using the class SignInDto from usage example above.

Error Handling

Validators can throw:

InvalidTypeException:
Thrown when the property type is incorrect, or when the type of the received value is invalid.

ValidationException:
Thrown on validation errors, the value type is correct but, its content is invalid.

So you can wrap the validation in a try/catch block.

Examples

or

Custom error message

All VALIDATING ATTRIBUTES have an argument called $errorMessage, where you can define a custom error message. If not defined, the default error messages from each validator will be thrown.

Consult each validator's documentation to see the position of the argument, or use PHP's named arguments feature.

Example

Validators

Set of attributes that validate the properties of a class, do not change its value, only check whether the data respects a certain rule of each validator.

Validators can throw ValidationException and InvalidTypeException.

Common

IsEqualTo

Validates whether the value of a property exactly equals to a given value.

Examples

IsOptional

Defines a property as optional, so its value can be empty or null.

[!NOTE] By default, all properties of a class that use any of the attributes of this library are treated as NON NULLABLE, but their values can be empty.

Examples

[!IMPORTANT] When setting the type of a property other than "mixed", you must set the type to optional as well by placing a question mark a the beggining.
E.g. ?string, ?int, ?array, ...

IsRequired

Defines a property as required, so that the value cannot be null or empty.

By default, all properties of a class that use any of the attributes in this library are treated as NON NULLABLE, so using this attribute their values cannot be empty as well.

Parameters

Examples

SameAs

Validates whether the value of a property is strictly equal to another in the same class

Parameters

Examples

Type Checkers

IsArray

Validates whether the value of a property is an array.

Parameters

Examples

IsBoolean

Validates wheter a property data is a valid boolean value.

Parameters

Examples

Accepted values:

IsDateTime

Validates whether the property value is a valid date time string.

Parameters

Examples

IsDouble

IsDouble is just an alias to IsFloat validator.

IsEnum

Validates if the property's value is a member of a given backed enum.

Parameters

Examples

[!IMPORTANT] The ENUM used to validate the data must be BACKED.

enum DeskOS: string
{
  case Linux = "L";
  case MacOS = "M";
  case Windows = "W";
}

enum Database: int 
{
  case MySql = 0;
  case Postgres = 1;
  case Mongo = 2;
}

enum MobileOS
{
  case Android;
  case iOS;
  case iPadOS;
}

IsFloat

Validates if a value's type is FLOAT.

Parameters

Examples

IsInt

Validates whether the value of a property is of type integer.

Parameters

Examples

IsInteger

IsInterger is just an alias to IsInt validator.

IsNumeric

Validates whether the value of a property is numeric. Only float, int or numeric string types are allowed.

Parameters

Examples

[!IMPORTANT] This validator requires the property to be set to mixed

IsString

Validates whether the type of a value is string.

Parameters

Examples

Arrays

ArrayContains

Validates whether an array contains a given value.

Parameters

Examples

TODO:
Implements case insensitive string search.

ArrayMaxSize

Checks whether the number of elements in an array is less than or equal to a specified number.

Parameters

Examples

ArrayMinSize

Checks whether the number of elements in an array is greater than or equal to a specified number.

Parameters

Examples

ArrayKeyExists

Validates whether an array has one or more keys.

Parameters

Examples

ArrayNotContains

Works in the opposite direction to ArrayContains.
Throws ValidationException when a certain value is found in an array.

Parameters

Examples

TODO:
Implements case insensitive string search.

Date/Time

MaxDateTime

Validates whether a DateTime instance is greater than a defined limit.

Parameters

Examples

[!IMPORTANT] If you intend to validate date/time in strings, you must first use the IsDateTime attribute, and set the 'toDateTime' argument to true, in these cases it is mandatory to set the property type to mixed. See the examples below.

MinDateTime

Validates whether a DateTime instance is before than a defined minimum date/time.

Parameters

Examples

[!IMPORTANT] If you intend to validate date/time in strings, you must first use the IsDateTime attribute, and set the 'toDateTime' argument to true, in these cases it is mandatory to set the property type to mixed. See the examples below.

Numbers

IsDivisibleBy

Validates whether a number (int or float) is divisible by a given one.

Parameters

Examples

IsNegative

Validates if property's value is negative (lesser than zero).

Parameters

Examples

IsPositive

Validates if a number is positive (greater than zero).

Parameters

Examples

Max

Validates whether a number (int or float) is less than or equal to a given number.

Parameters

Examples

Min

Validates whether a number (int or float) is greater than or equal to a given number.

Parameters

Examples

Range

Validates whether a number falls within a given inclusive range.

Parameters

Examples

Strings

[!IMPORTANT] All string validators in this section extend the IsString validator, so its use is unnecessary.

Contains

Validates whether a substring is contained in the property's value.

Parameters

Examples

IsAlpha

Validates if a string have only alphabetical characters.

Parameters

Examples

IsAlphanumeric

Validates if a string have only alphanumeric characters.

Parameters

Examples

IsBase64

Validates whether a string is in Base64 format.
Works with url safe base64 strings.

Parameters

Examples

IsCnpj

Validates if a given string has a valid CNPJ registration.

The Brazil National Registry of Legal Entities number (CNPJ) is a company identification number that must be obtained from the Department of Federal Revenue(Secretaria da Receita Federal do Brasil) prior to the start of any business activities.

Parameters

Examples

[!IMPORTANT] The cnpj numbers above were generated randomly using this tool.
If one of them belongs to you, please send me a request to remove.

IsCpf

Validates if a given string has a valid CPF identification.

CPF Stands for “Cadastro de Pessoas Físicas” or “Registry of Individuals”. It is similar to the “Social Security” number adopted in the US, and it is used as a type of universal identifier in Brazil.

Parameters

Examples

[!IMPORTANT] The CPF numbers above were generated randomly using this tool.
If one of them belongs to you, please send me a request and I will remove it immediately.

IsEmail

Validates whether a string has a valid email structure.

Parameters

Examples

[!TIP] Take a look at the tests to see more of valid or invalid emails.

IsIP

Validates whether a string is a valid IP address for both V4 and V6.

Parameters

Examples

IsSemVer

Validates whether a version number follow the rules of semantic versioning (SemVer).

Parameters

Examples

IsTUID

Validates whether a string is a valid TUID.

Parameters

Examples

IsURL

Validates whether a string has a valid URL structure.

Parameters

Validation Options

Default values:

Examples

Length

Validates if the length of a string is between a minimum and maximum parameters.

Parameters

Examples

Matches

Performs a regular expression match on property's value

Parameters

Examples

MaxLength

Validates if the length of a string is lesser than or equal to a maximum parameter.

Parameters

Examples

MinLength

Examples

NotContains

Checks whether a substring is contained in the received value, if so, throws an exception.

Parameters

Examples

Handlers

Set of attributes that modify the value of a property and do not validate the value, the objective is to transform/manipulate them in some way.

When the type of the value is incorrect, the handlers should do nothing, so they normally do not throw any exceptions in this cases.

Some handlers require the property to be of a certain type, usually mixed, therefore they can throw InvalidTypeException.

Common

CopyFrom

Copies the value of another property in the same class.

Parameters

[!IMPORTANT] Throws InvalidArgumentException if the target properthy does not exists.

Example

Convertions

Explode

Explode is an alias to Split handler.

Implode

Implode is an alias to Join handler.

Join

Converts an array to a string by recursively joining the values ​​by placing a separator between them.

[!NOTE] This handler requires the property to be declared as mixed, otherwise InvalidTypeException will be thrown.

Parameters

Examples

Split

Converts a string to an array of strings each of which is a substring of it on boundaries formed by the string separator.

[!NOTE] This handler requires the property to be declared as mixed, otherwise InvalidTypeException will be thrown.

Parameters

* If limit is set and positive, the returned array will contain a maximum of limit elements with the last element containing the rest of string. If the limit parameter is negative, all components except the last - limit are returned. If the limit parameter is zero, then this is treated as 1.

Examples

Strings

Append

Concatenates a string at the end of the property value.

Parameters

Examples

PasswordHash

Generates a new password hash using a strong one-way hashing algorithm.
Uses PHP password_hash() function.

Parameters

Examples

Prepend

Concatenates a string at the beginning of the property value.

Parameters

Examples

SubString

Returns the portion of string specified by the offset and length parameters.
Uses PHP substr() function.

Parameters

Examples

Replace

Replace all occurrences of the search string with the replacement string.

Parameters

Examples

ToLowerCase

Converts a string or string elements in an array to lower case.

Examples

ToTitleCase

Converts a string or string elements in an array to title case.

Parameters

To know more visit.

Examples

ToUpperCase

Converts a string or string elements in an array to upper case.

Examples

Trim, LTrim and RTrim

Strip whitespace (or other characters) from the beginning and end of a string.

Characters parameter

The stripped characters can be specified using the characters parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.

Examples

[!NOTE] LTrim and RTrim works exactly in the same way.

Setters

SetDateTime

Sets the property's value as DateTime object or formatted string.

Parameters

Examples

SetFromCallback

Sets the property's value from a returned value of a function or class method. This attribute wraps the PHP call_user_func_array function.

Parameters

[!NOTE] If you want to call a method from a class, the method must be static.

Examples

SetValueWhenEmpty

Sets a custom string value when property receives an empty string or a null value.

Parameters

Examples

SetValueWhenNull

Sets a custom value when property receives a null value.

Parameters

Examples

Custom Validators

To create a custom validator is required:

1. The validator must extends Torugo\PropertyValidator\Abstract\Validator;
2. Add the attribute #[Attribute(Attribute::TARGET_PROPERTY)] to the class;
3. Implement the method public function validation(mixed $value): void;

Templates

Simple validator

Validator with arguments

Validator class

The Validator class gives to you:

Properties

Methods

Contribute

It is currently not open to contributions, I intend to make it available as soon as possible.

License

This library is licensed under the MIT License - see the LICENSE file for details.