__tostring()

Die __toString() Magic-Methode

__toString() ist eine der Magic-Methoden von PHP — spezielle Methoden, die PHP automatisch in bestimmten Situationen aufruft. Konkret ruft PHP __toString() immer dann auf, wenn ein Objekt dort verwendet wird, wo ein String erwartet wird: in echo, print, bei der String-Verkettung mit ., innerhalb von Strings in doppelten Anführungszeichen, wenn es an eine Funktion mit dem Typhinweis string übergeben wird, und so weiter.

Ohne __toString() führt der Versuch, ein Objekt als String zu verwenden, zu einem Fehler:

Object of class Foo could not be converted to string

Durch das Definieren von __toString() entscheiden Sie, wie diese String-Darstellung aussieht. Diese Seite behandelt die Signatur der Methode, die von PHP erzwungenen Regeln, funktionierende Beispiele und häufige Fallstricke.

Wann verwenden

__toString() kommt zum Einsatz, wenn ein Objekt eine sinnvolle textuelle Form hat und in String-Kontexten „einfach funktionieren" soll. Typische Anwendungsfälle:

• Ein Money-Objekt, das als "$19.99" dargestellt werden soll.
• Ein User-Objekt, das in einem Template als vollständiger Name ausgegeben werden soll.
• Ein Wertobjekt (Datum, URL, Koordinate), das Sie protokollieren oder ausgeben möchten, ohne jedes Mal einen Getter aufzurufen.

Der aufrufende Code bleibt dadurch übersichtlich — echo $user; statt echo $user->getFullName();.

Syntax

public function __toString(): string

Die Methode nimmt keine Argumente entgegen und muss einen String zurückgeben. Seit PHP 8.0 wird der Rückgabetyp : string implizit erzwungen, auch wenn Sie ihn weglassen — die Rückgabe eines anderen Typs löst einen TypeError aus.

Grundlegendes Beispiel

Hier geben wir einem Money-Objekt eine lesbare String-Form:

<?php

class Money
{
    public function __construct(
        private int $cents,
        private string $currency = 'USD'
    ) {}

    public function __toString(): string
    {
        $amount = number_format($this->cents / 100, 2);
        return "{$amount} {$this->currency}";
    }
}

$price = new Money(1999);

echo $price;            // 19.99 USD
echo "Total: {$price}"; // Total: 19.99 USD

Sie können dies über die Schaltfläche oben ausprobieren.

Wenn echo $price ausgeführt wird, erkennt PHP ein Objekt, wo ein String erwartet wird, und ruft daher im Hintergrund $price->__toString() auf und verwendet den zurückgegebenen Wert. Dasselbe geschieht innerhalb des Strings mit doppelten Anführungszeichen "Total: {$price}".

__toString() muss einen String zurückgeben

Der Rückgabetyp : string bedeutet, dass PHP zwingend einen String erhält. Skalare Werte wie 42 werden automatisch zu "42" umgewandelt, aber Werte, die nicht umgewandelt werden können — wie ein Array — lösen einen TypeError aus:

<?php

class Broken
{
    public function __toString(): string
    {
        return [1, 2]; // wrong: an array cannot become a string
    }
}

echo new Broken();
// TypeError: Broken::__toString(): Return value must be of type string, array returned

Erstellen und geben Sie immer einen echten String zurück, damit die Konvertierung explizit ist und Sie nie überrascht.

Stringable-Interface

Seit PHP 8.0 implementiert jede Klasse, die __toString() deklariert, automatisch das eingebaute Stringable-Interface. Sie können Stringable (oder string|Stringable) als Typhinweis verwenden, um „alles, was zu einem String werden kann" zu akzeptieren:

<?php

function greet(string|Stringable $who): void
{
    echo "Hello, {$who}!\n";
}

class Name implements Stringable
{
    public function __construct(private string $value) {}

    public function __toString(): string
    {
        return $this->value;
    }
}

greet('world');        // Hello, world!
greet(new Name('Ada')); // Hello, Ada!

Das explizite Deklarieren von implements Stringable ist optional (PHP fügt es für Sie hinzu), macht aber Ihre Absicht für Leser und statische Analyse-Tools deutlicher.

Fallstricke

• Sie können in __toString() vor PHP 7.4 keine Exception werfen. In PHP 7.4+ sind Exceptions erlaubt; in älteren Versionen verursachte das Werfen innerhalb von __toString() einen fatalen Fehler. Halten Sie die Methode einfach und ohne Nebeneffekte.
• Sie muss public sein. Eine private oder protected __toString() ist im String-Kontext, der sie auslöst, nicht aufrufbar.
• Der (string)-Cast löst sie ebenfalls aus. (string) $object ist die explizite Methode, um __toString() aufzurufen.

Fazit

__toString() ermöglicht es einem Objekt, seine eigene String-Darstellung zu definieren, sodass es wie ein einfacher String ausgegeben, verkettet und interpoliert werden kann. Halten Sie die Methode rein, geben Sie immer einen String zurück und erwägen Sie den Typhinweis Stringable, wenn eine Funktion sowohl Strings als auch stringartige Objekte akzeptieren soll. Für weitere Informationen lesen Sie PHP Klassen und Objekte, die Magic-Methode Konstruktor __construct() und PHP Strings.

Übung