Componere\cast — Funktion · PHP-Referenz

Signatur

Componere\cast(object $instance, Componere\Definition $definition): object

Beschreibung

Componere\cast ist Teil der Componere-Extension und ermöglicht es, eine vorhandene Objektinstanz dynamisch in einen anderen Typ zu überführen. Dabei wird die übergebene Componere\Definition verwendet, um den Zieltyp zu beschreiben. Das ursprüngliche Objekt bleibt unberührt; die Funktion gibt eine neue Instanz des definierten Typs zurück.

Das Casting ist besonders nützlich in Szenarien, in denen man mit Objekten aus externem Code oder Frameworks arbeitet und diese zur Laufzeit mit zusätzlichen Interfaces, Methoden oder Properties ausstatten möchte, ohne Klassen dauerhaft zu verändern (im Gegensatz zu Componere\patch). So kann man z. B. Objekte temporär mit Interfaces versehen, um sie an typsichere APIs zu übergeben.

Das resultierende Objekt teilt sich denselben internen Zustand (Properties) wie das Original, da die Daten aus der Quellinstanz übernommen werden. Methoden, die in der Definition definiert sind, stehen im neuen Objekt zur Verfügung, während die ursprüngliche Klasse unverändert bleibt.

Zu beachten ist, dass Componere\cast nur mit Objekten (nicht mit primitiven Werten) arbeitet und eine korrekt aufgebaute Componere\Definition erwartet, die kompatibel mit dem Ausgangstyp ist.

Parameter

Name	Typ	Default	Beschreibung
$instance Pflicht	object		Die Quellobjectinstanz, die umgewandelt werden soll. Ihr Zustand (Properties) wird in das neue Objekt übernommen.
$definition Pflicht	Componere\Definition		Die `Componere\Definition`, die den Zieltyp beschreibt, einschließlich zusätzlicher Methoden, Properties und zu implementierender Interfaces.

Rückgabewert

Typ

object

Beschreibung

Gibt eine neue Objektinstanz zurück, die dem durch Componere\Definition beschriebenen Typ entspricht und den Zustand der Quellinstanz trägt.

Beispiele

Objekt dynamisch mit einem Interface versehen

<?php
use Componere\Definition;
use Componere\Method;

interface Serializable2 {
    public function serialize2(): string;
}

class User {
    public string $name;
    public int $age;

    public function __construct(string $name, int $age) {
        $this->name = $name;
        $this->age  = $age;
    }
}

$user = new User('Alice', 30);

// Definition für den Zieltyp erstellen: User + Serializable2
$definition = new Definition(User::class, [Serializable2::class]);
$definition->addMethod('serialize2', new Method(function(): string {
    return json_encode(['name' => $this->name, 'age' => $this->age]);
}));

// Cast ausführen
$castUser = Componere\cast($user, $definition);

// Das neue Objekt implementiert das Interface
echo ($castUser instanceof Serializable2) ? 'true' : 'false'; // true
echo $castUser->serialize2(); // {"name":"Alice","age":30}

// Das Original ist unverändert
echo ($user instanceof Serializable2) ? 'true' : 'false'; // false

true {"name":"Alice","age":30} false

Typsicheres Übergeben an eine restriktive API

<?php
use Componere\Definition;
use Componere\Method;

interface Loggable {
    public function getLogMessage(): string;
}

function logEntity(Loggable $entity): void {
    echo '[LOG] ' . $entity->getLogMessage() . PHP_EOL;
}

class Order {
    public int $id;
    public float $total;

    public function __construct(int $id, float $total) {
        $this->id    = $id;
        $this->total = $total;
    }
}

$order = new Order(42, 199.99);

$def = new Definition(Order::class, [Loggable::class]);
$def->addMethod('getLogMessage', new Method(function(): string {
    return "Order #{$this->id}, Total: {$this->total}";
}));

$loggableOrder = Componere\cast($order, $def);
logEntity($loggableOrder);

[LOG] Order #42, Total: 199.99

// Wichtig · Fallstricke

Erweiterung erforderlich: Componere\cast ist keine eingebaute PHP-Funktion, sondern Teil der Componere PECL-Extension, die separat installiert werden muss (pecl install componere).

Lebensdauer: Der Cast ist temporär und gilt nur für die zurückgegebene Instanz. Im Gegensatz zu Componere\patch oder Componere\patch_reverse wird die ursprüngliche Klasse nicht global modifiziert.

Kompatibilität: Die Definition muss auf derselben Basisklasse wie $instance aufgebaut sein, sonst wird eine Componere\Exception geworfen.

PHP-Version: Die Extension unterstützt PHP 7 und PHP 8; die genaue Mindestversion hängt von der installierten Extension-Version ab.

Siehe auch

Componere\Definition Componere\patch Componere\Method Componere\cast_by_ref