Master | ||
---|---|---|
Develop |
Extensible validation and sanitization library for various input sources like $_POST
and routing parameters.
- Supports validation of various input sources (per field configurable)
- Extensible
- Translatable
- Supports global php functions like
trim()
,intval()
, etc. - Supports array field inputs
- No dependencies
- Automated tests with 100% code coverage
- Liberal license: zlib/libpng
Note: This has just been released, so it might not be perfect yet. Feel free to report issues, improvement ideas or create pull requests.
- PHP >= 7.1
Install via composer:
composer require lusito/insanity
Include the autoloader in your php script, unless you've done that already:
require __DIR__ . '/vendor/autoload.php';
An example use-case:
use Lusito\InSanity\InSanity;
//...
$in = new InSanity(); // or new InSanity($_GET) if you want to use $_GET as default instead of $_POST.
$in->site_id('Site ID', $_GET)->required->is_natural->intval; // use $_GET as input instead of $_POST for this field
$in->parent_id('Parent ID')->required->is_natural->intval;
$in->title('Title')->required->trim->min_length(2)->max_length(255);
$in->slug('Slug')->max_length(255);
$in->visible('Visible')->required->is_bool->boolval;
$errors = $in->getErrors();
if ($errors) {
http_response_code(400);
header('Content-Type: application/json');
echo json_encode(['error' => "Invalid input!", 'validation_errors' => $errors], JSON_UNESCAPED_SLASHES);
} else {
// Get all values in an associative array:
$json = $in->toJSON();
}
Alternatively, you can grab the values manually like this:
use Lusito\InSanity\InSanity;
//...
$in = new InSanity(); // or new InSanity($_GET) if you want to use $_GET as default instead of $_POST.
$siteId = $in->site_id('Site ID', $_GET)->required->is_natural->intval->getValue(); // use $_GET as input instead of $_POST for this field
$parentId = $in->parent_id('Parent ID')->required->is_natural->intval->getValue();
$title = $in->title('Title')->required->trim->min_length(2)->max_length(255)->getValue();
$slug = $in->slug('Slug')->max_length(255)->getValue();
$visible = $in->visible('Visible')->required->is_bool->boolval->getValue();
//...
This library consists of these classes:
InSanity
: This coordinates the validation process.Field
: Used to chain rules and sanitizers to process values. Instances are automatically created.RuleHandler
: A class that contains the included rules.ErrorHandler
: Aggregates errors.Translator
: A class used to translate messages and field names.
The last 3 classes can be extended or even replaced with your own implementations if you feel like it.
Details follow:
This class receives 3 parameters:
- An optional (associative) array that serves as the default input if none was specified. If this is
null
,$_POST
will be used. - An optional instance of
RuleHandler
(or a replacement class). Ifnull
, a defaultRuleHandler
is created. - An optional instance of
ErrorHandler
(or a replacement class). Ifnull
, a defaultErrorHandler
is created.
To start validation and sanitization on a field, call it like this:
$in = new InSanity();
$in->my_field_name('My Field Label')->required->trim->min_length(2);
This consists of 2 parts:
$in->my_field_name('My Field Label')
my_field_name
is the field name as it exists in the input array.My Field Label
is the text that will be used when generating error messages.- This returns an instance of
Field
.
->required->trim->min_length(2)
- These apply your rules. Rule calls return the
Field
instance for easy chaining.
- These apply your rules. Rule calls return the
You can get errors using $in->getErrors()
. If you need to access a field afterwards (or apply an additional later), you can access the fields later by using $in->my_field_name
.
For convenience, a method $in->toJSON()
exists, which will create an associative array field_name => field_value.
Field instances are created by InSanity
(see above). The instance supports executing and chaining rules.
A rule can be run in 3 different ways:
// shortest way:
$field->required;
// does the same as:
$field->required();
// A parameter can be supplied like this:
$field->min_length(2);
The rule (and filter) methods are applied in order. If the given method returns a boolean value, it's interpreted as a rule, otherwise as a filter (the sole exception is boolval
, see below).
Examples:
- A return value of false will fail the validation (and skip the rest of the rules)
- A value of true will continue with the next rule (or filter).
- Anything else will change the current value to what has been returned by the rule handler.
Some methods exist in addition to normal rule handling:
default(default)
: If value isnull
, value will be set todefault
.boolval()
: This was added for two reasons:boolval
from PHP doesn't work on the same values as the is_bool rule.- it returns true or false, which would normally be interpreted as a validation result and thus, not be stored.
getValue()
: Gets the current value of the field (after rules have been applied)getError()
: Gets the error message, ornull
if no error has been set yet.setFailed(rule, param=null)
: Sets the field to failed. An error message will be generated using the translator class.
As said, RuleHandler contains validation methods.
That method receives 1-2 parameters. The first being the value to validate and the second is the parameter passed by the user (null
if none given).
The following rules are included in the built-in RuleHandler class:
is_alpha
(a-z)is_alnum
(a-z and 0-9)is_alnum_dash
(a-z, 0-9, _ and -)is_numeric
(a numeric value, prefixed by a + or a -)is_integer
(an integer value, prefixed by a + or a -)is_natural
(an integer value without prefix)is_natural_no_zero
(an integer value without prefix and above zero)is_bool
(true|false|on|off|yes|no|1|0)valid_email
(a valid e-mail address)required
(the trimmed value may not be empty)min_length(length)
(the value must have a minimum length)max_length(length)
(the value must have a maximum length)exact_length(length)
(the value must have a specified length)
If you plan on writing your own rules or if you need more than english as target language, you can either add/override translations by supplying an associative array to the constructor or you can write your own implementation.
The ErrorHandler builds and aggregates error messages. It will create a new Translator
instance when needed. If you want it to use a custom Translator
instance, either pass the instance as first argument to the constructor, or override the getTranslator()
method.
Something not working quite as expected? Do you need a feature that has not been implemented yet? Check the issue tracker and add a new one if your problem is not already listed. Please try to provide a detailed description of your problem, including the steps to reproduce it.
Awesome! If you would like to contribute with a new feature or submit a bugfix, fork this repo and send a pull request. Please, make sure all the unit tests are passing before submitting and add new ones in case you introduced new features.
InSanity has been released under the zlib/libpng license, meaning you can use it free of charge, without strings attached in commercial and non-commercial projects. Credits are appreciated but not mandatory.