This library allows you to extract, filter and validate individual fields from an associative array. It can be used, as an example, to validate request variables sent from a web browser. You give each parameter a "name", define the "context" and call "process"; the result will be the value extracted from the context or an error message in case of not conforming to one or more validation filters. Many predefined filters and validators are available from a "finger-friendly" API. You can also specify a fallback value to be returned in case of validation error.
Install via composer:
composer require flsouto/param
The example bellow creates a parameter and prints out its name
<?php
use FlSouto\Param;
require_once('vendor/autoload.php');
$param = new Param('test');
echo $param->name();test
You can instantiate the parameter from the static get method which always returns the same instance for that name:
use FlSouto\Param;
$param1 = Param::get('country');
$param2 = Param::get('country');
var_dump($param1===$param2);The output will be:
bool(true)
The process instance method receives a "context", which must be an associative array, and tries to extract
the parameter value based on the parameter name.
use FlSouto\Param;
$param = Param::get('user_id');
$result = $param->process(['user_id'=>5]);
echo $result->output;The output of the above will be:
5
You can set the context on the parameter instance before calling the process method:
use FlSouto\Param;
$param = Param::get('language');
$param->context([
'var1' => '...',
'var2' => '...',
'language' => 'en'
]);
$result = $param->process();
echo $result->output;en
If you want to set the context and be able to modify it later, I recommend you provide an instance of ArrayObject like in the example bellow:
use FlSouto\Param;
$context = new ArrayObject;
$param = Param::get('lang_code');
$param->context($context);
// modify context later
$context['lang_code'] = 'en';
$result = $param->process();
echo $result->output;en
Furthermore, you can work with the ParamContext class which allows you to factory parameters from a predefined context. Read more about it on the "ParamContext" section.
You can use square brackets for a fully qualified name. In the following example, the parameter 'email' is found inside the hierarchy user > contact:
use FlSouto\Param;
$param = Param::get('user[contact][email]');
$param->context([
'user' => [
'contact' => [
'email' => 'user@domain.com'
]
]
]);
$result = $param->process();
echo $result->output;The output of the above will be:
user@domain.com
The param object uses an instance of the Pipe class which allows you to bind a series of filters and/or validators to the data:
use FlSouto\Param;
$param = Param::get('user');
$param->pipe()->add('trim')->add(function($value){
if(empty($value)){
echo 'Cannot be empty';
}
});
$result = $param->process(['user'=>' ']);
echo $result->error;Output:
Cannot be empty
The above snippet adds a filter that trims the parameter value, and also adds a validator that produces an error if the final value is empty. The printed error message is then captured inside the $result->error property.
Notice: the Param class actually provides a bunch of common filters and validatiors through the
ParamFilters API. More on this subject in the "ParamFilters API" section.
You can specify a fallback value to be returned in the $result->output in case validation fails.
use FlSouto\Param;
$param = Param::get('lang');
$param->fallback('en');
$param->pipe()->add(function($value){
if(empty($value)){
echo 'No language selected';
}
});
// pass an empty context
$result = $param->process([]);
echo $result->output;The output will be:
en
The library provides the static setup method which allows you to intercept all param instances upon their creation.
In the example bellow we define the default context for every parameter in our application to be the $_REQUEST superglobal, and we also set all parameters to be trimmed by default:
use FlSouto\Param;
// place this in a global bootstrap script
Param::setup(function(Param $param){
$param->context($_REQUEST)->filters()->trim();
});
// Processing some request
$_REQUEST = ['name'=>'Fabio ','age'=>' 666 '];
$name = (new Param('name'))->process()->output;
$age = (new Param('age'))->process()->output;
echo "$name is $age years old";The output from the above code will be:
Fabio is 666 years old
Last but not least, all setters of the Param class return the instance itself, so it is possible to use method chaining:
<?php
use FlSouto\Param;
require_once('vendor/autoload.php');
$_REQUEST['lang'] = 'pt';
Param::get('lang')
->fallback('en')
->context($_REQUEST)
->pipe()
->add('trim')
->add(function($value){
if(empty($value)) echo 'Cannot be empty';
});
$result = Param::get('lang')->process();
The ParamContext allows you to create params out of a predefined context.
It's actually a wrapper to the ArrayObject class that keeps track of added parameters:
<?php
require_once('vendor/autoload.php');
use FlSouto\ParamContext;
$context = new ParamContext();
$context->param('user_id');
$context->param('lang_code')->filters()->trim();
$context['user_id'] = 5;
$context['lang_code'] = 'en ';
$result = $context->process();
print_r($result->output);The output will be an associative array with all the parameters extracted:
Array
(
[user_id] => 5
[lang_code] => en
)
You can still process an individual param and get its output:
require_once('vendor/autoload.php');
use FlSouto\ParamContext;
$context = new ParamContext();
$context->param('lang_code')->filters()->trim();
$context['lang_code'] = 'en ';
// process individual param:
$result = $context->param('lang_code')->process();
var_dump($result->output);The output will be:
string(2) "en"
If there are any errors, these will be available as an associative array inside the ´$result->errors´ variable.
require_once('vendor/autoload.php');
use FlSouto\ParamContext;
$context = new ParamContext();
$required = function($value){
if(empty($value)){
echo "Cannot be empty";
}
};
$context->param('user_id')->pipe()->add($required);
$context->param('user_name')->pipe()->add($required);
$result = $context->process();
print_r($result->errors);Output:
Array
(
[user_id] => Cannot be empty
[user_name] => Cannot be empty
)
The Param class has an instance method filters which returns an instance of ParamFilters.
This class makes the process of filtering and validating data much easier.
The following sections are dedicated to showing the usage of each method in that object.
Removes espaces from start and end of a string.
<?php
require_once('vendor/autoload.php');
use FlSouto\Param;
Param::get('name')
->filters()
->trim();
$result = Param::get('name')->process(['name'=>' maria ']);
var_dump($result->output);string(5) "maria"
The replace filter allows you to replace one string with another, similar to php's str_replace function:
use FlSouto\Param;
Param::get('money')
->context(['money'=>'3,50'])
->filters()
->replace(',','.');
$output = Param::get('money')->process()->output;
var_dump($output);string(4) "3.50"
If you wrap the search pattern between two slashes, a regular expression will be assumed.
use FlSouto\Param;
Param::get('file_name')
->context(['file_name'=>'My untitled document.pdf'])
->filters()
->replace('/\s+/', '-');
$output = Param::get('file_name')->process()->output;
var_dump($output);string(24) "My-untitled-document.pdf"
Another example using regex with the "i" modifier:
use FlSouto\Param;
Param::get('style')
->context(['style'=>'CamelCase'])
->filters()
->replace('/camelcase/i', 'under_scores');
$output = Param::get('style')->process()->output;
var_dump($output);string(12) "under_scores"
Matches a string or a regex pattern and remove it from the string:
use FlSouto\Param;
Param::get('name')->filters()->strip('/[^\d]/');
$result = Param::get('name')->process(['name'=>'f4b10']);
var_dump($result->output);string(3) "410"
Makes sure the value is not empty. If empty, an error message is produced.
use FlSouto\Param;
Param::get('name')
->context(['name'=>''])
->filters()
->required("Cannot be empty");
$error = Param::get('name')->process()->error;
var_dump($error);string(15) "Cannot be empty"
All validators have default error messages that can be customized. Bellow is an example of redefining the default error message:
use FlSouto\Param;
FlSouto\ParamFilters::$errmsg_required = 'Cannot be empty';
Param::get('name')
->context(['name'=>''])
->filters()
->required();
$error = Param::get('name')->process()->error;
var_dump($error);string(15) "Cannot be empty"
Produces an error when the string MATCHES A PATTERN:
use FlSouto\Param;
Param::get('name')
->filters()
->ifmatch('/\d/', 'Name cannot contain digits');
$error = Param::get('name')->process(['name'=>'M4ry'])->error;
var_dump($error);string(26) "Name cannot contain digits"
Another example using regex modifiers:
use FlSouto\Param;
Param::get('phone')
->filters()
->ifmatch('/[a-z]/i', 'Phone cannot contain letters');
$error = Param::get('phone')->process(['phone'=>'9829574K'])->error;
var_dump($error);string(28) "Phone cannot contain letters"
Notice: This validator is only applied when the value is not empty:
use FlSouto\Param;
Param::get('phone')
->filters()
->ifmatch('/[a-z]/i', 'Phone cannot contain letters');
$error = Param::get('phone')->process(['phone'=>''])->error;
var_dump($error);NULL
If you want to make sure the value is not empty use the required filter before ifmatch.
Produces an error when the string DOES NOT MATCH a pattern:
use FlSouto\Param;
Param::get('date')->filters()->ifnot('/^\d{4}-\d{2}-\d{2}$/','Date is expected to be in the format yyyy-mm-dd');
$error = Param::get('date')->process(['date'=>'10/12/1992'])->error;
var_dump($error);string(47) "Date is expected to be in the format yyyy-mm-dd"
Notice: This validator is only applied when the value is not empty:
use FlSouto\Param;
Param::get('login')->filters()->ifnot('\w','Login must contain at least one letter');
$error = Param::get('login')->process([])->error;
var_dump($error);NULL
Makes sure the length of the string doesn't exceed a maximum:
use FlSouto\Param;
Param::get('description')->filters()->maxlen(30, "Description must be less than %d characters long!");
$error = Param::get('description')
->process(['description'=>str_repeat('lorem ipsum', 10)])
->error;
var_dump($error);string(49) "Description must be less than 30 characters long!"
Makes sure the length of a string is at least certain characters long:
use FlSouto\Param;
Param::get('description')->filters()->minlen(10, "Description must be at least %d characters long!");
$error = Param::get('description')->process(['description'=>'Test'])->error;
var_dump($error);string(48) "Description must be at least 10 characters long!"
Notice: This validator is only applied when the value is not empty:
use FlSouto\Param;
Param::get('description')->filters()->minlen(10, "Description must be at least %d characters long!");
$error = Param::get('description')->process(['description'=>''])->error;
var_dump($error);NULL
Makes sure an integer is not more than certain value:
use FlSouto\Param;
Param::get('age')->filters()->maxval(150, "Age cannot be more than %d!");
$error = Param::get('age')->process(['age'=>200])->error;
var_dump($error);string(28) "Age cannot be more than 150!"
Makes sure the integer, if provided, is at least larger than X:
use FlSouto\Param;
Param::get('age')->filters()->minval(1, "Age cannot be less than %d!");
$error = Param::get('age')->process(['age'=>0])->error;
var_dump($error);string(26) "Age cannot be less than 1!"
Notice: This validator is only applied when the value is not empty:
use FlSouto\Param;
Param::get('age')->filters()->minval(1, "Age cannot be less than %d!");
$error = Param::get('age')->process(['age'=>null])->error;
var_dump($error);NULL
Last but not least, you can use method chaning for adding multiple filters. The filters will be applied to the value in the same order they were added:
<?php
require_once('vendor/autoload.php');
use FlSouto\Param;
Param::get('number')
->filters()
->strip('/[^\d]/')
->required()
->minlen(5)
->maxlen(10);
$result = Param::get('number')->process([
'number' => '203-40-10/80'
]);
var_dump($result->output);In the example above the data will be filtered before the validation constraints and the result will be:
string(9) "203401080"