Design Patterns: Singleton, Factory e Builder

✓ Resposta: A última linha é o que o === do enunciado prova: $b vê o que $a escreveu porque são o mesmo objeto. Vale saber o outro lado: esse estado global compartilhado é justamente o que torna Singleton difícil de testar — em código novo, injeção de dependência costuma ser a escolha melhor.

<?php

declare(strict_types=1);

final class Config
{
    private static ?self $instancia = null;

    private array $dados = [];

    // Os três bloqueios que fazem o Singleton valer: sem `new`, sem `clone`
    // e sem `unserialize` criando uma segunda instância pelas costas.
    private function __construct()
    {
        $caminho = __DIR__ . '/config.php';

        if (!is_file($caminho)) {
            throw new RuntimeException("config.php não encontrado em {$caminho}");
        }

        $this->dados = require $caminho;   // o arquivo retorna um array
    }

    private function __clone() {}

    public function __wakeup(): void
    {
        throw new LogicException('Config não pode ser desserializado.');
    }

    public static function getInstance(): self
    {
        // O carregamento do arquivo acontece uma vez só, na primeira chamada.
        return self::$instancia ??= new self();
    }

    /** Aceita chave com ponto: get('db.host') */
    public function get(string $chave, mixed $padrao = null): mixed
    {
        $atual = $this->dados;

        foreach (explode('.', $chave) as $parte) {
            if (!is_array($atual) || !array_key_exists($parte, $atual)) {
                return $padrao;
            }
            $atual = $atual[$parte];
        }

        return $atual;
    }

    public function set(string $chave, mixed $valor): void
    {
        $partes = explode('.', $chave);
        $atual = &$this->dados;

        foreach ($partes as $parte) {
            if (!isset($atual[$parte]) || !is_array($atual[$parte])) {
                $atual[$parte] = [];
            }
            $atual = &$atual[$parte];
        }

        $atual = $valor;
    }
}

// config.php seria:
// <?php return ['app' => ['nome' => 'Loja'], 'db' => ['host' => '127.0.0.1']];

$a = Config::getInstance();
$b = Config::getInstance();

var_dump($a === $b);                  // bool(true) — mesma instância
echo $a->get('db.host'), PHP_EOL;     // 127.0.0.1
echo $a->get('db.porta', 3306), PHP_EOL;  // 3306 (padrão)

$a->set('db.porta', 5432);
echo $b->get('db.porta'), PHP_EOL;    // 5432 — b enxerga o que a escreveu

✓ Resposta: Quem chama a factory nunca escreve new JsonParser: recebe ParserInterface e pronto. Formato novo é uma linha no mapa — e o throw como expressão no ?? evita o if de sempre.

<?php

declare(strict_types=1);

interface ParserInterface
{
    /** @return array<int|string, mixed> */
    public function parse(string $conteudo): array;
}

final class ParserNaoSuportadoException extends InvalidArgumentException
{
    public function __construct(public readonly string $extensao)
    {
        parent::__construct("Não há parser para a extensão '{$extensao}'.");
    }
}

final class JsonParser implements ParserInterface
{
    public function parse(string $conteudo): array
    {
        // JSON_THROW_ON_ERROR troca o retorno null silencioso por exceção.
        return json_decode($conteudo, true, 512, JSON_THROW_ON_ERROR);
    }
}

final class CsvParser implements ParserInterface
{
    public function __construct(private readonly string $separador = ',') {}

    public function parse(string $conteudo): array
    {
        $linhas = preg_split('/\r\n|\r|\n/', trim($conteudo));
        $cabecalho = str_getcsv(array_shift($linhas), $this->separador);

        return array_map(
            fn(string $linha): array => array_combine(
                $cabecalho,
                str_getcsv($linha, $this->separador),
            ),
            array_filter($linhas, static fn(string $l): bool => trim($l) !== ''),
        );
    }
}

final class XmlParser implements ParserInterface
{
    public function parse(string $conteudo): array
    {
        $anterior = libxml_use_internal_errors(true);

        // LIBXML_NONET fecha a porta de XXE — XML de terceiro não deve
        // conseguir buscar entidade externa pela rede.
        $xml = simplexml_load_string($conteudo, null, LIBXML_NONET | LIBXML_NOCDATA);

        libxml_use_internal_errors($anterior);

        if ($xml === false) {
            throw new RuntimeException('XML inválido.');
        }

        return json_decode(json_encode($xml), true);
    }
}

final class ParserFactory
{
    private const MAPA = [
        'json' => JsonParser::class,
        'csv'  => CsvParser::class,
        'xml'  => XmlParser::class,
    ];

    public static function criar(string $extensao): ParserInterface
    {
        // Normaliza ".JSON", "json" e ".json" para a mesma chave.
        $chave = strtolower(ltrim($extensao, '.'));

        $classe = self::MAPA[$chave] ?? throw new ParserNaoSuportadoException($chave);

        return new $classe();
    }

    public static function paraArquivo(string $caminho): ParserInterface
    {
        return self::criar(pathinfo($caminho, PATHINFO_EXTENSION));
    }
}

// Uso:
$parser = ParserFactory::criar('.json');
print_r($parser->parse('{"nome":"Onix","preco":89900}'));

$csv = ParserFactory::criar('csv');
print_r($csv->parse("nome,preco\nOnix,89900\nHB20,87500"));

try {
    ParserFactory::criar('.docx');
} catch (ParserNaoSuportadoException $e) {
    echo $e->getMessage(), PHP_EOL;   // Não há parser para a extensão 'docx'.
}

✓ Resposta: Repare que where() aqui recebe a condição pronta — é o que o enunciado pede, e serve para aprender a montagem. Em código de produção, valor vindo do usuário nunca entra por concatenação: vira placeholder, como no QueryBuilder do artigo sobre PDO.

<?php

declare(strict_types=1);

final class QueryBuilder
{
    private string $tabela = '';
    private array $colunas = ['*'];
    private array $condicoes = [];
    private array $ordenacao = [];
    private ?int $limite = null;

    public function from(string $tabela): static
    {
        $this->tabela = $tabela;
        return $this;
    }

    public function select(string ...$colunas): static
    {
        if ($colunas !== []) {
            $this->colunas = $colunas;
        }
        return $this;
    }

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

    public function orderBy(string $coluna, string $direcao = 'ASC'): static
    {
        $direcao = strtoupper($direcao);

        if (!in_array($direcao, ['ASC', 'DESC'], true)) {
            throw new InvalidArgumentException("Direção inválida: {$direcao}");
        }

        $this->ordenacao[] = "{$coluna} {$direcao}";
        return $this;
    }

    public function limit(int $n): static
    {
        if ($n < 1) {
            throw new InvalidArgumentException('LIMIT tem de ser >= 1.');
        }

        $this->limite = $n;
        return $this;
    }

    public function build(): string
    {
        if ($this->tabela === '') {
            throw new LogicException('Defina a tabela com from() antes de build().');
        }

        // A ordem das cláusulas é fixa em SQL — o builder garante isso mesmo
        // que os métodos tenham sido chamados fora de ordem.
        $sql = 'SELECT ' . implode(', ', $this->colunas)
             . ' FROM ' . $this->tabela;

        if ($this->condicoes !== []) {
            $sql .= ' WHERE ' . implode(' AND ', $this->condicoes);
        }
        if ($this->ordenacao !== []) {
            $sql .= ' ORDER BY ' . implode(', ', $this->ordenacao);
        }
        if ($this->limite !== null) {
            $sql .= ' LIMIT ' . $this->limite;
        }

        return $sql;
    }
}

// O `return $this` de cada método é o que permite a corrente:
echo (new QueryBuilder())
    ->select('id', 'nome', 'preco')
    ->from('produtos')
    ->where('ativo = 1')
    ->where('preco > 5000')
    ->orderBy('preco', 'DESC')
    ->limit(10)
    ->build();

// SELECT id, nome, preco FROM produtos
// WHERE ativo = 1 AND preco > 5000 ORDER BY preco DESC LIMIT 10

✓ Resposta: A divisão de trabalho do padrão: o Builder sabe como montar cada pedaço, o Director sabe quais pedaços formam uma receita conhecida. O erro de página zero morre no Director, não vira SQL com OFFSET negativo.

<?php

declare(strict_types=1);

/**
 * O Director guarda as receitas de montagem que se repetem.
 * Quem chama não precisa lembrar que paginação é OFFSET = (página-1) * porPágina.
 */
final class QueryDirector
{
    public function queryPaginada(string $tabela, int $pagina, int $porPagina): string
    {
        if ($pagina < 1) {
            throw new InvalidArgumentException('A página começa em 1.');
        }

        $offset = ($pagina - 1) * $porPagina;

        $sql = (new QueryBuilder())
            ->from($tabela)
            ->orderBy('id')
            ->limit($porPagina)
            ->build();

        // OFFSET não está no builder do exercício 3 — sai daqui.
        return $offset > 0 ? "{$sql} OFFSET {$offset}" : $sql;
    }

    public function queryRecentes(string $tabela, string $campoData, int $limite): string
    {
        return (new QueryBuilder())
            ->from($tabela)
            ->orderBy($campoData, 'DESC')
            ->limit($limite)
            ->build();
    }
}

$director = new QueryDirector();

echo $director->queryPaginada('produtos', pagina: 3, porPagina: 20), PHP_EOL;
// SELECT * FROM produtos ORDER BY id ASC LIMIT 20 OFFSET 40

echo $director->queryRecentes('pedidos', 'criado_em', 5), PHP_EOL;
// SELECT * FROM pedidos ORDER BY criado_em DESC LIMIT 5

✓ Resposta: Cada padrão responde por uma pergunta diferente e não invade a do vizinho: a Factory decide qual classe nasce, o Builder decide com que configuração, e o Singleton guarda o que é global de verdade. Quando um padrão começa a responder a pergunta do outro, é sinal de que o desenho azedou.

<?php

declare(strict_types=1);

// ---------- SINGLETON: limites e formatos, um só para a aplicação ----------
final class ConfiguracaoRelatorio
{
    private static ?self $instancia = null;

    private array $formatos = ['pdf', 'csv', 'html'];
    private int $limiteLinhas = 5000;

    private function __construct() {}
    private function __clone() {}

    public static function getInstance(): self
    {
        return self::$instancia ??= new self();
    }

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

    public function limiteLinhas(): int { return $this->limiteLinhas; }

    public function definirLimite(int $linhas): void
    {
        $this->limiteLinhas = max(1, $linhas);
    }
}

// ---------- STRATEGY/FACTORY: um relatório por formato --------------------
interface RelatorioInterface
{
    public function render(array $linhas, array $colunas): string;

    public function extensao(): string;
}

final class RelatorioCsv implements RelatorioInterface
{
    public function render(array $linhas, array $colunas): string
    {
        $saida = fopen('php://temp', 'r+');
        fputcsv($saida, $colunas);

        foreach ($linhas as $linha) {
            // Só as colunas visíveis, na ordem pedida.
            fputcsv($saida, array_map(fn($c) => $linha[$c] ?? '', $colunas));
        }

        rewind($saida);
        $conteudo = stream_get_contents($saida);
        fclose($saida);

        return $conteudo;
    }

    public function extensao(): string { return 'csv'; }
}

final class RelatorioHtml implements RelatorioInterface
{
    public function render(array $linhas, array $colunas): string
    {
        $html = "<table>\n<thead><tr>";

        foreach ($colunas as $coluna) {
            // htmlspecialchars em TODO dado que vai para a página.
            $html .= '<th>' . htmlspecialchars((string) $coluna, ENT_QUOTES) . '</th>';
        }

        $html .= "</tr></thead>\n<tbody>\n";

        foreach ($linhas as $linha) {
            $html .= '<tr>';
            foreach ($colunas as $coluna) {
                $html .= '<td>' . htmlspecialchars((string) ($linha[$coluna] ?? ''), ENT_QUOTES) . '</td>';
            }
            $html .= "</tr>\n";
        }

        return $html . "</tbody>\n</table>";
    }

    public function extensao(): string { return 'html'; }
}

final class RelatorioPdf implements RelatorioInterface
{
    // Sem dependência externa aqui: gera o corpo que uma lib (Dompdf, mPDF)
    // receberia. O padrão é o mesmo, muda só o motor de saída.
    public function render(array $linhas, array $colunas): string
    {
        $corpo = (new RelatorioHtml())->render($linhas, $colunas);

        return "%PDF-1.4 (simulado)\n" . strip_tags($corpo, '<table><tr><td><th>');
    }

    public function extensao(): string { return 'pdf'; }
}

final class RelatorioFactory
{
    public static function criar(string $formato): RelatorioInterface
    {
        $formato = strtolower($formato);

        if (!in_array($formato, ConfiguracaoRelatorio::getInstance()->formatos(), true)) {
            throw new InvalidArgumentException("Formato não habilitado: {$formato}");
        }

        return match ($formato) {
            'csv'  => new RelatorioCsv(),
            'html' => new RelatorioHtml(),
            'pdf'  => new RelatorioPdf(),
        };
    }
}

// ---------- BUILDER: filtros, colunas e ordenação -------------------------
final class RelatorioBuilder
{
    private ?DateTimeImmutable $de = null;
    private ?DateTimeImmutable $ate = null;
    private array $colunas = [];
    private ?string $ordenarPor = null;
    private string $direcao = 'ASC';

    public function periodo(DateTimeImmutable $de, DateTimeImmutable $ate): static
    {
        if ($de > $ate) {
            throw new InvalidArgumentException('Início posterior ao fim do período.');
        }

        $this->de = $de;
        $this->ate = $ate;
        return $this;
    }

    public function colunas(string ...$colunas): static
    {
        $this->colunas = $colunas;
        return $this;
    }

    public function ordenarPor(string $coluna, string $direcao = 'ASC'): static
    {
        $this->ordenarPor = $coluna;
        $this->direcao = strtoupper($direcao) === 'DESC' ? 'DESC' : 'ASC';
        return $this;
    }

    public function gerar(array $dados, RelatorioInterface $relatorio): string
    {
        $linhas = $dados;

        if ($this->de !== null) {
            $linhas = array_filter($linhas, function (array $l): bool {
                $data = new DateTimeImmutable($l['data']);
                return $data >= $this->de && $data <= $this->ate;
            });
        }

        if ($this->ordenarPor !== null) {
            $col = $this->ordenarPor;
            $dir = $this->direcao === 'DESC' ? -1 : 1;
            usort($linhas, fn(array $a, array $b): int => ($a[$col] <=> $b[$col]) * $dir);
        }

        // O Singleton é a última palavra sobre o tamanho do relatório.
        $linhas = array_slice($linhas, 0, ConfiguracaoRelatorio::getInstance()->limiteLinhas());

        $colunas = $this->colunas ?: array_keys($linhas[0] ?? []);

        return $relatorio->render($linhas, $colunas);
    }
}

// ---------- Juntando tudo -------------------------------------------------
$dados = [
    ['data' => '2026-03-01', 'produto' => 'Onix', 'total' => 89900],
    ['data' => '2026-03-14', 'produto' => 'HB20', 'total' => 87500],
    ['data' => '2026-04-02', 'produto' => 'Kwid', 'total' => 71200],
];

echo (new RelatorioBuilder())
    ->periodo(new DateTimeImmutable('2026-03-01'), new DateTimeImmutable('2026-03-31'))
    ->colunas('data', 'produto', 'total')
    ->ordenarPor('total', 'DESC')
    ->gerar($dados, RelatorioFactory::criar('csv'));

// data,produto,total
// 2026-03-01,Onix,89900
// 2026-03-14,HB20,87500