uuf6429 / php-castable
Type casting functionality for PHP
Requires
- php: ^8
Requires (Dev)
- ergebnis/composer-normalize: ^2.7
- friendsofphp/php-cs-fixer: ^3.3
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^9 || ^10 || ^11
- roave/security-advisories: dev-latest
README
Basic groundwork for type-casting in PHP.
🔌 Installation
The recommended and easiest way to install this library is through Composer:
composer require uuf6429/php-castable
⭐️ Features / Functionality
- Works with simple types and objects
cast($value, $type)
function that converts a value to a target type.Castable
interface, exposes method that is called whenevercast()
is called on objects implementing this interface.- Error handling - all errors routed to
NotCastableException
. - Fixes type-hinting for IDEs understanding PHPDoc Generics.
While cast()
is just a regular PHP function, it would be the equivalent to type-casting operators in other languages (e.g. val as Type
, (Type)val
, val.to(Type)
, CAST(val, TYPE)
...).
🚀 Example
class Cat implements \uuf6429\Castable\Castable { public function castTo($type) { if ($type === Dog::class) { return new Dog(); } throw new RuntimeException("Unsupported type $type."); } } class Dog {} $dog = \uuf6429\Castable\cast(new Cat(), Dog::class); // ok, cat becomes a dog :) $cat = \uuf6429\Castable\cast($dog, Cat::class); // not allowed
🔍 Casting Behaviour
The casting process follows these steps:
- If the value is an object or value of the desired type, then it is returned unchanged.
- If the value is an object that implements
Castable
interface,castTo()
is called and its value returned. - Otherwise, PHP's
settype()
is attempted.
At any point in time, errors or unsupported type-casting could occur, in which case a NotCastableException
is thrown.
💰 Motivation
In many cases, having specific castToX()
methods in your classes is enough, and it typically works adequately.
However, this could get very repetitive and somewhat error-prone, until a more dynamic solution is needed. This package helps to safely avoid all that boilerplate code.