Criando um Controller de API REST com Respostas JSON Padronizadas em PHP

A falta de padronização no formato das respostas de uma API pode causar inconsistências no front-end e dificultar a manutenção da aplicação. Este Controller encapsula a lógica de resposta HTTP em PHP, garantindo que todas as saídas (sucesso ou erro) sigam uma estrutura JSON uniforme e previsível.

PHP

<?php

/**
 * Controller base para APIs REST com suporte a respostas JSON estruturadas.
 */
class ApiController
{
    /**
     * Envia uma resposta JSON padronizada para o cliente HTTP.
     *
     * @param bool   $success Status da operação (true/false).
     * @param mixed  $data    Dados principais a serem retornados na resposta.
     * @param string $message Mensagem informativa sobre o processamento.
     * @param int    $code    Código de status HTTP (ex: 200, 201, 400, 500).
     */
    protected function jsonResponse(bool $success, mixed $data = null, string $message = '', int $code = 200): void
    {
        // Define o cabeçalho oficial para conteúdo JSON
        header('Content-Type: application/json; charset=utf-8');
        
        // Define o código de resposta HTTP
        http_response_code($code);

        // Estrutura do envelope padrão retornado pela API
        $payload = [
            'success'   => $success,
            'message'   => $message,
            'data'      => $data,
            'timestamp' => date('Y-m-d H:i:s')
        ];

        // Serializa o array e encerra a execução do script
        echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        exit;
    }

    /**
     * Atalho para respostas de sucesso.
     */
    public function success(mixed $data = null, string $message = 'Operação realizada com sucesso', int $code = 200): void
    {
        $this->jsonResponse(true, $data, $message, $code);
    }

    /**
     * Atalho para respostas de erro.
     */
    public function error(string $message = 'Ocorreu um erro no processamento', int $code = 400, mixed $data = null): void
    {
        $this->jsonResponse(false, $data, $message, $code);
    }
}

// --- Exemplo de Uso Prático ---

class UserController extends ApiController
{
    public function show(int $id): void
    {
        // Simulação de busca de usuário no banco de dados
        if ($id === 1) {
            $user = ['id' => 1, 'nome' => 'Ana Silva', 'email' => 'ana@empresa.com'];
            $this->success($user, 'Usuário encontrado com sucesso');
        } else {
            $this->error('Usuário não encontrado', 404);
        }
    }
}

// Simulação da chamada do Controller
$controller = new UserController();

// Teste de resposta com sucesso (HTTP 200)
$controller->show(1);

// Teste de resposta com erro (HTTP 404) - descomente para testar
// $controller->show(999);

• Estrutura de Envelope Única (Envelope Pattern): Todas as respostas possuem a mesma chave base (success, message, data, timestamp), simplificando a desserialização e o tratamento de dados no consumo por clientes front-end ou mobile.
• Opções de Serialização (JSON_UNESCAPED_UNICODE): O uso dessa flag no json_encode() preserva acentos e caracteres especiais UTF-8 nativos no retorno JSON sem converter para códigos escapados Unicode (ex: \u00e1).
• Sinalização do Status HTTP (http_response_code): Alinha a resposta do corpo JSON com o status code real do protocolo HTTP, mantendo a API compatível com os padrões de arquitetura REST.
• Interrupção de Fluxo (exit): Garante que nenhum conteúdo adicional (como warnings ou quebras de linha acidentais do PHP) estrague a formatação válida do JSON enviado ao cliente.