Acervo.estudos
Trilhas Enviar material Entrar
mapa · Intermediário

4.2 Estrutura de um sistema backend

Como organizar uma API em PHP puro: front controller, roteador, controlador, modelo e conexão PDO, com os erros de status, validação e segurança do projeto da aula corrigidos.

por @julio · rev. 23 set · 6 telas

Cada arquivo com uma responsabilidade

Camadas de um backend

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom

Regra de ouro: o modelo não faz echo nem http_response_code; o controlador não escreve SQL. Assim dá para trocar o banco sem mexer nas rotas, e testar cada parte separada.

⚠ A página original diz "arquitetura em camadas (layered architecture), também conhecida como MVC". São conceitos diferentes: camadas é um estilo arquitetural geral (apresentação, negócio, dados); MVC é um padrão que separa modelo, visão e controlador. Um projeto pode usar MVC dentro de uma arquitetura em camadas.

O projeto da aula, com dois ajustes

Organização de pastas

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
ArquivoPapelO que corrigir no original
public/index.phpCabeçalho JSON, exibição de erros, inclui o roteadorRegistrar um tratador global de exceções (tela 3)
src/routes/routes.phpswitch no método; preg_match para /users/{id}405 + Allow quando a rota existe com outro método
src/controllers/UserController.phpLê o JSON, valida, chama o modelo, respondeValidar os dois campos no PUT; 404 de verdade
src/config/Database.phpCria o PDOutf8mb4, senha fora do código, uma conexão só
src/models/User.phpCRUD com prepared statementsUsar rowCount(); converter o id para int
tests/requests.restRequisições de teste—

Tudo fora de public/ fica inacessível pelo navegador: é ali que moram código e configuração. Em projetos maiores, o Composer (autoload PSR-4) substitui os require_once.

index.php + routes.php

Entrada e roteador

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
<?php
// public/index.php
declare(strict_types=1);

header('Content-Type: application/json; charset=utf-8');
ini_set('display_errors', '0');       // erros vão para o log, não para a resposta

set_exception_handler(function (Throwable $e): void {
    error_log((string) $e);
    http_response_code(500);
    echo json_encode(['erro' => 'Erro interno no servidor'], JSON_UNESCAPED_UNICODE);
});

require __DIR__ . '/../src/routes/routes.php';
// trecho do roteador: rota existe, método não
if ($caminho === '/users' && !in_array($metodo, ['GET', 'POST'], true)) {
    header('Allow: GET, POST');
    responder(['erro' => 'Método não permitido'], 405);
}

⚠ O projeto da página original não trata exceções de banco. Testado: um POST com e-mail já cadastrado devolve status 200 e, no lugar do JSON, um Fatal error: Uncaught PDOException … Duplicate entry em HTML com caminhos do servidor e argumentos. O código 500 aparece na lista da aula, mas nunca é emitido.

⚠ No roteador original, PUT/DELETE em /users e GET em /users/1 respondem 404 "Rota … não encontrada". Como o recurso existe e só o método não é aceito, o adequado é 405 com cabeçalho Allow; o 405 do default também sai sem Allow.

Validar, chamar o modelo, escolher o status

Controlador

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
public function atualizarUsuario(int $id): void
{
    $d = json_decode(file_get_contents('php://input'), true);
    $nome  = trim((string) ($d['nome'] ?? ''));
    $email = filter_var($d['email'] ?? '', FILTER_VALIDATE_EMAIL);

    if ($nome === '' || $email === false) {
        $this->respostaJson(['erro' => 'Informe nome e e-mail válidos'], 422);
    }
    if (!$this->model->existe($id)) {
        $this->respostaJson(['erro' => 'Usuário não encontrado'], 404);
    }
    $this->model->atualizar($id, $nome, $email);
    $this->respostaJson(['id' => $id, 'nome' => $nome, 'email' => $email]);
}

⚠ No original, atualizarUsuario() só testa empty($dados). Um PUT com apenas {"email": …} tenta gravar nome = NULL; o MySQL recusa (erro 1048) e a resposta sai com status 200 e um Fatal error em HTML (testado).

Database.php e User.php

Conexão e modelo

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
final class Database
{
    private static ?PDO $pdo = null;

    public static function conexao(): PDO
    {
        if (self::$pdo === null) {
            $cfg = require __DIR__ . '/../../config/database.php';
            self::$pdo = new PDO($cfg['dsn'], $cfg['user'], $cfg['pass'], [
                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
                PDO::ATTR_EMULATE_PREPARES   => false,
            ]);
        }
        return self::$pdo;
    }
}

// no modelo User
public function excluir(int $id): bool
{
    $stmt = $this->pdo->prepare('DELETE FROM usuarios WHERE id = :id');
    $stmt->execute(['id' => $id]);
    return $stmt->rowCount() === 1;      // false se o id não existia
}

⚠ No original, atualizar() e excluir() devolvem $stmt->execute(), que com ERRMODE_EXCEPTION é sempre true. O 404 do controlador nunca acontece: testado, PUT e DELETE em /users/999 respondem 200 "com sucesso". E o texto diz que atualizar() "retorna false se falhar"; com exceções ligadas, ela lança.

⚠ O Database.php original "garante que apenas uma instância seja utilizada", mas cada new User() cria outro Database e outra conexão. Usa charset=utf8 (utf8mb3): nome com emoji dá erro 1366 (testado). Traz root e senha escritos no código versionado. E, se a conexão falha, faz echo $e->getMessage() (usuário e host à mostra) com status 200.

Teste antes de seguir

Revisão rápida

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
Por que só a pasta public/ fica exposta ao servidor web?

Para que ninguém baixe pelo navegador arquivos de código ou de configuração (com senha). Só o index.php precisa ser acessível.

excluir() devolve $stmt->execute(). Por que isso não detecta id inexistente?

execute() só diz se o comando rodou; um DELETE que não encontra linha roda sem erro. Quem informa quantas linhas saíram é rowCount().

Onde deve ficar o SQL: no controlador ou no modelo?

No modelo. O controlador cuida de HTTP (entrada, validação, status); o modelo, dos dados.

Um POST com e-mail repetido: qual status a API deveria devolver?

409 Conflict. Na captura da PDOException, errorInfo[1] === 1062 identifica a chave duplicada; outros erros viram 500.

← Voltar ao curso