toString e debugInfo

Parte da seção Programação Orientada a Objetos do Journey de PHP da Coddy — lição 45 de 91.

O método __toString() permite que você defina como um objeto deve ser representado como uma string. Isso é chamado automaticamente quando você usa um objeto em um contexto de string, como com echo ou concatenação de strings.

<?php
class User {
    public function __construct(
        private string $name,
        private string $email
    ) {}
    
    public function __toString(): string {
        return $this->name . " (" . $this->email . ")";
    }
}

$user = new User("Alice", "alice@example.com");
echo $user;

Saída:

Alice (alice@example.com)

O método __debugInfo() controla quais informações aparecem quando você usa var_dump() em um objeto. Isso é útil para ocultar dados sensíveis ou mostrar valores calculados durante a depuração:

<?php
class BankAccount {
    public function __construct(
        private string $accountNumber,
        private float $balance,
        private string $pin
    ) {}
    
    public function __debugInfo(): array {
        return [
            'accountNumber' => '****' . substr($this->accountNumber, -4),
            'balance' => $this->balance,
            'pin' => '[HIDDEN]'
        ];
    }
}

$account = new BankAccount("1234567890", 1500.00, "9876");
var_dump($account);

Saída:

object(BankAccount)#1 (3) {
  ["accountNumber"]=>
  string(8) "****7890"
  ["balance"]=>
  float(1500)
  ["pin"]=>
  string(8) "[HIDDEN]"
}

Observe como __debugInfo() retorna um array de pares chave-valor que substituem o dump de propriedade padrão. O PIN sensível está oculto e o número da conta está parcialmente mascarado - perfeito para depuração segura.

Desafio

Fácil

Vamos construir um sistema de gerenciamento de credenciais que demonstra os métodos mágicos __toString() e __debugInfo(). Você criará uma classe que exibe informações amigáveis ao usuário quando impressa, enquanto protege dados sensíveis durante a depuração.

Você organizará seu código em dois arquivos:

Credential.php — Crie uma classe Credential que armazena informações de login de forma segura. Use a promoção de construtor para definir propriedades privadas para $username (string), $password (string) e $lastLogin (string). Implemente dois métodos mágicos:
- __toString() — Retorna uma string amigável ao usuário: "User: [username] (Last login: [lastLogin])". Observe que a senha nunca é exposta na representação em string.
- __debugInfo() — Retorna um array para o var_dump() que mostra o nome de usuário como está, mascara a senha exibindo apenas "[PROTECTED]" e exibe a data do último login normalmente.
main.php — Inclua o arquivo Credential. Você receberá três entradas: um nome de usuário, uma senha e uma data de último login. Crie uma instância de Credential com esses valores. Primeiro, use o echo no objeto de credencial diretamente (isso aciona o __toString()). Em seguida, em uma nova linha, use var_dump() no objeto para ver a saída de depuração protegida.

O método __toString() fornece uma maneira limpa e segura de exibir a credencial sem expor a senha. O método __debugInfo() garante que, mesmo durante a depuração, informações sensíveis permaneçam ocultas — uma prática crucial ao trabalhar com dados de autenticação.

Folha de consulta

O método __toString() define como um objeto é representado como uma string quando usado com echo ou concatenação de strings:

<?php
class User {
    public function __construct(
        private string $name,
        private string $email
    ) {}
    
    public function __toString(): string {
        return $this->name . " (" . $this->email . ")";
    }
}

$user = new User("Alice", "alice@example.com");
echo $user; // Alice (alice@example.com)

O método __debugInfo() controla quais informações aparecem ao usar var_dump() em um objeto. Ele retorna um array de pares chave-valor para exibir:

<?php
class BankAccount {
    public function __construct(
        private string $accountNumber,
        private float $balance,
        private string $pin
    ) {}
    
    public function __debugInfo(): array {
        return [
            'accountNumber' => '****' . substr($this->accountNumber, -4),
            'balance' => $this->balance,
            'pin' => '[HIDDEN]'
        ];
    }
}

$account = new BankAccount("1234567890", 1500.00, "9876");
var_dump($account);
// Mostra o número da conta mascarado e o PIN oculto

Esses métodos são úteis para ocultar dados sensíveis ou personalizar a saída do objeto para diferentes contextos.

Experimente você mesmo

<?php

require_once 'Credential.php';

// Ler entradas
$username = trim(fgets(STDIN));
$password = trim(fgets(STDIN));
$lastLogin = trim(fgets(STDIN));

// TODO: Criar uma instância de Credential com os valores de entrada

// TODO: Exibir o objeto credential (aciona __toString())

// TODO: Usar var_dump() no objeto para ver a saída de depuração protegida

?>