wildphp / type-definitions
Type definition and validation library
Installs: 203
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Type:project
Requires
- php: ^7.2|^8.0
Requires (Dev)
- phpmd/phpmd: ^2.9.1
- phpstan/phpstan: ^0.12.84
- phpunit/phpunit: ^8.5
- squizlabs/php_codesniffer: ^3.6.0
README
Library to provide type validation and expression. Includes an interpreter to transform short and concise syntax into usable types.
Installation
In order to use this library, install it through Composer:
$ composer require wildphp/type-definitions
Type definitions using classes
Type definitions can be built using the classes in this library. There are 3 main classes:
PrimitiveTypeDefinition
ClassTypeDefinition
ArrayTypeDefinition
PrimitiveTypeDefinition
Primitive type definitions are those who refer to scalar or otherwise built-in types.
PrimitiveTypeDefinition
acts as a wrapper around gettype().
For example:
$definition = new \WildPHP\TypeDefinitions\PrimitiveTypeDefinition('string'); echo $definition->validate('this is a valid string'); // true echo $definition->validate(1); // false echo $definition->validate(false); // false
Alternatively, types may be specified using one of the constants on the PrimitiveTypeDefinition
class.
These map to the type specifiers for gettype()
and are recommended to be used instead of specifying types manually.
$definition = new \WildPHP\TypeDefinitions\PrimitiveTypeDefinition(\WildPHP\TypeDefinitions\PrimitiveTypeDefinition::STRING);
ClassTypeDefinition
Class type definitions validate their value using instanceof. This means that any class will pass this definition if it is an instance of, or inheritor of, the given class.
null
is also considered a valid value.
For example:
$definition = new \WildPHP\TypeDefinitions\ClassTypeDefinition(stdClass::class); $object = new stdClass(); echo $definition->validate($object); // true echo $definition->validate(null); // true echo $definition->validate('this is a string'); // false echo $definition->validate(1); // false echo $definition->validate(false); // false
ArrayTypeDefinition
Array type definitions validate their values using a child type definition (a content definition). This makes it possible to write complex nested structures.
Please note that ArrayTypeDefinition only validates values and not keys. Key validation would not make a lot of sense, since PHP itself limits key types to strings and integers.
Validation will fail when any of the children does not conform to the content definition.
For example:
$childDefinition = new \WildPHP\TypeDefinitions\PrimitiveTypeDefinition('string'); $definition = new \WildPHP\TypeDefinitions\ArrayTypeDefinition($childDefinition); echo $definition->validate(['this is a valid string', 'another valid string']); // true echo $definition->validate(1); // false echo $definition->validate([1]); // false echo $definition->validate(false); // false echo $definition->validate([false]); // false echo $definition->validate(['this is a string', 1]); // false, because 1 does not conform
Type definitions using maps and strings
The library provides a TypeDefinitionInterpreter
helper class to translate maps and strings into TypeDefinitionInterface
instances.
This is used in the models library to provide swift model declaration and validation.
createDefinitionMap
is used to translate the values of key-value based arrays into TypeDefinitionInterface implementations.
This method will preserve keys and will not modify the existing array.
For example:
$map = [ 'array' => ['string'], 'string' => 'string', 'stdClass' => stdClass::class ]; $interpreted = \WildPHP\TypeDefinitions\TypeDefinitionInterpreter::createDefinitionMap($map); // $interpreted['array'] is now an instance of ArrayTypeDefinition with a content definition of PrimitiveTypeDefinition with type 'string' // $interpreted['string'] is now an instance of PrimitiveTypeDefinition with type 'string' // $interpreted['stdClass'] is now an instance of ClassTypeDefinition with class identifier stdClass::class
If you do not need to interpret a map but would rather interpret a single value, use the interpret
function:
$definition = 'string'; $interpreted = \WildPHP\TypeDefinitions\TypeDefinitionInterpreter::interpret($definition); // $interpreted is now an instance of PrimitiveTypeDefinition with type 'string'