Jasny TypeCast
This library does type casting in PHP.
Type casting is natively supported in PHP. This library adds some basic logic to the process, like triggering a warning
when casting a string like "FOO"
to an integer.
In contrary to PHP's internal type casting, casting null
always results in null
.
Installation
The Jasny TypeCast package is available on packagist. Install it using composer:
composer require jasny/typecast
Usage
use Jasny\TypeCast;
$typecast = new TypeCast();
$typecast->to('string')->cast(null); // null
$typecast->to('integer')->cast('987'); // 987
$typecast->to(DateTime::class)->cast('2015-01-01'); // new DateTime('2015-01-01)
$typecast->to(FooBar::class)->cast($data); // FooBar::__set_state($data)
// Unable to cast
$typecast->to('float')->cast('red'); // 'red' + triggers a notice
$typecast->to('int')->cast(new stdClass()); // stdClass object + triggers a notice
Alias
You can set aliases in cases where you might need to cast to an interface or abstract class or when you want to cast to a child class.
$typecast = new TypeCast();
$typecast->alias(FooBarInterface::class, FooBar::class);
$typecast->to(FooBarInterface::class)->cast($data); // FooBar::__set_state($data)
Errors
By default an E_NOTICE
is triggered if a value can't be casted to desired type. Jasny\TypeCast
follows stricter
rules than PHP for casting values.
Instead of a notice an error of any severity can be triggered. Alternatively any Throwable
like an exception or
error can be thrown.
$typecast = new TypeCast();
$typecast->failWith(E_USER_WARNING);
$typecast->failWith(TypeError::class);
$typecast->failWith(UnexpectedValueException::class);
Variable name in error
You can use the setName()
method to set the property or variable name that is casted. This name will be included in
any error triggered when type casting. This can be useful when determining an issue.
$foo = 'red';
$typecast->value($foo)->setName('foo')->to('float');
Dependency injection
If your application supports dependency injection through containers, create a new TypeCast
object and add it to the
container as a service.
The value()
method will clone the TypeCast
object. Settings like any aliases or custom handlers will propagate.
use Jasny\TypeCast;
use Jasny\TypeCastInterface;
$container = new Container([
TypeCastInterface::class => function() {
$typecast = new TypeCast();
$typecast->alias(FooBarInterface::class, FooBar::class);
return $typecast;
}
]);
$container->get(TypeCastInterface::class)->value('987')->to('integer');
Assume that Container
is any PSR-11 compatible container.
Handlers
The Typecast
object uses handlers to cast a value. Each handler can cast a value to a specific type. The following
handlers are defined:
- array (includes typed arrays as
string[]
andDateTime[]
) - boolean
- float
- integer
- number (
int|float
) - mixed
- object (includes casting to a specific class)
- resource
- string
- multiple (e.g.
int|string
andstring|string[]
)
You may overwrite the handlers when creating the TypeCast
object.
Desire
The desire
method will return the handler. This is an alternative approach of using the value
method. If you need to
cast multiple values to the same type, it's recommendable to get the handler once using desire
.
use Jasny\TypeCast;
$typecast = new TypeCast();
$typecast->desire('integer')->cast('10');
$arrayHandler = $typecast->desire('array');
foreach ($items as &$item) {
$item = $arrayHandler->cast($item);
}
Multiple handler
In cast multiple types are specified, the handler will try to guess the type the value should be cast in. This might
hurt performance. You may use NoTypeGuess
to have the handler give an error if the type can't be determined.
use Jasny\TypeCast;
$multipleHandler = new TypeCast\Handlers\MultipleHandler(new TypeCast\NoTypeGuess());
$typecast = new TypeCast(null, ['multiple' => $multipleHandler] + TypeCast::getDefaultHandlers());