Download the PHP package inpsyde/validator without Composer

On this page you can find all versions of the php package inpsyde/validator. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of inpsyde/validator

Informations about the package validator

Inpsyde Validator

This package provides a collection of validators for WordPress.

Contents

Installation

Best served by Composer from Packagist. Package name is inpsyde/validator.

What it is and how it works

The package provides validator objects that can be used to verify that some given data fulfill specific requirements.

Most important method for each validator is is_valid() that receives some data and returns true or false, depending on the provided data meets validator requirements.

We can distinguish among three types of validators:

Simple validators are used to verify single values, according to some specifications.

Secondary validators are created taking a simple validator and modifying its behavior. Can be seen as "decorators" for validators.

Compound validators are made by combining togheter more validators.

Simple validators

This is a summary of simple validators provided as of now with the package:

Name Can be used for Options Description
Between Any data min, max,inclusive Verifies given value is between a maximum and a minimum defined in options.
Callback Any data callback Run give callback passing value to validate. If callback returns a true-ish value, value is considered valid.
ClassName Strings autoload Check that value is a valid class name string. Trigger autoload by default, but ir can be prevented by option.
Date String, array, integers andDateTimeInterface objects format Verifies that given data is a valid date according to format defined in options.
Email Strings check_dns Check that value is a valid email. Optionally also checks DNS.
GreaterThan Any data min,inclusive Verifies given value is > (or >=) option value.
InArray Any data haystack,strict Verifies given value is present in an haystack defined in options.
LessThan Any data max,inclusive Verifies given value is < (or <=) option value.
NotEmpty Any data --- Verifies given value is not empty. (Unlike PHP empty() function 0 and '0' are not considered empty)
RegEx Strings pattern Verifies given string matches a regular expression pattern defined in options.
Size Any data size Verifies given data has size defined by option. For strings it means length, arrays and countable objects are counted, numbers cast to integer.
Type Any data type Verifies that given data is of a specific type. Works with built-in types like "integer", "string" and with class and interface names. Also has 2 special types "numeric" and "traversable"
Url Strings allowed_protocols, check_dns Verifies that given string is a valid URL. Optionally also checks DNS.
WpFilter Any data filter Calls apply_filters with the filter set, passing the value as argument. If callbacks hooked to filter returns a true-ish value, value is considered valid.

All validators are defined in Inpsyde\Validator namespace, so it is possible to use them like this:

Other validators can be used in a pretty identical fashion.

Secondary validators

At the moment, are available following secondary validators:

Name Can be used for Description
Bulk Traversable data Takes one validator and applies it to all items of a traversable value. Validate if validator validates all the items.
Negate Any data Takes one validator and negate its result. If given validator validates, the Negate validator will fail, and the other way around.
Pool Traversable data Similar to Bulk, it applies a validator to all items of a traversable value. But it validates if the validator validates any of the items.

All secondary validators have a with_validator() static method, that can be used as named constructor to obtain an instance.

Negate example

Here an example on how to use Negate to check that given value is not included in a given haystack of values:

Bulk example

Here an example on how to use Bulk to check that given array contains only strings:

Pool example

Here an example on how to use Pool to check that given array contains at least a WP_Post object:

Pool traverse the given value and returns true when first item of the value validates the inner validator.

Compound validators

At the moment, following compound validators ar available:

Name Can be used for Options Description
Multi Any data stop_on_failure Combine more validators together to check the same value. Will be valid if all child validators are valid. I.e. it combines validators with AND login operand.
MultiOr Any data --- Combine more validators together to check the same value. Will be valid if any of the child validators is valid. I.e. it combines validators with OR login operand.
DataValidator arrays or instances of Traversable --- Validate a collection of data, each child validator is assigned to a different part of the data, assigned by key

DataValidator is the more powerful validator of the package, because it is the only validator implementing ErrorLoggerAwareValidatorInterface interface that makes it possible to obtain error messages for validated data in a very simple way. For this reason usage of this validator is treated separately below.

Multi example

Here an example on how to use Multi validator, to check that given value is an array and has two items and both of them are strings:

The first constructor argument is an array of options, just like for all the "simple" validators. The second argument is an array of validators.

Please note how we used a secondary validator (Bulk) as a child validator for Multi: this is totally fine, because simple, secondary and compound validators all implement the same interface.

By default all validators are executed for the given value when is_valid() is called, but setting the option stop_on_failure to TRUE, the validator stops to perform validation when the first failing validator is reached.

An alternative (and less verbose) way to build a Multi validator instance is to use the static method with_validators() that accepts a variadic number of validator objects:

When constructed like this, the stop_on_failure options is set to its default, that is false, but can be set to true by calling stop_on_failure() method on the obtained instance.

MultiOr example

MultiOr is very similar to Multi, but the latter combines validator with an AND operand, the former with OR operand.

In other words, using Multi all the inner validators have to validate to make Multi validate, on the contrary MultiOr validates if at least one of inner validators validates.

Here an example on how to use MultiOr to validate a value to be in the range from 5 to 10 or in the range 50 to 100:

Error codes and input data

Some validators may fail for different reasons.

For example, RegEx validator may fail because the input provided is not a string, or because the patter is not valid or just because the given value does not match the provided pattern.

This is why all validators came with two additional methods (alongside is_valid()):

get_error_code() returns a code that identifies the kind of error that made the validator fail.

All default error codes are available as interface constants of Inpsyde\Validator\Error\ErrorLoggerInterface.

For example, Between validator might return ErrorLoggerInterface::NOT_BETWEEN_STRICT if inclusive option is true, or ErrorLoggerInterface::NOT_BETWEEN if it is false.

get_input_data() returns an array with information on

For example, in the example above Validator\Between::get_input_data() might return:

Validators factory

The package ships with a validator factory class that can be used to build validator instances starting from some configuration values.

This is useful when more validators have to built in bulk from configuration files or for lazy instantiation.

The factory has just one method create() that accepts a validator identifier as string and an optional array of options.

Usage example:

To construct shipped validators, it is also possible to use as identifier their class name without namespace, like:

For any custom validator (see below) that implements validator interfaces, it is possible to pass the fully qualified name of the class to obtain a constructed instance.

Error messages

This package comes with objects dedicated to get error messages when validators fail.

They are:

The two loggers works in the same way, however WordPressErrorLogger has support for translations via WordPress translation feature.

There are two step involved in showing errors using these objects:

  1. Log the error(s)
  2. Get the array of logged errors

The code looks like this:

It might seem it requires too much work, however when validating data with DataValidator (see below) most of the code above is not necessary.

Error templates

When using error loggers, the error messages are created using "templates": message strings that contain placeholders for values.

Every error code available as constant of ErrorLoggerInterface has a related template.

For example, for the code ErrorLoggerInterface::NOT_BETWEEN the related template is:

Where %value%, %min% and %max% are placeholders that are replaced with data passed via get_input_data() when the error is logged.

Error templates can be customized in 2 different ways:

  1. replacing the template used for specific codes in the logger
  2. passing a specific template when logging an error

Code-specific templates

Error loggers comes with a method: use_error_template() that can be used to set a custom error template for a given error code.

For example:

Doing like this, all the errors for Error\ErrorLoggerInterface::NOT_BETWEEN will use the given template, unless an error-specific template is provided when logging the error.

Instead of using use_error_template() that replaces error templates one by one, it is possible to replace more templates at once passing to logger constructor an array of templates where array keys are the error codes:

Error-specific templates

The method log_error() accepts a third argument to pass a specific template that will me used for that error only:

When used like this, the custom template does not affect all the other messages for same code, but only the error being logged.

DataValidator

DataValidator is the more powerful validator in the package. Beside to collect more validators, it also provides more methods than other validators, including get_error_messages() that returns an array of all errors occurred while validating given data.

"Child" validators added to DataValidator can be used to validate:

Add validators to all items

DataValidator has two methods to add validators to all the items of the data to validate, they are:

The first just accepts a validator instance, the second also accepts a custom message template that will be used to build the error message when this validator fail.

Example:

Each element of the array passed to is_valid() will be validated against both the validators added.

In the example above, note how both add_validator_with_message() and add_validator implements "fluent interface" allowing to "chain" calls to them by returning an instance of validator.

Add validator to specific items

DataValidator also has one method that allows to add validators to specific element of the given data, it is add_validator_by_key().

It takes three arguments: an instance of validator, a key used to identify the data element, and optionally an error message template to use for the validator.

Example:

DataValidator is the only validator that supports get_error_messages() to obtain an array of all error occurred.

Customize error message templates

By using add_validator_by_key() and add_validator_with_message() it is possible to customize the error template at validator level, however, DataValidator constructor optionally takes as first argument an instance of error logger that will be used to build all messages.

So, it is possible to create an error logger instance with custom error messages (as shown above) and pass it to DataValidator constructor:

Item keys in error messages

When using DataValidator, there is an additional placeholder:'%key%', that will be replaced with the item key of the value that caused the error.

By default, error messages have no '%key%' placeholder, so the string "<code>%key%</code>: " is prepended to default message.

For example, the default message template

The input %value% is not a valid URL.

becomes:

%key%: The input %value% is not a valid URL.

This only happens when no custom error template is provided using add_validator_by_key() or add_validator_with_message(), when custom error template is provided, nothing is prepended to it, but if the custom template contains the '%key%' placeholder it will be replaced as well.

Item key labels for error messages

Sometimes it might be desirable that the error message does not contain the item key, but a label.

For example, if the validator is used to validate data coming from an HTML form, would be nice if the error message would contain the input label, and not input name.

However, the input name (that will be the key in the submitted data array) is also needed to let DataValidator identify which validator apply to each field.

For this reason, both add_validator_by_key() and add_validator_with_message() support a special syntax for their second argument$key: an array of two element, with keys 'key' and 'label'.

Example:

In the example above, because username key has an empty value, the error message built will be the translated version of

User name must not be empty.

Note how the label is used to replace the placeholder instead of the key.

Custom validators

It is possible to create custom validators to be used with the package.

Custom validators should implement the interface ExtendedValidatorInterface which contains the following methods:

The package ships with 2 traits that can be used to implement the first 3 methods, leaving only is_valid() to implementers.

Particularly consider GetErrorMessagesTrait that contains implementation for the deprecated get_error_messages() (see "Upgrading from version 1.0" below for more info).

Custom validator example

A trivial custom validator could be something like this:

The validator might emit two error codes in case of error, one of them is a default error code, the other is custom.

If the validator is intended to be used with DataValidator, it is necessary to add the custom code to the error logger, something like:

Upgrading from version 1.0

For reasons above starting from version 2.0:

Other notes

Bugs, technical hints or contribute

Please give us feedback, contribute and file technical bugs on GitHub Repo.

License

Good news, this plugin is free for everyone! Since it's released under the MIT, you can use it free of charge on your personal or commercial blog.

Changelog

See commits or read short version.

All versions of validator with dependencies

PHP Build Version
Package Version
Requires php Version >=7.2
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package inpsyde/validator contains the following files

Loading the files please wait ....