__tostring()

O Método Mágico __toString()

__toString() é um dos métodos mágicos do PHP — métodos especiais que o PHP chama automaticamente em determinadas situações. Especificamente, o PHP chama __toString() sempre que um objeto é usado onde uma string é esperada: em echo, print, concatenação de strings com ., dentro de strings entre aspas duplas, quando passado a uma função com type-hint string, e assim por diante.

Sem __toString(), tentar usar um objeto como string lança um erro:

Object of class Foo could not be converted to string

Ao definir __toString(), você decide como essa representação em string será. Esta página aborda a assinatura do método, as regras que o PHP aplica, exemplos funcionais e os erros comuns.

Por que usá-lo

Você recorre ao __toString() quando um objeto possui uma forma textual significativa e você quer que ele "funcione de imediato" em contextos de string. Casos típicos:

• Um objeto Money que deve ser renderizado como "$19.99".
• Um objeto User que deve ser impresso com o nome completo em um template.
• Um objeto de valor (data, URL, coordenada) que você quer registrar ou exibir sem chamar um getter toda vez.

Isso mantém o código chamador limpo — echo $user; em vez de echo $user->getFullName();.

Sintaxe

public function __toString(): string

O método não recebe argumentos e deve retornar uma string. Desde o PHP 8.0, o tipo de retorno : string é implicitamente aplicado mesmo se omitido — retornar qualquer outra coisa dispara um TypeError.

Exemplo básico

Aqui damos a um objeto Money uma forma em string legível:

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

Você pode executar isso com o botão "experimentar" acima.

Quando echo $price é executado, o PHP vê um objeto onde uma string é necessária, então chama $price->__toString() nos bastidores e usa o valor retornado. O mesmo acontece dentro da string entre aspas duplas "Total: {$price}".

__toString() deve retornar uma string

O tipo de retorno : string significa que o PHP deve terminar com uma string. Valores escalares como 42 são coagidos para "42" automaticamente, mas valores que não podem ser coagidos — como um array — lançam um 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

Sempre construa e retorne uma string real para que a conversão seja explícita e nunca cause surpresas.

Interface Stringable

Desde o PHP 8.0, qualquer classe que declare __toString() implementa automaticamente a interface integrada Stringable. Você pode usar type-hint Stringable (ou string|Stringable) para aceitar "qualquer coisa que possa se tornar uma string":

<?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 explicitamente é opcional (o PHP adiciona por você), mas deixa sua intenção clara para leitores e ferramentas de análise estática.

Erros comuns

• Você não pode usar throw em __toString() antes do PHP 7.4. No PHP 7.4+ as exceções são permitidas; em versões anteriores, lançar dentro de __toString() causava um erro fatal. Mantenha o método simples e sem efeitos colaterais.
• Deve ser public. Um __toString() privado ou protegido não pode ser chamado a partir do contexto de string que o aciona.
• O cast (string) também o aciona. (string) $object é a forma explícita de invocar __toString().

Conclusão

__toString() permite que um objeto defina sua própria representação em string para que possa ser exibido, concatenado e interpolado como uma string simples. Mantenha-o puro, sempre retorne uma string e considere usar type-hint Stringable quando uma função dever aceitar tanto strings quanto objetos semelhantes a strings. Para aprofundar, veja Classes e Objetos PHP, o método mágico construtor __construct() e Strings PHP.

Prática