__tostring()

Il Metodo Magico __toString()

__toString() è uno dei metodi magici di PHP — metodi speciali che PHP chiama automaticamente in determinate situazioni. In particolare, PHP chiama __toString() ogni volta che un oggetto viene utilizzato dove è attesa una stringa: in echo, print, nella concatenazione di stringhe con ., all'interno di stringhe con doppi apici, quando passato a una funzione che prevede il tipo string, e così via.

Senza __toString(), tentare di usare un oggetto come stringa genera un errore:

Object of class Foo could not be converted to string

Definendo __toString(), sei tu a decidere come appare quella rappresentazione stringa. Questa pagina tratta la firma del metodo, le regole che PHP impone, esempi funzionanti e gli errori più comuni.

Perché usarlo

Si ricorre a __toString() quando un oggetto ha una forma testuale significativa e si vuole che "funzioni direttamente" nei contesti stringa. Casi tipici:

• Un oggetto Money che deve essere visualizzato come "$19.99".
• Un oggetto User che deve stampare il nome completo in un template.
• Un oggetto valore (data, URL, coordinata) che si vuole registrare o visualizzare senza chiamare ogni volta un getter.

Mantiene il codice chiamante pulito — echo $user; invece di echo $user->getFullName();.

Sintassi

public function __toString(): string

Il metodo non accetta argomenti e deve restituire una stringa. Da PHP 8.0 il tipo di ritorno : string è implicitamente applicato anche se omesso — restituire qualsiasi altra cosa genera un TypeError.

Esempio base

Qui diamo a un oggetto Money una forma stringa leggibile:

<?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

Puoi eseguire questo codice con il pulsante try-it qui sopra.

Quando viene eseguito echo $price, PHP rileva un oggetto dove è necessaria una stringa, quindi chiama $price->__toString() in background e usa il valore restituito. La stessa cosa accade all'interno della stringa con doppi apici "Total: {$price}".

__toString() deve restituire una stringa

Il tipo di ritorno : string significa che PHP deve ottenere una stringa. I valori scalari come 42 vengono convertiti automaticamente in "42", ma i valori che non possono essere convertiti — come un array — generano un TypeError:

<?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

Costruisci e restituisci sempre una vera stringa in modo che la conversione sia esplicita e non ti sorprenda mai.

Interfaccia Stringable

Da PHP 8.0, qualsiasi classe che dichiara __toString() implementa automaticamente l'interfaccia integrata Stringable. Puoi usare il tipo Stringable (o string|Stringable) per accettare "qualsiasi cosa che possa diventare una stringa":

<?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!

Dichiarare implements Stringable esplicitamente è facoltativo (PHP lo aggiunge per te) ma rende chiara l'intenzione ai lettori e agli strumenti di analisi statica.

Errori comuni

• Non è possibile usare throw in __toString() prima di PHP 7.4. In PHP 7.4+ le eccezioni sono consentite; nelle versioni precedenti, lanciare un'eccezione all'interno di __toString() causava un errore fatale. Mantieni il metodo semplice e privo di effetti collaterali.
• Deve essere public. Un __toString() privato o protetto non è richiamabile dal contesto stringa che lo attiva.
• Il casting (string) lo attiva anch'esso. (string) $object è il modo esplicito per invocare __toString().

Conclusione

__toString() consente a un oggetto di definire la propria rappresentazione stringa in modo da poter essere visualizzato con echo, concatenato e interpolato come una semplice stringa. Mantienilo puro, restituisci sempre una stringa e considera di usare il tipo Stringable quando una funzione deve accettare sia stringhe che oggetti simili a stringhe. Per approfondire, consulta Classi e Oggetti PHP, il metodo magico costruttore __construct() e le Stringhe PHP.

Pratica