README

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[] and DateTime[])
boolean
float
integer
number (int|float)
mixed
object (includes casting to a specific class)
resource
string
multiple (e.g. int|string and string|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());

jasny / typecast

Maintainers

Details