SOLID na Prática

✓ Resposta: O teste de SRP é a pergunta "quantos motivos para mudar?". Trocar o formato da API mexe só no Serializer; endurecer uma regra, só no Validator; aceitar XML além de JSON, só no Reader. O controller fica intocado nos três casos.

<?php

declare(strict_types=1);

// ---------- ANTES: o controller fazia tudo ------------------------------
// class ProdutoController {
//     public function criar(): string {
//         $dados = json_decode(file_get_contents('php://input'), true);  // I/O
//         if (trim($dados['nome'] ?? '') === '') { ... }                 // validação
//         $stmt = $this->pdo->prepare('INSERT ...');                     // persistência
//         return json_encode(['id' => ..., 'nome' => ...]);              // serialização
//     }
// }
// Quatro motivos para mudar essa classe: formato de entrada, regra de
// validação, esquema do banco e formato de saída. SRP diz: um motivo.

// ---------------------------------------- src/Http/RequestReader.php
final class RequestReader
{
    /** Só sabe transformar corpo HTTP em array. */
    public function corpoJson(): array
    {
        $bruto = file_get_contents('php://input');

        if ($bruto === false || trim($bruto) === '') {
            return [];
        }

        try {
            $dados = json_decode($bruto, true, 512, JSON_THROW_ON_ERROR);
        } catch (JsonException $e) {
            throw new InvalidArgumentException('Corpo JSON malformado.', 0, $e);
        }

        return is_array($dados) ? $dados : [];
    }
}

// ---------------------------------------- src/Validation/ProdutoValidator.php
final class ProdutoValidator
{
    /** @return array<string, string> campo => erro; vazio = válido */
    public function validar(array $dados, bool $parcial = false): array
    {
        $erros = [];

        if (!$parcial || array_key_exists('nome', $dados)) {
            $nome = trim((string) ($dados['nome'] ?? ''));

            if ($nome === '') {
                $erros['nome'] = 'Obrigatório.';
            } elseif (mb_strlen($nome) > 160) {
                $erros['nome'] = 'Máximo de 160 caracteres.';
            }
        }

        if (!$parcial || array_key_exists('preco', $dados)) {
            $preco = $dados['preco'] ?? null;

            if (!is_numeric($preco)) {
                $erros['preco'] = 'Precisa ser numérico.';
            } elseif ((float) $preco <= 0) {
                $erros['preco'] = 'Precisa ser maior que zero.';
            }
        }

        if (isset($dados['estoque']) && (!is_int($dados['estoque']) || $dados['estoque'] < 0)) {
            $erros['estoque'] = 'Precisa ser inteiro não negativo.';
        }

        return $erros;
    }
}

// ---------------------------------------- src/Http/ProdutoSerializer.php
final class ProdutoSerializer
{
    /** Só sabe transformar entidade em array de saída. */
    public function um(Produto $produto): array
    {
        return [
            'id'    => $produto->id,
            'nome'  => $produto->nome,
            'preco' => [
                'centavos'  => $produto->precoCentavos,
                'formatado' => 'R$ ' . number_format($produto->precoCentavos / 100, 2, ',', '.'),
            ],
            'estoque' => $produto->estoque,
        ];
    }

    /** @param Produto[] $produtos */
    public function colecao(array $produtos, array $meta = []): array
    {
        return ['dados' => array_map($this->um(...), $produtos)] + ($meta ? ['meta' => $meta] : []);
    }
}

// ---------------------------------------- src/Http/ProdutoController.php
final class ProdutoController
{
    public function __construct(
        private readonly RequestReader $reader,
        private readonly ProdutoValidator $validator,
        private readonly ProdutoSerializer $serializer,
        private readonly ProdutoRepositorioInterface $repositorio,
    ) {}

    /** Orquestra: lê, valida, delega, serializa. Nenhuma regra própria. */
    public function criar(): array
    {
        $dados = $this->reader->corpoJson();

        if ($erros = $this->validator->validar($dados)) {
            return ['status' => 422, 'corpo' => ['erro' => 'validacao', 'campos' => $erros]];
        }

        $produto = $this->repositorio->salvar(
            Produto::novo(
                nome: trim($dados['nome']),
                precoCentavos: (int) round(((float) $dados['preco']) * 100),
                estoque: (int) ($dados['estoque'] ?? 0),
            ),
        );

        return ['status' => 201, 'corpo' => $this->serializer->um($produto)];
    }
}

✓ Resposta: O sinal de que o OCP foi respeitado é não existir switch/match por tipo de canal dentro do serviço. Repare que a regra dos 160 caracteres mora no SMS: colocá-la no serviço seria um vazamento de detalhe de um canal para quem coordena todos.

<?php

declare(strict_types=1);

interface CanalDeNotificacao
{
    public function enviar(string $destinatario, string $mensagem): void;

    public function nome(): string;

    /** Nem todo canal serve para todo destinatário. */
    public function suporta(string $destinatario): bool;
}

final class NotificacaoEmail implements CanalDeNotificacao
{
    public function enviar(string $destinatario, string $mensagem): void
    {
        // mail() de verdade, ou um mailer injetado.
        error_log("[email] para {$destinatario}: {$mensagem}");
    }

    public function nome(): string { return 'email'; }

    public function suporta(string $destinatario): bool
    {
        return filter_var($destinatario, FILTER_VALIDATE_EMAIL) !== false;
    }
}

final class NotificacaoSMS implements CanalDeNotificacao
{
    private const LIMITE = 160;

    public function enviar(string $destinatario, string $mensagem): void
    {
        // A regra de truncar é DESTE canal — não do serviço.
        $texto = mb_strlen($mensagem) > self::LIMITE
            ? mb_substr($mensagem, 0, self::LIMITE - 1) . '…'
            : $mensagem;

        error_log("[sms] para {$destinatario}: {$texto}");
    }

    public function nome(): string { return 'sms'; }

    public function suporta(string $destinatario): bool
    {
        return (bool) preg_match('/^\+?\d{10,15}$/', preg_replace('/\D/', '', $destinatario));
    }
}

final class NotificacaoSlack implements CanalDeNotificacao
{
    public function __construct(private readonly string $webhook) {}

    public function enviar(string $destinatario, string $mensagem): void
    {
        $payload = json_encode(['channel' => $destinatario, 'text' => $mensagem]);

        error_log("[slack] POST {$this->webhook} — {$payload}");
    }

    public function nome(): string { return 'slack'; }

    public function suporta(string $destinatario): bool
    {
        return str_starts_with($destinatario, '#') || str_starts_with($destinatario, '@');
    }
}

final class NotificacaoService
{
    /** @param CanalDeNotificacao[] $canais */
    public function __construct(private readonly array $canais) {}

    /** @return array<string, bool> canal => enviou */
    public function notificar(string $destinatario, string $mensagem): array
    {
        $resultado = [];

        foreach ($this->canais as $canal) {
            if (!$canal->suporta($destinatario)) {
                continue;
            }

            try {
                $canal->enviar($destinatario, $mensagem);
                $resultado[$canal->nome()] = true;
            } catch (Throwable $e) {
                // Um canal fora do ar não pode derrubar os outros.
                error_log("Falha no canal {$canal->nome()}: {$e->getMessage()}");
                $resultado[$canal->nome()] = false;
            }
        }

        return $resultado;
    }
}

// Canal novo = classe nova. O NotificacaoService NUNCA muda — é isso o
// "fechado para modificação, aberto para extensão".
$servico = new NotificacaoService([
    new NotificacaoEmail(),
    new NotificacaoSMS(),
    new NotificacaoSlack('https://hooks.slack.com/services/XXX'),
]);

print_r($servico->notificar('ana@exemplo.com', 'Seu pedido foi enviado.'));
// [email] => 1

print_r($servico->notificar('#alertas', 'Fila acima de 1000 jobs.'));
// [slack] => 1

// Amanhã, WhatsApp: basta implementar a interface e acrescentar ao array.
// Nenhum `if ($tipo === 'whatsapp')` em lugar nenhum.

✓ Resposta: LSP não se quebra com tipo errado — se quebra com promessa errada: mesma assinatura, comportamento incompatível. O cheiro clássico é o método sobrescrito que ignora um parâmetro ou lança BadMethodCallException. A correção quase sempre é trocar herança por interfaces menores.

<?php

declare(strict_types=1);

// ---------- A VIOLAÇÃO ----------------------------------------------------
class Colecao
{
    protected array $itens = [];

    /** Contrato: o item fica NA posição pedida. */
    public function adicionar(mixed $item, ?int $posicao = null): void
    {
        if ($posicao === null) {
            $this->itens[] = $item;
            return;
        }

        array_splice($this->itens, $posicao, 0, [$item]);
    }

    public function em(int $posicao): mixed { return $this->itens[$posicao] ?? null; }

    public function todos(): array { return $this->itens; }
}

class ColecaoOrdenada extends Colecao
{
    public function adicionar(mixed $item, ?int $posicao = null): void
    {
        // ⚠️ IGNORA a posição e reordena. Assinatura idêntica, comportamento
        // diferente: quem recebe uma Colecao não pode mais confiar no contrato.
        $this->itens[] = $item;
        sort($this->itens);
    }
}

// O código cliente quebra sem nenhum erro de tipo:
function inserirNoTopo(Colecao $colecao, mixed $item): mixed
{
    $colecao->adicionar($item, 0);

    return $colecao->em(0);   // o contrato promete que é $item
}

var_dump(inserirNoTopo(new Colecao(), 'zebra'));           // "zebra" ✅
var_dump(inserirNoTopo(new ColecaoOrdenada(), 'zebra'));   // outro item ❌

// ---------- A CORREÇÃO: separar as capacidades ---------------------------
// A pergunta certa não é "ColecaoOrdenada é uma Colecao?", e sim "ela cumpre
// TUDO o que Colecao promete?". Não cumpre — então não deve herdar dela.

interface ColecaoInterface
{
    public function adicionar(mixed $item): void;

    public function em(int $posicao): mixed;

    /** @return mixed[] */
    public function todos(): array;

    public function contar(): int;
}

/** Só quem realmente respeita posição declara isto. */
interface PosicionavelInterface
{
    public function inserirEm(int $posicao, mixed $item): void;

    public function mover(int $de, int $para): void;
}

final class ListaSimples implements ColecaoInterface, PosicionavelInterface
{
    private array $itens = [];

    public function adicionar(mixed $item): void { $this->itens[] = $item; }

    public function inserirEm(int $posicao, mixed $item): void
    {
        array_splice($this->itens, max(0, $posicao), 0, [$item]);
    }

    public function mover(int $de, int $para): void
    {
        if (!array_key_exists($de, $this->itens)) {
            throw new OutOfBoundsException("Posição {$de} não existe.");
        }

        $item = array_splice($this->itens, $de, 1)[0];
        array_splice($this->itens, $para, 0, [$item]);
    }

    public function em(int $posicao): mixed { return $this->itens[$posicao] ?? null; }

    public function todos(): array { return $this->itens; }

    public function contar(): int { return count($this->itens); }
}

/** Não implementa Posicionavel: a ordem é dela, e ela não mente sobre isso. */
final class ColecaoOrdenadaCorreta implements ColecaoInterface
{
    private array $itens = [];

    public function __construct(private readonly ?Closure $comparador = null) {}

    public function adicionar(mixed $item): void
    {
        $this->itens[] = $item;

        $this->comparador !== null
            ? usort($this->itens, $this->comparador)
            : sort($this->itens);
    }

    public function em(int $posicao): mixed { return $this->itens[$posicao] ?? null; }

    public function todos(): array { return $this->itens; }

    public function contar(): int { return count($this->itens); }
}

// Agora o tipo do parâmetro diz a verdade: esta função exige posicionamento,
// e ColecaoOrdenadaCorreta simplesmente não é aceita — erro em tempo de
// análise, não surpresa em produção.
function inserirNoTopoSeguro(PosicionavelInterface&ColecaoInterface $c, mixed $item): mixed
{
    $c->inserirEm(0, $item);

    return $c->em(0);
}

var_dump(inserirNoTopoSeguro(new ListaSimples(), 'zebra'));   // "zebra" ✅
// inserirNoTopoSeguro(new ColecaoOrdenadaCorreta(), 'x');    // TypeError ✅

✓ Resposta: O ganho concreto do DIP aparece no teste: com echo cravado, verificar a saída exigiria ob_start() e análise de string. Com a interface, a verificação é uma asserção sobre um array. O LoggerNulo como padrão evita o if de "tem logger?".

<?php

declare(strict_types=1);

interface LoggerInterface
{
    public function log(string $mensagem): void;
}

final class LoggerConsole implements LoggerInterface
{
    public function log(string $mensagem): void
    {
        echo $mensagem, PHP_EOL;
    }
}

/** Guarda em memória: é o que torna o runner testável sem capturar stdout. */
final class LoggerArray implements LoggerInterface
{
    /** @var string[] */
    private array $linhas = [];

    public function log(string $mensagem): void
    {
        $this->linhas[] = $mensagem;
    }

    /** @return string[] */
    public function linhas(): array { return $this->linhas; }

    public function contem(string $trecho): bool
    {
        foreach ($this->linhas as $linha) {
            if (str_contains($linha, $trecho)) {
                return true;
            }
        }

        return false;
    }
}

final class LoggerNulo implements LoggerInterface
{
    // Null Object: evita `if ($this->logger !== null)` espalhado.
    public function log(string $mensagem): void {}
}

final class MigrationRunner
{
    public function __construct(
        private readonly PDO $pdo,
        private readonly array $migrations,
        // Depende da ABSTRAÇÃO. Antes, o `echo` amarrava o runner ao terminal:
        // não dava para usar em fila, em teste ou gravando em arquivo.
        private readonly LoggerInterface $logger = new LoggerNulo(),
    ) {}

    public function migrate(): int
    {
        $aplicadas = 0;

        foreach ($this->pendentes() as $nome) {
            $inicio = hrtime(true);

            $this->migrations[$nome]->up($this->pdo);
            $this->registrar($nome);

            $this->logger->log(sprintf('✅ %s (%.2f ms)',
                $nome, (hrtime(true) - $inicio) / 1_000_000));

            $aplicadas++;
        }

        $this->logger->log($aplicadas === 0
            ? 'Nada a fazer: tudo já aplicado.'
            : "{$aplicadas} migration(s) aplicada(s).");

        return $aplicadas;
    }

    private function pendentes(): array
    {
        $executadas = $this->pdo->query('SELECT migration FROM migrations')
                                ->fetchAll(PDO::FETCH_COLUMN);

        return array_diff(array_keys($this->migrations), $executadas);
    }

    private function registrar(string $nome): void
    {
        $stmt = $this->pdo->prepare('INSERT INTO migrations (migration, lote) VALUES (:m, 1)');
        $stmt->execute([':m' => $nome]);
    }
}

// ---------- Produção ------------------------------------------------------
(new MigrationRunner($pdo, $migrations, new LoggerConsole()))->migrate();

// ---------- Teste: sem capturar saída, sem output buffering --------------
$logger = new LoggerArray();
$runner = new MigrationRunner($pdoSqlite, $migrations, $logger);

$runner->migrate();

assert($logger->contem('Migration001Usuarios'));
assert($logger->contem('3 migration(s) aplicada(s).'));

$runner->migrate();
assert($logger->contem('Nada a fazer'));

✓ Resposta: Testes estruturais por Reflection são incomuns e devem ser usados com parcimônia — mas aqui fazem sentido: eles transformam um princípio de projeto em regra executável. O teste de OCP é o mais didático: ele prova que a regra nova entrou sem alterar os resultados antigos.

<?php

declare(strict_types=1);

namespace Tests\Unit\Solid;

use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
use ReflectionClass;

final class PrincipiosSolidTest extends TestCase
{
    // ---------- DIP -------------------------------------------------------
    #[Test]
    public function processadorDePedidoAceitaDublesEmVezDeInstanciarDependencias(): void
    {
        // Se a classe desse `new` internamente, seria impossível trocar por
        // mock — e este teste não compilaria.
        $repositorio = $this->createMock(PedidoRepositorioInterface::class);
        $pagamento   = $this->createMock(GatewayPagamentoInterface::class);

        $repositorio->expects(self::once())->method('salvar');
        $pagamento->expects(self::once())->method('cobrar')->willReturn('AUT-1');

        (new ProcessadorDePedido($repositorio, $pagamento))->processar(pedidoId: 1, valor: 100.0);
    }

    #[Test]
    public function processadorNaoInstanciaColaboradoresInternamente(): void
    {
        // Verificação estrutural: `new` de colaborador dentro do arquivo é o
        // acoplamento que o DIP proíbe. Falha se alguém "simplificar" o código.
        $arquivo = (new ReflectionClass(ProcessadorDePedido::class))->getFileName();
        $fonte = file_get_contents($arquivo);

        foreach (['new PedidoRepositorioPDO', 'new GatewayStripe', 'new PDO('] as $proibido) {
            self::assertStringNotContainsString(
                $proibido, $fonte,
                "ProcessadorDePedido não pode instanciar {$proibido} — injete."
            );
        }
    }

    #[Test]
    public function todasAsDependenciasDoConstrutorSaoAbstracoes(): void
    {
        $construtor = (new ReflectionClass(ProcessadorDePedido::class))->getConstructor();

        foreach ($construtor->getParameters() as $parametro) {
            $tipo = $parametro->getType();

            if ($tipo === null || $tipo->isBuiltin()) {
                continue;   // escalares são configuração, não dependência
            }

            $reflexaoTipo = new ReflectionClass($tipo->getName());

            self::assertTrue(
                $reflexaoTipo->isInterface() || $reflexaoTipo->isAbstract(),
                "{$parametro->getName()} depende da classe concreta "
                . "{$tipo->getName()} — deveria depender de uma abstração."
            );
        }
    }

    // ---------- OCP -------------------------------------------------------
    #[Test]
    public function regraDeDescontoNovaNaoQuebraAsExistentes(): void
    {
        $calculadora = new CalculadoraDeDesconto([
            new DescontoPrimeiraCompra(),
            new DescontoAcimaDe(500.00, 0.10),
        ]);

        self::assertSame(90.00, $calculadora->aplicar(100.00, ['primeira_compra' => true]));
        self::assertSame(540.00, $calculadora->aplicar(600.00, []));

        // Regra NOVA: só se acrescenta ao array. A calculadora não muda.
        $comCupom = new CalculadoraDeDesconto([
            new DescontoPrimeiraCompra(),
            new DescontoAcimaDe(500.00, 0.10),
            new DescontoCupom('BLACK20', 0.20),
        ]);

        // Os casos antigos continuam idênticos — é isso que o teste prova.
        self::assertSame(90.00, $comCupom->aplicar(100.00, ['primeira_compra' => true]));
        self::assertSame(540.00, $comCupom->aplicar(600.00, []));

        // E o novo funciona.
        self::assertSame(80.00, $comCupom->aplicar(100.00, ['cupom' => 'BLACK20']));
    }

    #[Test]
    public function calculadoraNaoTemCondicionalPorTipoDeRegra(): void
    {
        $fonte = file_get_contents(
            (new ReflectionClass(CalculadoraDeDesconto::class))->getFileName()
        );

        // `instanceof` numa regra concreta é o cheiro de OCP violado.
        self::assertDoesNotMatchRegularExpression(
            '/instanceof\s+Desconto[A-Z]/', $fonte,
            'A calculadora não deve conhecer regras concretas.'
        );
    }

    // ---------- LSP -------------------------------------------------------
    #[Test]
    public function todaImplementacaoRespeitaOContratoDaInterface(): void
    {
        // O MESMO teste roda contra todas as implementações: é a definição
        // prática de substituibilidade.
        $implementacoes = [
            new ColecaoOrdenadaCorreta(),
            new ListaSimples(),
        ];

        foreach ($implementacoes as $colecao) {
            $colecao->adicionar('b');
            $colecao->adicionar('a');

            self::assertSame(2, $colecao->contar(), $colecao::class . ' quebrou contar()');
            self::assertContains('a', $colecao->todos(), $colecao::class . ' perdeu um item');
        }
    }

    // ---------- ISP -------------------------------------------------------
    #[Test]
    public function nenhumMetodoImplementadoLancaBadMethodCall(): void
    {
        foreach ([AuditoriaRepositorio::class, ProdutoRepositorio::class] as $classe) {
            $fonte = file_get_contents((new ReflectionClass($classe))->getFileName());

            self::assertStringNotContainsString(
                'BadMethodCallException', $fonte,
                "{$classe} implementa método que não sabe cumprir — fatie a interface."
            );
        }
    }
}