# Parameter
Namespace Chevere\Parameter
The Parameter component is in charge of providing an user-land typed layer abstraction around parameter-argument. Intended to be used in I/O validation systems, this component provide dynamic parameter-argument type matching relying on the Type component.
To summarize, Parameter enables to validate any type of arguments for any kind of data-structure.
# Array Parameter
Use function arrayp
to create an array parameter for required array keys.
use function Chevere\Parameter\arrayp;
// Empty array
$parameter = arrayp();
// With required 'a' key
$parameter = arrayp(a: string());
# With parameters
Use method withRequired
to define required parameters to an existing object implementing ArrayParameterInterface
.
$parameter = $parameter
->withRequired(
username: string(),
email: string()
);
Use method withOptional
to define optional parameters to an existing object implementing ArrayParameterInterface
.
$parameter = $parameter
->withOptional(email: string());
👉 Note: Optional parameters will be validated only if a matching key is provided.
# Array String
Use function arrayString
to create an array parameter for required array keys. It only supports string parameters.
use function Chevere\Parameter\arrayString;
use function Chevere\Parameter\string;
$parameter = arrayString(
test: string(),
);
# Array assertion
Use function assertArray
to validate an array parameter against an array argument. It returns the typed array.
use function Chevere\Parameter\assertArray;
$parameter = arrayp(
a: string(),
b: integer(),
);
$argument = [
'a' => 'Hello world',
'b' => 123
];
$assert = assertArray($parameter, $argument);
// $assert same as $argument
If you define a default value for any parameter the system will fill in that value when not provided.
use function Chevere\Parameter\assertArray;
$parameter = arrayp(
foo: integer(default: 100),
);
$argument = [];
$assert = assertArray($parameter, $argument);
// $assert = ['foo' => 100];
# Boolean Parameter
Use function boolean
to create a parameter implementing BooleanParameterInterface
. This function can define description
and a default
value.
use function Chevere\Parameter\boolean;
$parameter = boolean();
# Boolean assertion
Use function assertBoolean
to validate a boolean parameter against a boolean argument.
use function Chevere\Parameter\assertBoolean;
$parameter = boolean();
$argument = true;
assertBoolean($parameter, $argument);
# File Parameter
Use function file
to create a parameter implementing FileParameterInterface
. This function can define description
, name
, type
and tmp_name
.
use function Chevere\Parameter\file;
// Any file
$parameter = file();
# File assertion
Use function assertFile
to validate a file parameter against a file argument.
use function Chevere\Parameter\assertFile;
$parameter = file(
// Name starting with chevere
name: string('/^chevere/'),
// Limited range size
size: integer(
minimum: 1000,
maximum: 500000
),
// Image types
type: string('/^image\/*$/')
);
$argument = [
'name' => 'chevere.png',
'size' => 1234,
'type' => 'image/png'
];
assertFile($parameter, $argument);
# Float Parameter
Use function float
to create a parameter implementing FloatParameterInterface
. This function can define description
, default
value, minimum
value, maximum
value and a float list of accept
values.
use function Chevere\Parameter\float;
// Any float
$float = float();
// Limited range float
$float = float(
minimum: 0,
maximum: 100
);
// Exact float match
$float = float(
accept: [1, 2, 3]
);
# Float assertion
Use function assertFloat
to validate a float parameter against a float argument.
use function Chevere\Parameter\assertFloat;
$parameter = float(
minimum: 0.0,
maximum: 10.0
);
$argument = 5.5;
assertFloat($parameter, $argument);
# Generic Parameter
Use function generic
to create a parameter implementing GenericParameterInterface
. This function can define a parameter value V
and parameter key K
.
💡 A generic parameter is used to match a variable collection of n-items
.
use function Chevere\Parameter\generic;
// For a collection of integer keys
// and string values
$parameter = generic(
string(),
);
# Generic assertion
Use function assertGeneric
to validate a generic parameter against a generic argument.
use function Chevere\Parameter\assertGeneric;
$parameter = generic(
K: integer(minimum: 0),
V: arrayp(
id: string(),
name: string(),
),
);
$argument = [
0 => [
'id' => '123e4567',
'name' => 'Rodolfo'
],
1 => [
'id' => '123e4568',
'name' => 'Alejandro'
],
// ...
];
assertGeneric($parameter, $argument);
# Integer Parameter
Use function integer
to create a parameter implementing IntegerParameterInterface
. This function can define description
, default
value, minimum
value, maximum
value and a integer list of accept
values.
use function Chevere\Parameter\integer;
// Any integer
$integer = integer();
// Limited range integer
$integer = integer(
minimum: 0,
maximum: 100
);
// Exact integer match
$integer = integer(
accept: [1, 2, 3]
);
# Integer assertion
Use function assertInteger
to validate an integer parameter against an integer argument.
use function Chevere\Parameter\assertInteger;
$parameter = integer(
minimum: 0.0,
maximum: 10.0
);
$argument = 5.5;
assertInteger($parameter, $argument);
# Null Parameter
Use function null
to create a parameter implementing NullParameterInterface
. This function can define description
.
use function Chevere\Parameter\null;
$null = null();
# Null assertion
Use function assertNull
to validate a null parameter against a null argument.
use function Chevere\Parameter\assertNull;
$parameter = null();
$argument = null;
assertNull($parameter, $argument);
# Object Parameter
Use function object
to create a parameter implementing ObjectParameterInterface
. This function can define a clasName
and a description
.
use function Chevere\Parameter\object;
$object = object(stdClass::class);
# Object assertion
Use function assertObject
to validate an object parameter against an object argument.
use function Chevere\Parameter\assertObject;
$parameter = object();
$argument = new stdClass();
assertObject($parameter, $argument);
# String Parameter
Use function string
to create a parameter implementing StringParameterInterface
. This function can define a regex
for string matching, a description
and a default
value.
use function Chevere\Parameter\string;
// Any string
$parameter = string();
// A string matching id-123
$string = string('/^id-[\d]+$/');
# Enum string
Use function enump
to create an enum string parameter. This function takes strings used for the enumeration.
use function Chevere\Parameter\enum;
// A string matching on OR off
$parameter = enum('on', 'off');
# Date string
Use function date
to create a date string parameter for YYYY-MM-DD
. This function can define description
and a default
value.
use function Chevere\Parameter\date;
// A YYYY-MM-DD string
$parameter = date();
# Time string
Use function time
to create a time string parameter for hh:mm:ss
. This function can define description
and a default
value.
use function Chevere\Parameter\time;
// A hh:mm:ss string
$parameter = time();
# Datetime string
Use function datetime
to create a datetime string parameter for YYYY-MM-DD hh:mm:ss
. This function can define description
and a default
value.
use function Chevere\Parameter\datetime;
// A YYYY-MM-DD hh:mm:ss
$parameter = datetime();
# String assertion
Use function assertString
to validate a string parameter against a string argument.
use function Chevere\Parameter\assertString;
$parameter = string('/^a|b|c$/');
$argument = 'a';
assertString($parameter, $argument);
# Union Parameter
Use function union
to create a parameter implementing UnionParameterInterface
. An union parameter works similar to PHP's union type as it enables to validate an argument against multiple types.
use function Chevere\Parameter\union;
// Any string or null
$union = union(string(), null());
// Any digit string or any integer
$union = union(
string('/^\d+$/'),
integer()
);
# Union assertion
Use function assertUnion
to validate an union parameter against a mixed argument.
use function Chevere\Parameter\assertUnion;
$union = union(string(), integer());
assertUnion($parameter, 'abc');
assertUnion($parameter, 0);
# Argument assertion
Use function assertArgument
to validate a parameter against an argument of any type. Useful when there's no certainty on the argument type.
use function Chevere\Parameter\assertArgument;
$parameter = string();
assertArgument($parameter, $argument);