Traits Avançados

✓ Resposta: O método abstrato no trait é o que o torna um template: validar() conhece o algoritmo, e a classe fornece só a parte que varia. Se esquecer de implementar regrasDeValidacao(), o erro é fatal já no carregamento da classe — não em produção.

<?php

declare(strict_types=1);

trait Validavel
{
    // Método abstrato dentro do trait: quem usar é OBRIGADO a implementar.
    // É assim que o trait exige o pedaço variável sem conhecê-lo.
    abstract public function regrasDeValidacao(): array;

    /** @return array<string, string[]> campo => lista de erros */
    public function validar(array $dados): array
    {
        $erros = [];

        foreach ($this->regrasDeValidacao() as $campo => $regras) {
            $valor = $dados[$campo] ?? null;

            foreach (explode('|', $regras) as $regra) {
                [$nome, $param] = array_pad(explode(':', $regra, 2), 2, null);

                $erro = $this->aplicarRegra($nome, $campo, $valor, $param);

                if ($erro !== null) {
                    $erros[$campo][] = $erro;
                    // Uma falha por campo basta: sem isso, campo vazio
                    // acusaria "obrigatório" e "mínimo 8" ao mesmo tempo.
                    break;
                }
            }
        }

        return $erros;
    }

    private function aplicarRegra(string $regra, string $campo, mixed $valor, ?string $param): ?string
    {
        return match ($regra) {
            'obrigatorio' => (is_string($valor) ? trim($valor) === '' : $valor === null)
                ? "O campo {$campo} é obrigatório." : null,

            'email' => ($valor !== null && !filter_var($valor, FILTER_VALIDATE_EMAIL))
                ? "O campo {$campo} precisa ser um e-mail válido." : null,

            'min' => (is_string($valor) && mb_strlen($valor) < (int) $param)
                ? "O campo {$campo} precisa de ao menos {$param} caracteres." : null,

            'numerico' => ($valor !== null && !is_numeric($valor))
                ? "O campo {$campo} precisa ser numérico." : null,

            'positivo' => (is_numeric($valor) && (float) $valor <= 0)
                ? "O campo {$campo} precisa ser maior que zero." : null,

            default => null,
        };
    }
}

final class FormularioCadastro
{
    use Validavel;

    public function regrasDeValidacao(): array
    {
        return [
            'nome'  => 'obrigatorio|min:3',
            'email' => 'obrigatorio|email',
            'senha' => 'obrigatorio|min:8',
        ];
    }
}

final class FormularioPagamento
{
    use Validavel;

    public function regrasDeValidacao(): array
    {
        return [
            'cartao'    => 'obrigatorio|min:13',
            'cvv'       => 'obrigatorio|numerico|min:3',
            'valor'     => 'obrigatorio|numerico|positivo',
        ];
    }
}

print_r((new FormularioCadastro())->validar([
    'nome' => 'Jo', 'email' => 'nao-eh-email', 'senha' => '123',
]));
// nome  => O campo nome precisa de ao menos 3 caracteres.
// email => O campo email precisa ser um e-mail válido.
// senha => O campo senha precisa de ao menos 8 caracteres.

print_r((new FormularioPagamento())->validar([
    'cartao' => '4111111111111111', 'cvv' => '12x', 'valor' => -5,
]));
// cvv   => O campo cvv precisa ser numérico.
// valor => O campo valor precisa ser maior que zero.

✓ Resposta: O erro mais comum aqui é achar que as renomeia. Ele adiciona um nome: depois de LogArquivo::log as logArquivo, o método continua existindo como log também — só que insteadof já deu esse nome ao outro trait.

<?php

declare(strict_types=1);

trait LogConsole
{
    public function log(string $msg): void
    {
        printf("[console] %s — %s%s",
               (new DateTimeImmutable())->format('H:i:s'), $msg, PHP_EOL);
    }
}

trait LogArquivo
{
    public function log(string $msg): void
    {
        file_put_contents(
            __DIR__ . '/app.log',
            sprintf("[arquivo] %s — %s\n", (new DateTimeImmutable())->format('c'), $msg),
            FILE_APPEND | LOCK_EX,
        );
    }
}

final class Aplicacao
{
    // Usar os dois sem o bloco de resolução é erro FATAL:
    // "Trait method Aplicacao::log has not been applied as it collides..."
    use LogConsole, LogArquivo {
        // 1) Quem fica com o nome disputado:
        LogConsole::log insteadof LogArquivo;

        // 2) O perdedor ganha um nome adicional — `as` NÃO renomeia,
        //    cria um apelido. Sem isso, LogArquivo::log ficaria inacessível.
        LogArquivo::log as logArquivo;
    }

    public function iniciar(): void
    {
        $this->log('Aplicação iniciada');        // LogConsole
        $this->logArquivo('Aplicação iniciada'); // LogArquivo
    }

    public function falhar(string $motivo): void
    {
        // Erro grave vai para os dois destinos.
        $this->log("ERRO: {$motivo}");
        $this->logArquivo("ERRO: {$motivo}");
    }
}

$app = new Aplicacao();
$app->iniciar();
$app->falhar('conexão recusada');

// Saída no console:
// [console] 14:30:12 — Aplicação iniciada
// [console] 14:30:12 — ERRO: conexão recusada
//
// app.log:
// [arquivo] 2026-08-15T14:30:12-03:00 — Aplicação iniciada
// [arquivo] 2026-08-15T14:30:12-03:00 — ERRO: conexão recusada

// ---------- Bônus: `as` também muda visibilidade -------------------------
final class Servico
{
    use LogConsole {
        // O log vira detalhe interno: ninguém de fora chama $servico->log().
        log as protected registrar;
    }

    public function executar(): void
    {
        $this->registrar('executando');
    }
}

✓ Resposta: A dupla interface + trait resolve o que nenhum dos dois faz sozinho: a interface permite tipar (function aquecer(CacheavelInterface $c)) e o trait evita reescrever o mesmo cache em cada classe. Trait sozinho não serve para type hint.

<?php

declare(strict_types=1);

interface CacheavelInterface
{
    public function chaveCache(): string;

    public function tempoExpiracao(): int;   // segundos
}

trait CacheavelTrait
{
    // O trait não implementa a interface — ele CONSOME os dois métodos que
    // a interface obriga a existir. A classe declara `implements`, o trait
    // entrega o comportamento. Separação limpa entre contrato e implementação.
    public function armazenarNoCache(mixed $valor): bool
    {
        $arquivo = $this->caminhoCache();

        $envelope = [
            'expira_em' => time() + $this->tempoExpiracao(),
            'valor'     => $valor,
        ];

        return file_put_contents(
            $arquivo,
            serialize($envelope),
            LOCK_EX,
        ) !== false;
    }

    public function buscarDoCache(): mixed
    {
        $arquivo = $this->caminhoCache();

        if (!is_file($arquivo)) {
            return null;
        }

        $envelope = unserialize((string) file_get_contents($arquivo), ['allowed_classes' => false]);

        if (!is_array($envelope) || time() > ($envelope['expira_em'] ?? 0)) {
            // Expirou: limpa e devolve null como se nunca tivesse existido.
            @unlink($arquivo);
            return null;
        }

        return $envelope['valor'];
    }

    public function invalidarCache(): void
    {
        $arquivo = $this->caminhoCache();

        if (is_file($arquivo)) {
            unlink($arquivo);
        }
    }

    private function caminhoCache(): string
    {
        // sha1 na chave: nome de arquivo seguro mesmo com "/" ou ":" na chave.
        return sys_get_temp_dir() . '/cache_' . sha1($this->chaveCache()) . '.php';
    }
}

final class RelatorioVendas implements CacheavelInterface
{
    use CacheavelTrait;

    public function __construct(
        private readonly int $ano,
        private readonly int $mes,
    ) {}

    public function chaveCache(): string
    {
        return sprintf('relatorio:vendas:%04d-%02d', $this->ano, $this->mes);
    }

    // Relatório de mês fechado não muda mais: cacheia por um dia.
    public function tempoExpiracao(): int
    {
        $ehMesAtual = $this->ano === (int) date('Y') && $this->mes === (int) date('n');

        return $ehMesAtual ? 300 : 86400;
    }

    public function gerar(): array
    {
        if (($cache = $this->buscarDoCache()) !== null) {
            return $cache;
        }

        $dados = ['total' => 128450.90, 'pedidos' => 312];   // consulta cara

        $this->armazenarNoCache($dados);

        return $dados;
    }
}

final class PerfilUsuario implements CacheavelInterface
{
    use CacheavelTrait;

    public function __construct(private readonly int $usuarioId) {}

    public function chaveCache(): string
    {
        return "usuario:{$this->usuarioId}:perfil";
    }

    public function tempoExpiracao(): int { return 600; }
}

$relatorio = new RelatorioVendas(2026, 7);
print_r($relatorio->gerar());   // 1ª vez: calcula e grava
print_r($relatorio->gerar());   // 2ª vez: vem do cache

✓ Resposta: A escolha entre as duas variantes é real: readonly dá garantia forte, mas obriga toda classe a chamar o inicializador no construtor e não aceita atribuição preguiçosa. A versão com ??= é mais tolerante e igualmente imutável na prática, já que não existe setter.

<?php

declare(strict_types=1);

trait HasUuid
{
    // Sem `readonly` aqui, porque o valor é atribuído fora do construtor da
    // classe; a imutabilidade vem de a propriedade ser private e não haver
    // setter. Quem quiser readonly de verdade, veja a variante no fim.
    private ?string $uuid = null;

    public function uuid(): string
    {
        // Geração preguiçosa: o primeiro acesso cria, os seguintes reusam.
        // Assim o trait funciona mesmo em classe cujo construtor não o chama.
        return $this->uuid ??= self::gerarUuidV4();
    }

    public static function gerarUuidV4(): string
    {
        $bytes = random_bytes(16);

        // Versão 4 nos bits 12-15 do time_hi_and_version.
        $bytes[6] = chr((ord($bytes[6]) & 0x0f) | 0x40);
        // Variante RFC 4122 nos dois bits mais altos do clock_seq_hi.
        $bytes[8] = chr((ord($bytes[8]) & 0x3f) | 0x80);

        return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4));
    }

    public function mesmaIdentidade(object $outro): bool
    {
        return method_exists($outro, 'uuid') && $this->uuid() === $outro->uuid();
    }
}

final class Pedido
{
    use HasUuid;

    public function __construct(
        public readonly string $cliente,
        public readonly float $total,
    ) {
        $this->uuid();   // fixa a identidade já na criação
    }
}

final class Produto
{
    use HasUuid;

    public function __construct(public readonly string $nome) {}
}

final class EventoDominio
{
    use HasUuid;

    public function __construct(
        public readonly string $nome,
        public readonly DateTimeImmutable $ocorridoEm = new DateTimeImmutable(),
    ) {}

    public function paraFila(): array
    {
        // O UUID é a chave de idempotência: reprocessar o mesmo evento duas
        // vezes é detectável porque o id não muda.
        return ['id' => $this->uuid(), 'nome' => $this->nome,
                'em' => $this->ocorridoEm->format('c')];
    }
}

$pedido = new Pedido('Ana', 349.90);

echo $pedido->uuid(), PHP_EOL;   // 3f2b1c8a-... (v4)
echo $pedido->uuid(), PHP_EOL;   // idêntico: não regenera

var_dump($pedido->uuid() === $pedido->uuid());          // true
var_dump($pedido->mesmaIdentidade(new Pedido('Ana', 349.90)));  // false

// ---------- Variante com readonly de verdade (PHP 8.1+) ------------------
trait HasUuidReadonly
{
    public readonly string $uuid;

    // A classe chama isto no construtor. readonly só aceita UMA escrita, e
    // ela tem de partir do escopo da classe — por isso não dá para usar a
    // inicialização preguiçosa aqui.
    private function inicializarUuid(): void
    {
        $this->uuid = HasUuid::gerarUuidV4();
    }
}

✓ Resposta: O is_subclass_of() com a interface é o que torna o comportamento automático — e é por isso que o Eloquent detecta o trait. Lembre do outro lado: índice em deletado_em e atenção a UNIQUE, porque a linha continua lá e um e-mail "apagado" ainda bloqueia o recadastro.

<?php

declare(strict_types=1);

interface SoftDeletavelInterface
{
    public function deletar(): void;

    public function restaurar(): void;

    public function estaDeletado(): bool;

    public function deletadoEm(): ?DateTimeImmutable;
}

trait SoftDeletesTrait
{
    private ?DateTimeImmutable $deletadoEm = null;

    public function deletar(): void
    {
        // Idempotente: deletar duas vezes não muda a data original.
        $this->deletadoEm ??= new DateTimeImmutable();
    }

    public function restaurar(): void
    {
        $this->deletadoEm = null;
    }

    public function estaDeletado(): bool
    {
        return $this->deletadoEm !== null;
    }

    public function deletadoEm(): ?DateTimeImmutable
    {
        return $this->deletadoEm;
    }

    /** Marca a coluna no banco, sem apagar a linha. */
    public function aplicarDelecao(PDO $pdo, string $tabela, int $id): bool
    {
        $stmt = $pdo->prepare(
            "UPDATE {$tabela} SET deletado_em = :quando WHERE id = :id AND deletado_em IS NULL"
        );

        $this->deletar();
        $stmt->execute([
            ':quando' => $this->deletadoEm->format('Y-m-d H:i:s'),
            ':id'     => $id,
        ]);

        return $stmt->rowCount() > 0;
    }
}

final class Post implements SoftDeletavelInterface
{
    use SoftDeletesTrait;

    public function __construct(
        public readonly int $id,
        public readonly string $titulo,
    ) {}
}

final class Comentario implements SoftDeletavelInterface
{
    use SoftDeletesTrait;

    public function __construct(public readonly int $id, public readonly string $texto) {}
}

// ---------- QueryBuilder que respeita a exclusão lógica -------------------
final class QueryBuilder
{
    private array $condicoes = [];
    private bool $incluirDeletados = false;

    public function __construct(
        private readonly string $tabela,
        private readonly string $classeEntidade,
    ) {}

    public function where(string $condicao): static
    {
        $this->condicoes[] = $condicao;
        return $this;
    }

    /** Equivale ao withTrashed() do Eloquent. */
    public function comDeletados(): static
    {
        $this->incluirDeletados = true;
        return $this;
    }

    /** Só a lixeira — o onlyTrashed(). */
    public function apenasDeletados(): static
    {
        $this->incluirDeletados = true;
        $this->condicoes[] = 'deletado_em IS NOT NULL';
        return $this;
    }

    public function build(): string
    {
        $condicoes = $this->condicoes;

        // O coração do exercício: se a entidade implementa a interface, o
        // filtro entra SOZINHO. Esquecer de escrever o WHERE deixa de ser
        // possível — e é justamente esse esquecimento que faz registro
        // "apagado" reaparecer numa listagem.
        if (!$this->incluirDeletados
            && is_subclass_of($this->classeEntidade, SoftDeletavelInterface::class)) {
            array_unshift($condicoes, 'deletado_em IS NULL');
        }

        $sql = "SELECT * FROM {$this->tabela}";

        if ($condicoes !== []) {
            $sql .= ' WHERE ' . implode(' AND ', $condicoes);
        }

        return $sql;
    }
}

echo (new QueryBuilder('posts', Post::class))
        ->where('autor_id = 7')
        ->build(), PHP_EOL;
// SELECT * FROM posts WHERE deletado_em IS NULL AND autor_id = 7

echo (new QueryBuilder('posts', Post::class))
        ->where('autor_id = 7')
        ->comDeletados()
        ->build(), PHP_EOL;
// SELECT * FROM posts WHERE autor_id = 7

echo (new QueryBuilder('posts', Post::class))->apenasDeletados()->build(), PHP_EOL;
// SELECT * FROM posts WHERE deletado_em IS NOT NULL

// Entidade sem a interface: nada é acrescentado.
final class LogAcesso {}
echo (new QueryBuilder('logs', LogAcesso::class))->build(), PHP_EOL;
// SELECT * FROM logs