__tostring()

El método mágico __toString()

__toString() es uno de los métodos mágicos de PHP — métodos especiales que PHP llama automáticamente en ciertas situaciones. Específicamente, PHP llama a __toString() siempre que un objeto se usa donde se espera una cadena: en echo, print, concatenación de cadenas con ., dentro de cadenas entre comillas dobles, cuando se pasa a una función con type-hint string, etc.

Sin __toString(), intentar usar un objeto como cadena lanza un error:

Object of class Foo could not be converted to string

Al definir __toString(), tú decides cómo luce esa representación en cadena. Esta página cubre la firma del método, las reglas que PHP impone, ejemplos funcionales y los errores comunes.

Por qué usarlo

Se recurre a __toString() cuando un objeto tiene una forma textual significativa y se quiere que "simplemente funcione" en contextos de cadena. Casos típicos:

• Un objeto Money que debe mostrarse como "$19.99".
• Un objeto User que debe imprimirse con su nombre completo en una plantilla.
• Un objeto de valor (fecha, URL, coordenada) que se quiere registrar o mostrar sin llamar a un getter cada vez.

Mantiene el código de llamada limpio — echo $user; en lugar de echo $user->getFullName();.

Sintaxis

public function __toString(): string

El método no toma argumentos y debe devolver una cadena. Desde PHP 8.0, el tipo de retorno : string se aplica implícitamente aunque se omita — devolver cualquier otra cosa genera un TypeError.

Ejemplo básico

Aquí le damos a un objeto Money una forma de cadena legible:

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

Puedes ejecutar este ejemplo con el botón de prueba que aparece arriba.

Cuando se ejecuta echo $price, PHP detecta un objeto donde se necesita una cadena, por lo que llama a $price->__toString() en segundo plano y utiliza el valor devuelto. Lo mismo ocurre dentro de la cadena entre comillas dobles "Total: {$price}".

__toString() debe devolver una cadena

El tipo de retorno : string significa que PHP debe obtener una cadena. Los valores escalares como 42 se convierten automáticamente a "42", pero los valores que no pueden convertirse — como un array — lanzan 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

Siempre construye y devuelve una cadena real para que la conversión sea explícita y nunca te sorprenda.

Interfaz Stringable

Desde PHP 8.0, cualquier clase que declare __toString() implementa automáticamente la interfaz integrada Stringable. Puedes usar type-hint con Stringable (o string|Stringable) para aceptar "cualquier cosa que pueda convertirse en cadena":

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

Declarar implements Stringable de forma explícita es opcional (PHP lo añade automáticamente) pero deja clara tu intención a los lectores y a las herramientas de análisis estático.

Errores comunes

• No se puede lanzar excepciones con throw desde __toString() antes de PHP 7.4. En PHP 7.4+ se permiten excepciones; en versiones anteriores, lanzar una excepción dentro de __toString() causaba un error fatal. Mantén el método simple y sin efectos secundarios.
• Debe ser public. Un __toString() privado o protegido no es accesible desde el contexto de cadena que lo activa.
• El cast (string) también lo activa. (string) $object es la forma explícita de invocar __toString().

Conclusión

__toString() permite que un objeto defina su propia representación en cadena para que pueda usarse con echo, concatenarse e interpolarse como una cadena simple. Mantenlo puro, devuelve siempre una cadena y considera usar type-hint con Stringable cuando una función deba aceptar tanto cadenas como objetos similares a cadenas. Para profundizar, consulta Clases y objetos en PHP, el método mágico constructor __construct() y Cadenas en PHP.

Práctica