APIs REST com PHP

✓ Resposta: A construção de trás para frente (array_reverse) é o que faz o primeiro middleware registrado ser o mais externo. E a regra de ouro da cebola: não chamar $proximo é o que aborta a requisição — é assim que o middleware de autenticação barra sem lançar exceção.

<?php

declare(strict_types=1);

final class Rota
{
    /** @var callable[] */
    private array $middlewares = [];

    public function __construct(
        public readonly string $metodo,
        public readonly string $path,
        public readonly mixed $handler,
    ) {}

    public function middleware(callable ...$mws): static
    {
        foreach ($mws as $mw) {
            $this->middlewares[] = $mw;
        }
        return $this;
    }

    /**
     * Monta a cebola: o último middleware fica mais perto do handler.
     * Construindo de trás para frente, cada camada recebe como $proximo a
     * cadeia que já foi montada — é o mesmo mecanismo do pipeline do Laravel.
     */
    public function executar(array $params): mixed
    {
        $proximo = fn (array $p): mixed => ($this->handler)($p);

        foreach (array_reverse($this->middlewares) as $mw) {
            $anterior = $proximo;
            $proximo = fn (array $p): mixed => $mw($p, $anterior);
        }

        return $proximo($params);
    }
}

final class Router
{
    /** @var Rota[] */
    private array $rotas = [];

    /** @var callable[] aplicados a todas as rotas */
    private array $globais = [];

    public function middlewareGlobal(callable ...$mws): void
    {
        foreach ($mws as $mw) {
            $this->globais[] = $mw;
        }
    }

    public function get(string $path, callable $handler): Rota
    {
        return $this->adicionar('GET', $path, $handler);
    }

    public function post(string $path, callable $handler): Rota
    {
        return $this->adicionar('POST', $path, $handler);
    }

    public function put(string $path, callable $handler): Rota
    {
        return $this->adicionar('PUT', $path, $handler);
    }

    public function delete(string $path, callable $handler): Rota
    {
        return $this->adicionar('DELETE', $path, $handler);
    }

    private function adicionar(string $metodo, string $path, callable $handler): Rota
    {
        $rota = new Rota($metodo, $path, $handler);
        $this->rotas[] = $rota;

        return $rota;   // devolve para permitir ->middleware(...) encadeado
    }

    public function despachar(string $metodo, string $uri): mixed
    {
        $caminho = rtrim(parse_url($uri, PHP_URL_PATH) ?? '/', '/') ?: '/';

        foreach ($this->rotas as $rota) {
            if ($rota->metodo !== strtoupper($metodo)) {
                continue;
            }

            $regex = '#^' . preg_replace(
                '/\\\\\{(\w+)\\\\\}/', '(?<$1>[^/]+)', preg_quote($rota->path, '#')
            ) . '$#';

            if (preg_match($regex, $caminho, $m)) {
                $params = array_filter($m, 'is_string', ARRAY_FILTER_USE_KEY);

                return $rota->middleware(...$this->globais)->executar($params);
            }
        }

        http_response_code(404);
        return ['erro' => 'nao_encontrado'];
    }
}

// ---------- Middlewares ---------------------------------------------------
$autenticar = static function (array $params, callable $proximo): mixed {
    $header = $_SERVER['HTTP_AUTHORIZATION'] ?? '';

    if (!str_starts_with($header, 'Bearer ')) {
        http_response_code(401);
        // Não chamar $proximo é o que interrompe a cadeia.
        return ['erro' => 'nao_autenticado'];
    }

    $params['usuario_id'] = 7;   // viria da validação do token

    return $proximo($params);
};

$logar = static function (array $params, callable $proximo): mixed {
    $inicio = hrtime(true);

    $resposta = $proximo($params);   // antes e depois: a cebola permite os dois

    error_log(sprintf('%s %s — %.2f ms',
        $_SERVER['REQUEST_METHOD'] ?? 'CLI', $_SERVER['REQUEST_URI'] ?? '/',
        (hrtime(true) - $inicio) / 1_000_000));

    return $resposta;
};

$json = static function (array $params, callable $proximo): mixed {
    header('Content-Type: application/json; charset=utf-8');
    return $proximo($params);
};

// ---------- Uso -----------------------------------------------------------
$router = new Router();
$router->middlewareGlobal($json, $logar);

$router->get('/api/perfil', fn (array $p): array => ['usuario' => $p['usuario_id']])
       ->middleware($autenticar);

echo json_encode($router->despachar('GET', '/api/perfil'));

✓ Resposta: Os status contam história: 201 com Location ao criar, 204 sem corpo ao excluir, 422 para validação e 409 para conflito. E note a corrida no e-mail único — a validação antecipada melhora a mensagem, mas quem garante é o UNIQUE.

<?php

declare(strict_types=1);

final class Resposta
{
    public static function json(mixed $dados, int $status = 200): array
    {
        http_response_code($status);
        return ['status' => $status, 'corpo' => $dados];
    }

    public static function erro(string $codigo, string $msg, int $status, array $extra = []): array
    {
        return self::json(['erro' => $codigo, 'mensagem' => $msg] + $extra, $status);
    }
}

final class UsuarioController
{
    public function __construct(private readonly PDO $pdo) {}

    /** GET /api/usuarios */
    public function index(array $params): array
    {
        $pagina = max(1, (int) ($_GET['pagina'] ?? 1));
        $porPagina = min(100, max(1, (int) ($_GET['por_pagina'] ?? 20)));

        $total = (int) $this->pdo->query('SELECT COUNT(*) FROM usuarios')->fetchColumn();

        $stmt = $this->pdo->prepare(
            'SELECT id, nome, email, criado_em FROM usuarios
             ORDER BY id LIMIT :limite OFFSET :offset'
        );
        $stmt->bindValue(':limite', $porPagina, PDO::PARAM_INT);
        $stmt->bindValue(':offset', ($pagina - 1) * $porPagina, PDO::PARAM_INT);
        $stmt->execute();

        return Resposta::json([
            'dados' => $stmt->fetchAll(PDO::FETCH_ASSOC),
            'meta'  => ['pagina' => $pagina, 'total' => $total,
                        'paginas' => (int) ceil($total / $porPagina)],
        ]);
    }

    /** GET /api/usuarios/{id} */
    public function mostrar(array $params): array
    {
        $usuario = $this->buscar((int) $params['id']);

        if ($usuario === null) {
            return Resposta::erro('nao_encontrado', 'Usuário não encontrado.', 404);
        }

        return Resposta::json($usuario);
    }

    /** POST /api/usuarios */
    public function criar(array $params): array
    {
        $dados = $this->corpoJson();

        $erros = $this->validar($dados);

        if ($erros !== []) {
            // 422: sintaxe correta, conteúdo inválido. Diferente de 400.
            return Resposta::erro('validacao', 'Dados inválidos.', 422, ['campos' => $erros]);
        }

        try {
            $stmt = $this->pdo->prepare(
                'INSERT INTO usuarios (nome, email, senha_hash, uuid)
                 VALUES (:nome, :email, :senha, :uuid)'
            );
            $stmt->execute([
                ':nome'  => trim($dados['nome']),
                ':email' => mb_strtolower(trim($dados['email'])),
                ':senha' => password_hash($dados['senha'], PASSWORD_DEFAULT),
                ':uuid'  => bin2hex(random_bytes(16)),
            ]);
        } catch (PDOException $e) {
            // A checagem antecipada do e-mail tem corrida: duas requisições
            // simultâneas passam as duas. Quem garante de verdade é o UNIQUE
            // do banco — por isso o catch do 23000 também existe.
            if ($e->getCode() === '23000') {
                return Resposta::erro('email_duplicado', 'E-mail já cadastrado.', 409);
            }
            throw $e;
        }

        $id = (int) $this->pdo->lastInsertId();
        header('Location: /api/usuarios/' . $id);

        return Resposta::json($this->buscar($id), 201);
    }

    /** PUT /api/usuarios/{id} */
    public function atualizar(array $params): array
    {
        $id = (int) $params['id'];

        if ($this->buscar($id) === null) {
            return Resposta::erro('nao_encontrado', 'Usuário não encontrado.', 404);
        }

        $dados = $this->corpoJson();
        $erros = $this->validar($dados, exigirSenha: false, ignorarId: $id);

        if ($erros !== []) {
            return Resposta::erro('validacao', 'Dados inválidos.', 422, ['campos' => $erros]);
        }

        $stmt = $this->pdo->prepare(
            'UPDATE usuarios SET nome = :nome, email = :email WHERE id = :id'
        );
        $stmt->execute([
            ':nome'  => trim($dados['nome']),
            ':email' => mb_strtolower(trim($dados['email'])),
            ':id'    => $id,
        ]);

        return Resposta::json($this->buscar($id));
    }

    /** DELETE /api/usuarios/{id} */
    public function remover(array $params): array
    {
        $stmt = $this->pdo->prepare('DELETE FROM usuarios WHERE id = :id');
        $stmt->execute([':id' => (int) $params['id']]);

        if ($stmt->rowCount() === 0) {
            return Resposta::erro('nao_encontrado', 'Usuário não encontrado.', 404);
        }

        // 204: sucesso sem corpo. Não devolva JSON aqui.
        http_response_code(204);
        return ['status' => 204, 'corpo' => null];
    }

    private function buscar(int $id): ?array
    {
        $stmt = $this->pdo->prepare(
            'SELECT id, nome, email, criado_em FROM usuarios WHERE id = :id'
        );
        $stmt->execute([':id' => $id]);

        return $stmt->fetch(PDO::FETCH_ASSOC) ?: null;
    }

    private function corpoJson(): array
    {
        $bruto = file_get_contents('php://input');

        try {
            return json_decode($bruto ?: '{}', true, 512, JSON_THROW_ON_ERROR);
        } catch (JsonException) {
            return [];
        }
    }

    private function validar(array $d, bool $exigirSenha = true, ?int $ignorarId = null): array
    {
        $erros = [];

        if (trim($d['nome'] ?? '') === '') {
            $erros['nome'] = 'Obrigatório.';
        }

        $email = trim($d['email'] ?? '');

        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            $erros['email'] = 'E-mail inválido.';
        } else {
            $sql = 'SELECT COUNT(*) FROM usuarios WHERE email = :email';
            $bind = [':email' => mb_strtolower($email)];

            if ($ignorarId !== null) {
                $sql .= ' AND id <> :id';   // no update, ele mesmo não conta
                $bind[':id'] = $ignorarId;
            }

            $stmt = $this->pdo->prepare($sql);
            $stmt->execute($bind);

            if ((int) $stmt->fetchColumn() > 0) {
                $erros['email'] = 'E-mail já cadastrado.';
            }
        }

        if ($exigirSenha && mb_strlen($d['senha'] ?? '') < 8) {
            $erros['senha'] = 'Mínimo de 8 caracteres.';
        }

        return $erros;
    }
}

$router->get('/api/usuarios',      fn ($p) => $controller->index($p));
$router->get('/api/usuarios/{id}', fn ($p) => $controller->mostrar($p));
$router->post('/api/usuarios',     fn ($p) => $controller->criar($p));
$router->put('/api/usuarios/{id}', fn ($p) => $controller->atualizar($p));
$router->delete('/api/usuarios/{id}', fn ($p) => $controller->remover($p));

✓ Resposta: Verificar o pai antes é o que dá significado às respostas: 404 quando o usuário não existe, 200 com lista vazia quando existe mas não tem pedidos. Sem isso, o cliente da API não consegue distinguir "id errado" de "nenhum pedido ainda".

<?php

declare(strict_types=1);

final class PedidoController
{
    public function __construct(private readonly PDO $pdo) {}

    /** GET /api/usuarios/{id}/pedidos?pagina=1&por_pagina=20 */
    public function porUsuario(array $params): array
    {
        $usuarioId = (int) $params['id'];

        // Verificar o pai PRIMEIRO muda a semântica da resposta:
        // usuário inexistente → 404
        // usuário sem pedidos → 200 com lista vazia
        // Sem essa checagem, os dois casos devolveriam a mesma coisa.
        if (!$this->usuarioExiste($usuarioId)) {
            return Resposta::erro('usuario_nao_encontrado',
                                  "Usuário {$usuarioId} não existe.", 404);
        }

        $pagina = max(1, (int) ($_GET['pagina'] ?? 1));
        $porPagina = min(100, max(1, (int) ($_GET['por_pagina'] ?? 20)));

        $filtros = ['p.usuario_id = :usuario'];
        $bind = [':usuario' => $usuarioId];

        if (($status = $_GET['status'] ?? null) !== null) {
            $filtros[] = 'p.status = :status';
            $bind[':status'] = $status;
        }

        $where = implode(' AND ', $filtros);

        $stmtTotal = $this->pdo->prepare("SELECT COUNT(*) FROM pedidos p WHERE {$where}");
        $stmtTotal->execute($bind);
        $total = (int) $stmtTotal->fetchColumn();

        $stmt = $this->pdo->prepare(
            "SELECT p.id, p.status, p.total, p.criado_em,
                    COUNT(i.id) AS itens
               FROM pedidos p
               LEFT JOIN pedido_itens i ON i.pedido_id = p.id
              WHERE {$where}
           GROUP BY p.id, p.status, p.total, p.criado_em
           ORDER BY p.criado_em DESC
              LIMIT :limite OFFSET :offset"
        );

        foreach ($bind as $chave => $valor) {
            $stmt->bindValue($chave, $valor);
        }
        $stmt->bindValue(':limite', $porPagina, PDO::PARAM_INT);
        $stmt->bindValue(':offset', ($pagina - 1) * $porPagina, PDO::PARAM_INT);
        $stmt->execute();

        $paginas = (int) ceil($total / $porPagina);

        return Resposta::json([
            'dados' => $stmt->fetchAll(PDO::FETCH_ASSOC),
            'meta'  => [
                'usuario_id' => $usuarioId,
                'pagina'     => $pagina,
                'por_pagina' => $porPagina,
                'total'      => $total,
                'paginas'    => $paginas,
            ],
            'links' => [
                'self'     => "/api/usuarios/{$usuarioId}/pedidos?pagina={$pagina}",
                'proxima'  => $pagina < $paginas
                    ? "/api/usuarios/{$usuarioId}/pedidos?pagina=" . ($pagina + 1) : null,
                'anterior' => $pagina > 1
                    ? "/api/usuarios/{$usuarioId}/pedidos?pagina=" . ($pagina - 1) : null,
            ],
        ]);
    }

    private function usuarioExiste(int $id): bool
    {
        $stmt = $this->pdo->prepare('SELECT 1 FROM usuarios WHERE id = :id LIMIT 1');
        $stmt->execute([':id' => $id]);

        return $stmt->fetchColumn() !== false;
    }
}

$router->get('/api/usuarios/{id}/pedidos', fn ($p) => $pedidoController->porUsuario($p))
       ->middleware($autenticar);

// GET /api/usuarios/7/pedidos?pagina=1
// { "dados": [...], "meta": {...}, "links": { "proxima": "...?pagina=2" } }
//
// GET /api/usuarios/999/pedidos
// 404 { "erro": "usuario_nao_encontrado" }

✓ Resposta: Confiar em X-Forwarded-For sem validar é o furo comum: o cliente pode forjar o header e trocar de "IP" a cada requisição. Só aceite esse header vindo de um proxy seu, e nunca guarde o IP em texto puro num rate limiter de longa duração — sha1 na chave já ajuda.

<?php

declare(strict_types=1);

interface LimitadorInterface
{
    /** @return array{permitido: bool, restante: int, retry_after: int} */
    public function verificar(string $chave, int $limite, int $janelaSegundos): array;
}

final class LimitadorApcu implements LimitadorInterface
{
    public function verificar(string $chave, int $limite, int $janela): array
    {
        $agora = time();
        $chave = 'rl:' . sha1($chave);

        // Janela deslizante: guarda os timestamps e descarta os que saíram
        // da janela. Mais justo que o contador fixo, onde o cliente pode
        // gastar o limite todo no fim de uma janela e de novo no começo da
        // seguinte — o dobro em poucos segundos.
        $registros = apcu_fetch($chave) ?: [];
        $registros = array_values(array_filter(
            $registros,
            static fn(int $t): bool => $t > $agora - $janela,
        ));

        if (count($registros) >= $limite) {
            $maisAntigo = min($registros);

            return [
                'permitido'   => false,
                'restante'    => 0,
                'retry_after' => max(1, ($maisAntigo + $janela) - $agora),
            ];
        }

        $registros[] = $agora;
        apcu_store($chave, $registros, $janela);

        return [
            'permitido'   => true,
            'restante'    => $limite - count($registros),
            'retry_after' => 0,
        ];
    }
}

/** Alternativa sem APCu, para hospedagem compartilhada. */
final class LimitadorArquivo implements LimitadorInterface
{
    public function __construct(private readonly string $diretorio = '/tmp/ratelimit') {}

    public function verificar(string $chave, int $limite, int $janela): array
    {
        if (!is_dir($this->diretorio)) {
            mkdir($this->diretorio, 0700, true);
        }

        $arquivo = $this->diretorio . '/' . sha1($chave) . '.json';
        $agora = time();

        $handle = fopen($arquivo, 'c+');

        // LOCK_EX é o que impede duas requisições simultâneas de lerem o
        // mesmo contador e gravarem por cima uma da outra.
        flock($handle, LOCK_EX);

        $conteudo = stream_get_contents($handle);
        $registros = $conteudo ? (json_decode($conteudo, true) ?: []) : [];

        $registros = array_values(array_filter(
            $registros, static fn(int $t): bool => $t > $agora - $janela
        ));

        $permitido = count($registros) < $limite;

        if ($permitido) {
            $registros[] = $agora;
        }

        ftruncate($handle, 0);
        rewind($handle);
        fwrite($handle, json_encode($registros));

        flock($handle, LOCK_UN);
        fclose($handle);

        return [
            'permitido'   => $permitido,
            'restante'    => max(0, $limite - count($registros)),
            'retry_after' => $permitido ? 0 : max(1, (min($registros) + $janela) - $agora),
        ];
    }
}

// ---------- Middleware ----------------------------------------------------
function limitarTaxa(LimitadorInterface $limitador, int $limite = 100, int $janela = 3600): callable
{
    return static function (array $params, callable $proximo) use ($limitador, $limite, $janela): mixed {
        $ip = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'] ?? 'desconhecido';
        $ip = trim(explode(',', $ip)[0]);   // o primeiro da cadeia de proxies

        $r = $limitador->verificar($ip, $limite, $janela);

        header('X-RateLimit-Limit: ' . $limite);
        header('X-RateLimit-Remaining: ' . $r['restante']);

        if (!$r['permitido']) {
            http_response_code(429);
            header('Retry-After: ' . $r['retry_after']);

            return [
                'erro'     => 'muitas_requisicoes',
                'mensagem' => "Limite de {$limite} requisições por hora excedido.",
                'tente_em' => $r['retry_after'] . 's',
            ];
        }

        return $proximo($params);
    };
}

$router->middlewareGlobal(limitarTaxa(new LimitadorApcu(), limite: 100, janela: 3600));

✓ Resposta: Repare que usuarios aponta para a mesma classe nas duas versões: versionar não obriga a duplicar tudo, só o que mudou de contrato. E os cabeçalhos Deprecation/Sunset são o que permite desligar a v1 um dia sem pegar ninguém de surpresa.

<?php

declare(strict_types=1);

enum VersaoApi: string
{
    case V1 = 'v1';
    case V2 = 'v2';

    public function depreciada(): bool
    {
        return $this === self::V1;
    }

    public function sunsetEm(): ?string
    {
        return $this === self::V1 ? '2027-01-01' : null;
    }
}

final class ApiVersion
{
    /** @var array<string, array<string, class-string>> versão => recurso => controller */
    private const MAPA = [
        'v1' => [
            'produtos' => ProdutoControllerV1::class,
            'usuarios' => UsuarioControllerV1::class,
        ],
        'v2' => [
            'produtos' => ProdutoControllerV2::class,
            // usuarios não mudou na v2: reaproveita o da v1.
            'usuarios' => UsuarioControllerV1::class,
        ],
    ];

    public const PADRAO = VersaoApi::V2;

    /** Lê /api/v1/produtos → [VersaoApi::V1, 'produtos', resto] */
    public static function daUri(string $uri): array
    {
        $caminho = trim(parse_url($uri, PHP_URL_PATH) ?? '', '/');
        $partes = explode('/', $caminho);

        // Espera api/{versao}/{recurso}/...
        if (($partes[0] ?? '') !== 'api') {
            throw new InvalidArgumentException('URI fora do prefixo /api.');
        }

        $versao = VersaoApi::tryFrom($partes[1] ?? '');

        if ($versao === null) {
            // Sem versão na URL: assume a padrão e desloca os índices.
            $versao = self::PADRAO;
            $recurso = $partes[1] ?? '';
            $resto = array_slice($partes, 2);
        } else {
            $recurso = $partes[2] ?? '';
            $resto = array_slice($partes, 3);
        }

        return [$versao, $recurso, $resto];
    }

    public static function controller(VersaoApi $versao, string $recurso): object
    {
        $classe = self::MAPA[$versao->value][$recurso]
            ?? throw new RuntimeException(
                "Recurso '{$recurso}' não existe na {$versao->value}."
            );

        return new $classe();
    }

    /** Avisa o cliente que a versão vai sair do ar (RFC 8594). */
    public static function cabecalhos(VersaoApi $versao): void
    {
        header('X-Api-Version: ' . $versao->value);

        if ($versao->depreciada()) {
            header('Deprecation: true');
            header('Sunset: ' . $versao->sunsetEm());
            header('Link: </api/v2>; rel="successor-version"');
        }
    }
}

// ---------- Os controllers convivem --------------------------------------
final class ProdutoControllerV1
{
    public function index(array $params): array
    {
        // Formato antigo: lista crua, preço como float.
        return [
            ['id' => 1, 'nome' => 'Teclado', 'preco' => 349.90],
        ];
    }
}

final class ProdutoControllerV2
{
    public function index(array $params): array
    {
        // Formato novo: envelope com meta, preço em centavos (sem float),
        // e campos renomeados. Quebrar contrato é o motivo de existir a v2.
        return [
            'dados' => [
                ['id' => 1, 'titulo' => 'Teclado', 'preco_centavos' => 34990,
                 'moeda' => 'BRL'],
            ],
            'meta' => ['versao' => 'v2', 'total' => 1],
        ];
    }
}

final class UsuarioControllerV1
{
    public function index(array $params): array
    {
        return [['id' => 7, 'nome' => 'Ana']];
    }
}

// ---------- Despacho ------------------------------------------------------
try {
    [$versao, $recurso, $resto] = ApiVersion::daUri($_SERVER['REQUEST_URI'] ?? '/api/v2/produtos');

    ApiVersion::cabecalhos($versao);

    $controller = ApiVersion::controller($versao, $recurso);

    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($controller->index(['resto' => $resto]), JSON_UNESCAPED_UNICODE);

} catch (RuntimeException $e) {
    http_response_code(404);
    echo json_encode(['erro' => 'recurso_desconhecido', 'mensagem' => $e->getMessage()]);
}

// GET /api/v1/produtos → [{"id":1,"nome":"Teclado","preco":349.9}]
//   Deprecation: true / Sunset: 2027-01-01
// GET /api/v2/produtos → {"dados":[{"id":1,"titulo":"Teclado",...}],"meta":{...}}