README.md

🎭 PHP Castable

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 whenever cast() 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:

1. If the value is an object or value of the desired type, then it is returned unchanged.
2. If the value is an object that implements Castable interface, castTo() is called and its value returned.
3. 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.