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.
Camadas de um backend
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.
Organização de pastas
| Arquivo | Papel | O que corrigir no original |
|---|---|---|
| public/index.php | Cabeçalho JSON, exibição de erros, inclui o roteador | Registrar um tratador global de exceções (tela 3) |
| src/routes/routes.php | switch no método; preg_match para /users/{id} | 405 + Allow quando a rota existe com outro método |
| src/controllers/UserController.php | Lê o JSON, valida, chama o modelo, responde | Validar os dois campos no PUT; 404 de verdade |
| src/config/Database.php | Cria o PDO | utf8mb4, senha fora do código, uma conexão só |
| src/models/User.php | CRUD com prepared statements | Usar rowCount(); converter o id para int |
| tests/requests.rest | Requisiçõ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.
Entrada e roteador
<?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.
Controlador
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).
Conexão e modelo
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.
Revisão rápida
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.