O que é o Haki, o que ele faz por você e por onde começar.
Conheça o Haki
O Haki é um miniframework PHP para criar APIs REST. Ele cuida de tudo o que se repete em toda API (rotas, leitura da requisição, respostas JSON, validação, login com token e tratamento de erros) para que você escreva só as regras da sua aplicação.
A ideia é ser simples o bastante para quem está começando e organizado o bastante para crescer. Uma API funcional cabe em poucas linhas:
Uma API é um programa que não mostra telas: ele recebe pedidos e responde com dados. Quem faz os pedidos é outro programa, como um site em React, um app de celular ou outro servidor.
Cada pedido (uma requisição) tem duas partes principais:
O método, que diz o que se quer fazer: GET (buscar), POST (criar), PUT/PATCH (alterar), DELETE (apagar).
O caminho, que diz sobre o que: /produtos, /produtos/10.
A API devolve uma resposta com um código de status (200 deu certo, 404 não encontrado, 401 não autenticado...) e, normalmente, dados em JSON, um formato de texto que qualquer linguagem entende.
exemplo de conversa com uma API
GET /produtos/10 ← o cliente pede o produto 10
HTTP/1.1 200 OK ← a API responde: deu certo
{"id": 10, "nome": "Chapéu de palha", "preco": 49.9}
O que o Haki faz por você
Quando uma requisição chega, o Haki segue sempre o mesmo caminho:
Encontra a rota certa para o método e o caminho (ou responde 404/405).
Roda os middlewares: código que se repete em várias rotas, como CORS e logs.
Confere o login, se a rota exigir, validando o token JWT.
Valida os dados enviados, se você pedir, respondendo 422 com mensagens claras.
Chama o seu código (o controller), entregando tudo o que ele pediu.
Transforma o retorno em JSON e envia a resposta.
Se algo der errado em qualquer etapa, responde com um erro padronizado, sem expor detalhes internos em produção.
O caminho de toda requisição. Em qualquer etapa, um problema interrompe o fluxo e vira uma resposta de erro padronizada.
Tipado de ponta a ponta
O PHP permite escrever código sem tipos, e muitos frameworks deixam assim. O Haki faz o contrário: ele usa os tipos que você escreve para fazer trabalho por você, e pode exigir que todo o projeto seja tipado.
Onde
Como o Haki usa os tipos
Parâmetros da rota
function show(int $id): "10" vira o número 10, e /produtos/abc responde 404 antes do seu código rodar.
Injeção de dependências
O tipo do parâmetro diz o que entregar: Request $request, Auth $auth, ProdutoRepositoryInterface $produtos.
Validação
$rule->integer() entrega int, $rule->date() entrega DateTimeImmutable, $rule->enum(Plano::class) entrega o enum. Nada chega como texto solto.
Arquivos gerados
Tudo o que o init e o make:request criam já vem com declare(strict_types=1) e tudo tipado.
Tipagem obrigatória
Com $app->requireTypes(), um método sem tipo faz a API responder com erro, dizendo a classe, o método e a linha. O haki check aponta antes de publicar.
public function show($id) // sem tipo: com requireTypes(), a API recusa e diz a linha
public function show(int $id): array // tipado: o Haki converte o {id} e confere o retorno
O resultado é menos erro escondido: um valor errado aparece na hora, com uma mensagem clara, em vez de virar um bug difícil de achar depois. Veja tudo em Tipagem.
Por que usar o Haki?
Pouca coisa para aprender. São poucas classes, e os nomes dizem o que fazem: Request, Response, Auth.
Começa em um comando.php vendor/bin/haki init cria a estrutura do projeto com um exemplo funcionando.
Erros que ensinam. Em desenvolvimento, cada erro vem com uma dica em português explicando como resolver.
Validação fácil.$rule->cpf(), $rule->email(), $rule->text()->length(3, 100), com mensagens prontas em português.
Login pronto. JWT com refresh token, logout e perfis de acesso, sem bibliotecas externas.
Tipado de ponta a ponta. Os tipos que você escreve convertem os dados, escolhem o que injetar e podem ser exigidos em todo o projeto.
Nenhuma dependência. O pacote usa apenas extensões nativas do PHP.
O que você precisa saber antes
PHP básico: variáveis, funções, arrays e classes. Não precisa ser avançado.
Usar o terminal para rodar comandos como composer e php.
Noção de JSON. Se nunca viu, ele parece um array do PHP: {"nome": "Nami", "idade": 20}.
Para testar a API, você pode usar o navegador (para GET), o comando curl ou programas como Insomnia, Postman ou a extensão Thunder Client do VS Code.
Requisitos
Requisito
Para quê
PHP 8.2 ou superior
Obrigatório. Veja a sua versão com php -v.
Composer
Instalar o pacote e carregar as classes
Extensão zip
Usada pelo Composer para baixar e extrair o pacote
Extensões json, mbstring, openssl
Obrigatórias (já vêm em quase toda instalação)
Extensão pdo_sqlite
Só se você usar a autenticação JWT
Por onde começar
Siga as páginas na ordem do menu. Cada uma parte do que foi feito na anterior:
Quando quiser consultar um método rapidamente, use a Referência da API ou a busca (Ctrl + K).
Instalação
Do composer require à primeira API respondendo.
Antes de instalar: as extensões do PHP
Veja quais extensões estão ativas no seu PHP:
php -m
Confira se estas duas aparecem na lista:
Extensão
Por que precisa
zip
O Composer baixa os pacotes compactados em .zip. Sem ela, o Haki não é instalado.
pdo_sqlite
Guarda os tokens da autenticação JWT. Só é necessária se você usar login.
Se alguma estiver faltando, abra o seu php.ini (o comando php --ini mostra onde ele está), procure as linhas abaixo e apague o ; do começo de cada uma:
php.ini, antes
;extension=zip
;extension=pdo_sqlite
php.ini, depois
extension=zip
extension=pdo_sqlite
Salve o arquivo, feche e abra o terminal de novo, e rode php -m mais uma vez para confirmar.
Instalando com o Composer
Crie uma pasta para o seu projeto e, dentro dela, rode:
composer require shankscode/haki
O Composer cria a pasta vendor/ com o framework dentro (vendor/shankscode/haki) e o comando vendor/bin/haki. Para criar as pastas e os arquivos da sua aplicação, rode php vendor/bin/haki init (veja o passo a passo abaixo).
Erro comum
Se aparecer a mensagem abaixo e a pasta vendor/ não for criada, a extensão zip está desativada. Ative-a como mostrado acima e rode o composer require de novo.
Failed to download shankscode/haki from dist: The zip extension and unzip/7z commands are both missing, skipping.
Sua primeira API em 5 minutos
Instale o Haki em uma pasta vazia
composer require shankscode/haki
Crie a estrutura padrão do projeto
php vendor/bin/haki init
O comando cria as pastas app/, bootstrap/, routes/, public/ e storage/, os arquivos .env e .gitignore, e já deixa uma rota e um controller de exemplo funcionando. Ele também configura o autoload no seu composer.json.
Suba o servidor embutido do PHP
php -S localhost:8000 -t public
Acesse no navegador ou no terminal
curl http://localhost:8000/
{ "mensagem": "Bem-vindo ao Haki!", "caminho": "/" }
Pronto, sua API está no ar. A próxima página explica cada arquivo criado.
Nota
O -t public diz ao PHP que só a pasta public/ fica acessível pela web. Assim, o .env, o código e o banco de tokens nunca podem ser baixados por alguém de fora.
Dica
O init nunca apaga nada: se um arquivo já existir, ele é mantido. Para recriar os arquivos padrão, use php vendor/bin/haki init --force.
Servidores web
Em produção, aponte a raiz do site para a pasta public/ e redirecione todas as requisições para o index.php.
As duas linhas do meio repassam o cabeçalho Authorization, que alguns Apaches descartam e que é necessário para o JWT.
Estrutura de pastas
Onde fica cada coisa e o que o haki init cria para você.
A estrutura recomendada
O Haki não obriga nenhuma estrutura, mas seguir esta deixa o projeto fácil de entender, de testar e de crescer. Cada pasta tem uma responsabilidade só.
minha-api/
├── app/
│ ├── Controllers/recebem a requisição e devolvem a resposta
│ ├── Requests/classes de validação (make:request)
│ ├── Services/regras de negócio (login, cálculo, envio...)
│ ├── Repositories/acesso a dados (banco, API externa, arquivo)
│ ├── Contracts/interfaces que os serviços usam
│ ├── Models/objetos que representam os dados
│ └── Middleware/código que roda antes/depois dos controllers
├── bootstrap/
│ └── app.php monta a aplicação: container, middlewares e rotas
├── routes/
│ └── api.php todas as rotas em um só lugar
├── public/
│ └── index.php única porta de entrada (raiz do servidor web)
├── storage/banco de tokens e chaves (criado automaticamente)
├── vendor/criado pelo Composer, não mexa
├── .env segredos e configurações (não versionar)
├── .gitignore
└── composer.json
Como uma requisição percorre as pastas
Entender esse caminho ajuda a saber onde colocar cada pedaço de código:
public/index.php recebe a requisição e carrega bootstrap/app.php.
O Haki procura a rota em routes/api.php.
Os middlewares rodam (CORS, autenticação, perfil...).
O controller lê os dados da requisição e chama um service.
O service aplica a regra de negócio e usa um repository para buscar ou salvar dados.
O controller devolve o resultado, e o Haki transforma em JSON.
Regra prática
Controller não acessa banco. Service não conhece HTTP. Repository não tem regra de negócio. Se um arquivo começar a fazer duas dessas coisas, ele está na pasta errada.
Criando a estrutura com haki init
Você não precisa criar as pastas à mão. Depois do composer require, rode:
php vendor/bin/haki init
Criando a estrutura do projeto Haki...
✔ criado app/Controllers/HomeController.php
✔ criado bootstrap/app.php
✔ criado routes/api.php
✔ criado public/index.php
✔ criado .env
✔ criado .env.example
✔ criado .gitignore
✔ alterado composer.json (autoload App\ → app/)
✔ Autoload atualizado.
As pastas vazias (Requests, Services, Repositories, Contracts, Models, Middleware, storage) ganham um arquivo .gitkeep para o Git guardá-las. Veja abaixo o que vem em cada arquivo.
public/index.php
A única porta de entrada. Ele só carrega a aplicação e a executa:
public/index.php
<?php
declare(strict_types=1);
// Única porta de entrada da API. Rode com: php -S localhost:8000 -t public
$app = require __DIR__ . '/../bootstrap/app.php';
$app->run();
bootstrap/app.php
É aqui que a aplicação é montada: ligações do container, middlewares globais e rotas. Ele é separado do index.php para que os testes possam carregar a aplicação sem subir um servidor.
bootstrap/app.php
<?php
declare(strict_types=1);
use Haki\Haki;
require __DIR__ . '/../vendor/autoload.php';
$app = new Haki(dirname(__DIR__));
// Interfaces de app/Contracts são ligadas sozinhas às classes de app/Repositories pelo nome:
// ProdutoRepositoryInterface → ProdutoRepository ou PdoProdutoRepository.
$app->container()->discover('App\\Contracts', 'App\\Repositories');
// Exige tipos em todo o código do projeto (veja a página Tipagem).
$app->requireTypes();
// Para casos fora do padrão, ligue manualmente:
// $app->container()->bind(PagamentoInterface::class, StripePagamento::class);
// Middlewares globais, por exemplo:
// $app->middleware(Cors::class);
// Rotas
$app->routes(__DIR__ . '/../routes/api.php');
return $app;
routes/api.php
Todas as rotas ficam aqui. O projeto começa com uma só, que aponta para o controller de exemplo. As rotas ficam soltas no arquivo, sem função em volta:
O $app é criado em bootstrap/app.php com new Haki(...). A linha $app->routes(...) carrega este arquivo e entrega a ele essa mesma variável. A linha /** @var Haki\Haki $app */ não executa nada: só avisa o editor qual é o tipo, para ele completar os métodos.
Para separar as rotas em mais de um arquivo, carregue cada um no bootstrap:
<?php
declare(strict_types=1);
namespace App\Controllers;
use Haki\Http\Request;
use Haki\Http\Response;
final class HomeController
{
public function index(Request $request, Response $response): Response
{
return $response->json([
'mensagem' => 'Bem-vindo ao Haki!',
'caminho' => $request->path(),
]);
}
}
composer.json
O init adiciona o bloco autoload. É ele que faz a classe App\Controllers\HomeController ser encontrada em app/Controllers/HomeController.php:
Um arquivo por classe, com o mesmo nome da classe. É isso que permite ao Composer encontrá-la sozinho.
Configuração
O arquivo .env, os modos de desenvolvimento e produção e todas as variáveis.
O arquivo .env
Algumas configurações mudam entre o seu computador e o servidor: a senha do banco, o modo de erro, o segredo do login. Em vez de escrever esses valores no código, eles ficam em um arquivo chamado .env, na raiz do projeto.
Cada linha é um par NOME=valor. Linhas começando com # são comentários:
.env
APP_ENV=development
# Gere com: php vendor/bin/haki key:generate
JWT_SECRET=a3f9c2...
# Variáveis da sua aplicação também podem ficar aqui
DB_HOST=localhost
DB_NAME=minha_api
O Haki lê esse arquivo sozinho quando você cria a aplicação com new Haki(dirname(__DIR__)). Você não precisa instalar nada para isso.
Regras do arquivo
Sem espaços em volta do =: APP_ENV=development.
Valores com espaço vão entre aspas: APP_NAME="Minha API".
Um comentário pode vir no fim da linha: JWT_TTL=900 # 15 minutos.
Se a mesma variável já existir no servidor (definida no Docker, na hospedagem ou pelo vlucas/phpdotenv), o valor do servidor vale e o .env é ignorado para ela.
Nunca envie o .env para o Git
Ele guarda segredos. O haki init já cria um .gitignore que o deixa de fora, e um .env.example: uma cópia com as mesmas chaves, mas sem os valores secretos, para mostrar ao time o que precisa ser preenchido. Quem clonar o projeto copia o exemplo e preenche: cp .env.example .env.
Desenvolvimento ou produção
A variável APP_ENV diz em que modo a aplicação está. Ela muda, principalmente, o quanto os erros mostram:
APP_ENV
Modo
Erros mostram
development, dev ou local
Desenvolvimento
Uma dica de solução; em erros 500, também arquivo, linha e trace.
qualquer outro valor, ou ausente
Produção
Só uma mensagem genérica.
O mesmo erro, nos dois modos:
desenvolvimento
{
"erro": "Erro interno do servidor",
"status": 500,
"detalhes": {
"excecao": "PDOException",
"mensagem": "SQLSTATE[HY000] [1045] Access denied for user 'root'",
"arquivo": "C:\\projetos\\minha-api\\app\\Repositories\\PdoProdutoRepository.php",
"linha": 18,
"trace": ["..."]
}
}
produção
{ "erro": "Erro interno do servidor", "status": 500 }
O padrão é produção. Assim, se você esquecer de configurar o servidor, nenhum detalhe interno (caminhos, usuário do banco, trechos de SQL) vaza para quem chama a API.
Os argumentos de new Haki()
A aplicação é criada no bootstrap/app.php:
$app = new Haki(dirname(__DIR__)); // raiz do projeto; o modo vem do APP_ENV
$app = new Haki(dirname(__DIR__), debug: true); // força o modo de desenvolvimento
$app = new Haki(dirname(__DIR__), debug: false); // força o modo de produção
O primeiro argumento é a pasta raiz do projeto, onde o Haki procura o .env e a pasta storage/. Em bootstrap/app.php, __DIR__ vale a pasta bootstrap/, e dirname(__DIR__) sobe um nível até a raiz:
$app->basePath(); // 'C:\projetos\minha-api'
$app->basePath('storage/x'); // 'C:\projetos\minha-api\storage\x'
$app->isDebug(); // true em desenvolvimento
Todas as variáveis do Haki
Variável
Padrão
Descrição
APP_ENV
production
Modo da aplicação
JWT_SECRET
nenhum
Segredo do login (HS256), com no mínimo 32 caracteres
JWT_ALGORITHM
HS256
HS256 ou RS256
JWT_PRIVATE_KEY
nenhum
Caminho da chave privada (RS256)
JWT_PUBLIC_KEY
nenhum
Caminho da chave pública (RS256)
JWT_TTL
900
Validade do access token em segundos (15 min)
JWT_REFRESH_TTL
604800
Validade do refresh token em segundos (7 dias)
JWT_ISSUER
nenhum
Nome do emissor (claim iss), opcional
JWT_DATABASE
storage/haki.sqlite
Arquivo de tokens quando o armazenamento padrão é SQLite; não usado no MySQL automático
DB_CONNECTION
nenhum
sqlite ou mysql (usado pelo comando db e pela sua conexão)
DB_DATABASE
nenhum
Caminho do arquivo (SQLite) ou nome do banco (MySQL)
DB_HOST / DB_PORT
127.0.0.1 / 3306
Servidor MySQL
DB_USERNAME / DB_PASSWORD
nenhum
Usuário e senha do MySQL
As variáveis JWT_* só são necessárias se você usar a autenticação.
Lendo variáveis no seu código
Use Env::get() para ler qualquer variável, inclusive as suas:
use Haki\Support\Env;
$host = Env::get('DB_HOST', 'localhost'); // segundo argumento = valor padrão
$debug = Env::get('APP_DEBUG'); // "true" vira true, "false" vira false
No .env
Env::get() devolve
X=true / X=false
true / false
X= (vazio) ou X=null
o valor padrão
X=900
'900' (texto: converta com (int))
variável inexistente
o valor padrão
Dica
Leia as variáveis em um só lugar, normalmente no bootstrap/app.php ao configurar o container, e passe os valores para as classes pelo construtor. Assim as classes não dependem do .env e ficam fáceis de testar. Veja Criando com uma função.
Rotas
Métodos HTTP, parâmetros na URL, grupos e arquivos de rotas.
Rotas básicas
Uma rota liga um método HTTP e um caminho a um código que responde. O Haki aceita os cinco métodos usados em APIs REST:
Para algo muito curto, uma função anônima resolve:
$app->get('/status', function () {
return ['ok' => true];
});
Para todo o resto, use controllers. Eles deixam o arquivo de rotas legível e o código reutilizável. Use o formato [Classe::class, 'metodo'].
Todos os formatos de handler
O segundo argumento da rota (o handler) pode ser:
Formato
Exemplo
Controller e método
[ProdutoController::class, 'index']
Função anônima
function (Request $request) { ... }
Classe invocável (um método __invoke)
MostrarStatus::class
A classe invocável é útil para controllers de uma ação só:
app/Controllers/MostrarStatus.php
final class MostrarStatus
{
public function __invoke(): array
{
return ['status' => 'online'];
}
}
// routes/api.php
$app->get('/status', MostrarStatus::class);
Trechos entre chaves viram parâmetros. O valor chega no método pelo mesmo nome:
$app->get('/usuarios/{id}/pedidos/{pedido}', function (int $id, int $pedido) {
return ['usuario' => $id, 'pedido' => $pedido];
});
Se você tipar o parâmetro como int, o Haki converte o valor. Se alguém acessar /usuarios/abc/pedidos/1, a resposta é 404 automaticamente, e o seu código nem chega a rodar.
Atenção
Parâmetros vêm da URL, ou seja, do usuário. Valide sempre se o recurso existe e se a pessoa pode acessá-lo.
Grupos de rotas
Grupos aplicam um prefixo e regras em comum a várias rotas de uma vez:
GET /
POST /login
GET /usuarios (auth)
GET /usuarios/{id} (auth)
Detalhes que o Haki resolve
/produtos/ e /produtos são a mesma rota.
A query string (?pagina=2) não interfere na rota.
Rotas fixas têm prioridade: /usuarios/novo vence /usuarios/{id}.
Registrar a mesma rota duas vezes gera um erro na hora, em vez de um bug silencioso.
Limite de requisições: ->limite()
Limita quantas vezes cada IP pode chamar uma rota dentro de uma janela de tempo. Ao passar do máximo, o Haki responde 429 com o cabeçalho Retry-After, sem chegar ao controller.
$app->post('/login', [AuthController::class, 'login'])->limite(5, 900); // 5 vezes a cada 15 minutos
$app->post('/contatos', [ContatoController::class, 'store'])->limite(20, 60); // 20 por minuto
O primeiro número é o máximo e o segundo é a janela, em segundos. Cada rota tem o seu contador: esgotar /login não afeta /refresh.
Ponto
Como funciona
O que conta
Cada chamada, com ou sem sucesso. Para contar só senhas erradas, use LimiteDeTentativas no service de login.
Por quem
Por IP e por rota. Quem não tem IP identificado divide um mesmo contador.
Ordem
Roda antes da autenticação, então um IP bloqueado não gasta consulta ao token.
Armazenamento
MySQL automático com DB_CONNECTION=mysql; nos demais casos, SQLite em storage/haki.sqlite.
Atrás de proxy
Se a API roda atrás de um balanceador, o IP lido é o do balanceador, e todos os clientes compartilham um contador. Nesse caso, o limite precisa de um IP real vindo do proxy, configurado no servidor.
Controllers
As classes que atendem as rotas e recebem tudo injetado.
O que é um controller
Um controller é a classe que atende uma rota. Pense nele como o atendente de uma loja: recebe o pedido (a requisição), chama quem sabe resolver (os services e repositories) e entrega a resposta. Ele não deve fazer o trabalho pesado sozinho.
Cada método público do controller pode responder a uma rota. O normal é ter um controller por recurso da API: ProdutoController para produtos, ClienteController para clientes, e assim por diante.
Criando um controller passo a passo
Crie o arquivo em app/Controllers
O nome do arquivo é o nome da classe: ProdutoController.php.
app/Controllers/ProdutoController.php
<?php
declare(strict_types=1);
namespace App\Controllers;
use Haki\Http\Request;
final class ProdutoController
{
public function index(Request $request): array
{
$pagina = (int) $request->query('pagina', 1);
return ['pagina' => $pagina, 'produtos' => []];
}
public function show(int $id): array
{
return ['produto' => ['id' => $id]];
}
}
O namespace App\Controllers; precisa bater com a pasta. É assim que o Composer encontra a classe.
[ProdutoController::class, 'index'] quer dizer: "nessa rota, chame o método index da classe ProdutoController".
Teste
curl http://localhost:8000/produtos/5
{ "produto": { "id": 5 } }
Nomes de métodos que todo mundo entende
Não é obrigatório, mas seguir estes nomes deixa qualquer pessoa entender o controller de cara:
Rota
Método
Faz
GET /produtos
index
Lista
GET /produtos/{id}
show
Mostra um
POST /produtos
store
Cria
PUT /produtos/{id}
update
Substitui
PATCH /produtos/{id}
patch
Altera uma parte
DELETE /produtos/{id}
destroy
Apaga
Injeção automática
Você nunca precisa criar objetos com new dentro do controller. Basta declarar o que o método precisa nos parâmetros, e o Haki entrega. A ordem dos parâmetros não importa.
public function update(int $id, AtualizarProdutoRequest $request, Response $response): Response
{
$produto = $this->produtos->atualizar($id, $request->validated());
return $response->json(['produto' => $produto]);
}
Dependências pelo construtor
Services e repositories devem chegar pelo construtor, porque o controller inteiro usa. O Haki cria tudo em cadeia:
final class ProdutoController
{
public function __construct(
private readonly ProdutoRepositoryInterface $produtos,
private readonly CriarProdutoService $criarProduto,
) {
}
public function index(): array
{
return ['produtos' => $this->produtos->todos()];
}
public function store(CriarProdutoRequest $request, Response $response): Response
{
$produto = $this->criarProduto->executar($request->validated());
return $response->json(['produto' => $produto], 201);
}
}
Regra prática: no construtor vai o que o controller usa em vários métodos (services, repositories). No método vai o que é daquela requisição (Request, Response, parâmetros da rota, classe de validação).
O que o método pode retornar
Retorno
O cliente recebe
Array ou objeto
JSON, status 200
Response
Exatamente o que você montou (status, cabeçalhos, corpo)
Para uma rota isolada, crie uma classe com o método __invoke e passe só o nome da classe na rota:
final class MostrarStatus
{
public function __invoke(): array
{
return ['status' => 'online'];
}
}
$app->get('/status', MostrarStatus::class);
Erros comuns
Mensagem
Causa e solução
"Não foi possível criar App\Controllers\X: a classe não existe."
O namespace não bate com a pasta, ou o autoload está desatualizado. Confira o namespace e rode composer dump-autoload.
"O método X::y() não existe."
Nome do método errado na rota. Confira maiúsculas e minúsculas.
"O método X::y() precisa ser public."
Troque private/protected por public.
"Não sei como injetar $nome em X::y."
Um parâmetro sem classe que não é parâmetro da rota. Use Request, um {nome} na rota ou dê um valor padrão.
"... a classe é uma interface."
Você pediu uma interface que não foi registrada. Faça o bind() no bootstrap (veja Container).
Em desenvolvimento, todas essas mensagens aparecem na resposta, junto com uma dica de solução.
Controller magro
Se um método passa de umas 10 linhas, ou se começa a ter if de regra de negócio, mova essa lógica para um service em app/Services. O controller deve só ler a requisição, chamar o service e devolver o resultado.
Requisições
Query string, parâmetros de rota, corpo, cabeçalhos e token.
O objeto Request
Tudo o que o cliente envia (URL, parâmetros, corpo, cabeçalhos e token) chega no objeto Request. Para usá-lo, basta pedir um parâmetro do tipo Request no método do controller ou na função da rota. O Haki entrega a requisição atual.
app/Controllers/ProdutoController.php
use Haki\Http\Request;
final class ProdutoController
{
public function index(Request $request): array
{
return ['busca' => $request->query('busca')];
}
}
Funciona da mesma forma em uma função anônima:
$app->get('/produtos', function (Request $request) {
return ['busca' => $request->query('busca')];
});
As três origens de dados
Os dados de uma requisição podem vir de três lugares diferentes, e cada um tem o seu método. Veja uma requisição completa:
requisição HTTP
PUT /produtos/10?notificar=sim HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
{"nome": "Chapéu de palha", "preco": 49.9}
Com a rota $app->put('/produtos/{id}', ...), cada pedaço é lido assim:
Pedaço
Onde está
Método
Resultado
Parâmetro de rota
Caminho: /produtos/10
param('id')
'10'
Query string
Depois do ?: notificar=sim
query('notificar')
'sim'
Corpo
JSON depois dos cabeçalhos
input('nome')
'Chapéu de palha'
Cabeçalho
Content-Type: ...
header('Content-Type')
'application/json'
Token
Authorization: Bearer ...
bearerToken()
'eyJhbGciOi...'
Quando usar cada um
Parâmetro de rota identifica qual recurso: /produtos/10. Query string filtra, busca, ordena e pagina, normalmente em GET: /produtos?busca=espada&pagina=2. Corpo traz os dados para criar ou alterar algo, em POST, PUT e PATCH.
Query string: query()
A query string é tudo o que vem depois do ? na URL, no formato chave=valor, separado por &.
$request->query(); // todos: ['busca' => 'espada', 'pagina' => '2']
$request->query('busca'); // um só: 'espada'
$request->query('ordem'); // não veio na URL: null
$request->query('pagina', 1); // com valor padrão: '2' (ou 1, se não vier)
Os valores chegam como texto
Tudo o que vem da URL é texto. pagina=2 chega como a string '2', não como o número 2. Converta antes de fazer contas ou comparações:
$pagina = (int) $request->query('pagina', 1);
$porPagina = min((int) $request->query('limite', 20), 100); // nunca mais que 100
$ativos = $request->query('ativos') === 'true';
Parâmetros de rota são os trechos entre chaves no caminho. Há duas formas de ler o valor.
Como argumento do método (recomendado)
Declare um argumento com o mesmo nome do parâmetro. Se você tipar o argumento, o Haki converte o valor:
$app->get('/produtos/{id}', [ProdutoController::class, 'show']);
public function show(int $id): array // '10' vira o número 10
{
return ['id' => $id];
}
Tipo do argumento
Aceita
Se o valor for inválido
int
10, -3
Responde 404
float
9.9, 10
Responde 404
bool
true, false, 1, 0
Responde 404
string ou sem tipo
Qualquer texto
(sempre aceita)
Com int $id, uma requisição para /produtos/abc recebe 404 antes mesmo de o seu código rodar.
Pelo Request
$request->param('id'); // '10' (sempre texto)
$request->param('slug', 'home'); // com valor padrão
$request->params(); // todos: ['id' => '10']
Corpo da requisição: input()
O corpo é onde o cliente envia os dados em POST, PUT e PATCH. O Haki entende dois formatos automaticamente:
JSON, quando o cabeçalho é Content-Type: application/json. É o formato usado por APIs, apps e fetch().
$request->input('nome'); // 'Nami'
$request->input('idade'); // 20 (no JSON, números chegam como número)
$request->input('endereco.cidade'); // 'Cocoyashi' (ponto acessa campos internos)
$request->input('tags'); // ['navegadora', 'cartógrafa']
$request->input('telefone'); // null (não foi enviado)
$request->input('telefone', '-'); // '-' (valor padrão)
$request->has('endereco.pais'); // true
$request->all(); // o corpo inteiro como array
$request->only(['nome', 'idade']); // ['nome' => 'Nami', 'idade' => 20]
$request->body(); // o corpo cru, como texto
Atenção
Use only() para pegar só os campos esperados. Passar all() direto para o banco permite que alguém envie campos extras, como "perfil": "admin", e altere o que não devia.
JSON inválido
Se o cliente enviar Content-Type: application/json com um corpo quebrado, a primeira leitura (input(), all(), has() ou only()) responde 400 com "JSON inválido no corpo da requisição". Você não precisa tratar isso.
$request->header('Accept'); // 'application/json'
$request->header('accept'); // o mesmo: o nome não diferencia maiúsculas
$request->header('X-Versao', '1'); // com valor padrão
$request->headers(); // todos, com nomes em minúsculas
$request->isJson(); // true se o Content-Type for JSON
$request->bearerToken(); // token de "Authorization: Bearer ..." ou null
Na maioria dos casos você não precisa de bearerToken(): o ->auth() lê e valida o token sozinho. Ele é útil para casos especiais, como validar o token manualmente com $auth->authenticate().
Informações da requisição
// GET /produtos/10?ordem=preco
$request->method(); // 'GET'
$request->path(); // '/produtos/10' (sem query string e sem barra final)
$request->uri(); // '/produtos/10?ordem=preco' (como chegou)
$request->ip(); // '127.0.0.1'
$request->user(); // usuário autenticado ou null (veja "Usuário autenticado")
Nota
ip() devolve o IP de quem se conectou ao servidor. Atrás de um proxy ou balanceador, esse é o IP do proxy, e o IP real do cliente costuma vir no cabeçalho X-Forwarded-For, que só é confiável se o seu proxy o define.
Todos os métodos
Método
Retorna
query($nome = null, $padrao = null)
Valor da query string; sem argumentos, todos (array)
param($nome, $padrao = null)
Parâmetro da rota, sempre texto
params()
Todos os parâmetros da rota
input($nome, $padrao = null)
Campo do corpo (JSON ou formulário); aceita 'a.b.c'
has($nome)
true se o campo existe no corpo (mesmo que seja null)
all()
Corpo inteiro como array
only([...])
Só os campos informados
body()
Corpo cru, como texto
validate($regras, $nomes = [])
Valida os dados e devolve só os campos validados (veja Validação)
Tudo o que vem da requisição deve ser tratado como não confiável. Em vez de conferir campo por campo com if, descreva as regras e deixe o Haki validar e converter os tipos:
Veja tudo sobre isso na página Validação, incluindo as classes de validação.
Criando requisições em testes
Request::create() monta uma requisição sem servidor, para usar com $app->handle():
use Haki\Http\Request;
Request::create('GET', '/produtos?busca=espada'); // com query string
Request::create('POST', '/clientes', ['nome' => 'Nami']); // corpo JSON
Request::create('GET', '/eu', [], ['Authorization' => 'Bearer ...']); // com cabeçalhos
Em produção, o $app->run() monta a requisição real a partir das variáveis do PHP (Request::capture()). Você não precisa chamar isso.
Validação
Regras com $rule, classes de validação e respostas 422 em português.
Visão geral
Validar é conferir se os dados enviados pelo cliente estão certos antes de usá-los. No Haki, você descreve cada campo com $rule, e o framework confere, converte os tipos e responde com mensagens em português quando algo está errado.
'nome' => $rule->text()->length(3, 100), // texto de 3 a 100 caracteres
'email' => $rule->email(), // e-mail válido
'idade' => $rule->integer()->min(18)->optional(), // inteiro, 18 ou mais, pode faltar
Há duas formas de validar:
Classe de validação (FormRequest): o jeito recomendado. Deixa o controller limpo e a regra reaproveitável.
$request->validate(): um atalho para casos rápidos, direto no controller.
O arquivo é criado em app/Requests/CriarClienteRequest.php.
Descreva os campos em rules()
app/Requests/CriarClienteRequest.php
<?php
declare(strict_types=1);
namespace App\Requests;
use Haki\Validation\FormRequest;
use Haki\Validation\Rule;
final class CriarClienteRequest extends FormRequest
{
public function rules(Rule $rule): array
{
return [
'nome' => $rule->text()->length(3, 100),
'email' => $rule->email(),
'idade' => $rule->integer()->min(18)->optional(),
'endereco' => [
'cidade' => $rule->text(),
'cep' => $rule->text()->pattern('/^\d{5}-?\d{3}$/'),
],
'tags' => $rule->list($rule->oneOf('vip', 'novo')),
];
}
}
Peça a classe no controller
app/Controllers/ClienteController.php
use App\Requests\CriarClienteRequest;
public function store(CriarClienteRequest $request, Response $response): Response
{
$cliente = $this->clientes->criar($request->validated());
return $response->json(['cliente' => $cliente], 201);
}
Pronto. O Haki valida antes do controller rodar. Se algo estiver errado, o controller nem é chamado.
O que o cliente recebe
Com dados inválidos, a resposta é 422, com as mensagens separadas por campo:
{
"erro": "Dados inválidos",
"status": 422,
"campos": {
"nome": ["O campo nome precisa ter entre 3 e 100 caracteres."],
"email": ["O campo email precisa ser um e-mail válido."],
"endereco.cep": ["O campo cep está em um formato inválido."],
"tags.1": ["O item 2 de tags precisa ser um destes: vip, novo."]
}
}
Campos dentro de objetos usam ponto (endereco.cep), e itens de lista usam a posição, começando em zero (tags.1 é o segundo item). No front-end, mostre cada mensagem embaixo do campo correspondente.
Usando os dados validados
$request->nome; // 'Nami' (acesso direto)
$request->get('endereco.cidade'); // 'Cocoyashi' (notação de ponto)
$request->get('telefone', '-'); // com valor padrão
$request->only(['nome', 'email']); // só alguns campos
$request->validated(); // todos os campos validados
$request->user(); // usuário autenticado
$request->request(); // a requisição original (cabeçalhos, IP, parâmetros de rota...)
Os valores já chegam convertidos
Diferente de $request->input(), que entrega o que o cliente mandou, os dados validados vêm no tipo certo:
Regra
Cliente enviou
Você recebe
text()
" Nami "
'Nami' (sem espaços nas pontas)
integer()
"20"
20
number()
"9.9"
9.9
boolean()
"sim", "1", "on"
true
date()
"2026-12-31"
DateTimeImmutable
enum(Plano::class)
"pro"
Plano::Pro
Proteção automática
validated() só traz os campos declarados em rules(). Se alguém enviar "perfil": "admin" sem que esse campo exista nas regras, ele é ignorado. Por isso é seguro passar validated() direto para o banco.
Obrigatório e opcional
Todo campo é obrigatório. Você só escreve a exceção, com optional():
'apelido' => $rule->text()->optional(), // se faltar: fica fora de validated()
'pagina' => $rule->integer()->optional(1), // se faltar: 1
'ativo' => $rule->boolean()->optional(true), // se faltar: true
'bio' => $rule->text()->optional(null), // se faltar: null
Campo que não veio e não tem padrão declarado fica fora de validated(). É o que permite $modelo->atualizar($request->validated()) numa edição parcial: o que o cliente não mandou não é sobrescrito. Com padrão declarado — inclusive optional(null) — a chave sempre aparece.
Já um campo enviado vazio ("", só espaços ou null) aparece em validated() com o padrão, para o cliente poder limpar um valor de propósito.
Mudança de comportamento
Até a 1.9, todo campo optional() aparecia em validated() com o padrão, mesmo ausente. Se o seu código lê $request->campo de um campo opcional, troque por $request->get('campo'), que aceita um valor padrão, ou declare o padrão na regra com optional(null).
required(): campo que não pode ficar vazio
Todo campo já é obrigatório por padrão. O required() deixa isso explícito no código e permite trocar a mensagem de erro:
'nome' => $rule->text()->required(),
'email' => $rule->email()->required('Informe um e-mail para contato.'),
Com "nome": " ", a resposta é O campo nome é obrigatório.. Com a mensagem própria, o texto informado é usado como está, sem o nome do campo na frente.
required ou optional?
Chamar required() depois de optional() torna o campo obrigatório de novo, e o padrão é descartado. Os dois métodos se anulam: vale o último que você escrever.
Todos aceitam o valor com ou sem máscara e entregam a versão limpa, pronta para salvar no banco:
Regra
Aceita
Você recebe
$rule->cep()
12345-678, 12345678
'12345678'
$rule->cpf()
529.982.247-25, 52998224725
'52998224725'
$rule->cnpj()
11.222.333/0001-81 e o novo alfanumérico 12.ABC.345/01DE-35
'11222333000181'
$rule->cpfOrCnpj()
CPF ou CNPJ (campo "documento")
Só os caracteres, sem máscara
$rule->phone()
Fixo ou celular com DDD: (11) 3456-7890, (11) 98765-4321, +55 11 98765-4321
'1134567890', '11987654321'
$rule->mobile()
Só celular com DDD: (11) 98765-4321
'11987654321'
$rule->plate()
Placa antiga ABC-1234 ou Mercosul abc-1d23
'ABC1D23'
$rule->uf()
Sigla de estado: sp, RJ
'SP'
$rule->time()
Horário: 9:05, 18:30
'09:05'
$rule->slug()
meu-produto-2
'meu-produto-2'
$rule->hexColor()
#FF8800, #f80
'#ff8800'
Mais que uma expressão regular
cpf() e cnpj() conferem os dígitos verificadores: 529.982.247-24 tem o formato certo, mas é recusado porque o último dígito não confere. Sequências repetidas, como 111.111.111-11, também são recusadas. O cnpj() já aceita o CNPJ alfanumérico adotado pela Receita Federal.
As mensagens de erro dizem o que se espera:
"campos": {
"cpf": ["O campo cpf precisa ser um CPF válido."],
"cep": ["O campo cep precisa ser um CEP válido (ex.: 12345-678)."],
"celular": ["O campo celular precisa ser um celular válido com DDD (ex.: (11) 98765-4321)."]
}
Os formatos podem ser combinados com as outras restrições, como optional(), check() e message():
'documento' => $rule->cpfOrCnpj()->message('Informe um CPF ou CNPJ válido.'),
'whatsapp' => $rule->mobile()->optional(),
Usando os formatos fora da validação
A classe Formats faz a mesma conferência em qualquer lugar do código. Ela devolve o valor limpo, ou null se for inválido:
use Haki\Validation\Formats;
Formats::cpf('529.982.247-25'); // '52998224725'
Formats::cpf('111.111.111-11'); // null
Formats::phone('+55 11 98765-4321'); // '11987654321'
Formats::uf('mg'); // 'MG'
Formats::UFS; // lista com as 27 siglas
Restrições
Encadeie depois do tipo, na ordem que preferir:
Método
Para
Exemplo
length($min, $max)
Quantidade de caracteres (textos) ou de itens (listas)
length(3, 100), length(3), length(max: 100)
required($mensagem)
Campo não pode ser vazio (opcional, troca a mensagem de erro)
text()->required()
min($valor)
Menor valor: só integer() e number()
integer()->min(18), number()->min(0.01)
max($valor)
Maior valor: só integer() e number()
integer()->max(100), number()->max(9.99)
between($min, $max)
Faixa de valores: só integer() e number()
integer()->between(1, 5)
oneOf(...)
Lista de valores aceitos
$rule->text()->oneOf('P', 'M', 'G')
pattern($regex, $mensagem)
Formato por expressão regular
pattern('/^\d{5}-?\d{3}$/')
same('campo')
Igual a outro campo do mesmo nível
same('senha')
check($funcao, $mensagem)
Regra própria
veja abaixo
optional($padrao)
Campo pode faltar. Sem padrão declarado, o campo ausente fica fora de validated()
optional(), optional(1)
message($mensagem)
Uma mensagem única para o campo
message('Escolha um apelido')
Números: mínimo, máximo e faixa
min(), max() e between() valem para integer() (inteiros) e number() (inteiros ou decimais). Os limites são inclusivos: min(18) aceita 18.
{
"erro": "Dados inválidos",
"status": 422,
"campos": {
"idade": ["O campo idade pode ser no máximo 65."],
"quantidade": ["O campo quantidade precisa ser no mínimo 1."],
"preco": ["O campo preco precisa ser no mínimo 0,01."]
}
}
Com decimais, o Haki mostra o limite no formato brasileiro (0,01).
Erro ao montar a regra
Dois casos geram erro logo ao declarar a regra, antes de qualquer requisição: usar min(), max() ou between() em text() (use length()), e um mínimo maior que o máximo, como min(10)->max(5).
length ou min?
length conta tamanho (letras de um texto, itens de uma lista). min e max comparam o valor de um número. Uma senha de pelo menos 8 caracteres é text()->length(8); uma idade de pelo menos 18 anos é integer()->min(18).
Objetos e listas
Objetos (um grupo de campos dentro de outro)
Use quando o cliente envia um objeto dentro de outro no JSON. A regra simplesmente copia o formato do JSON que chega. Imagine que o front-end envia este cadastro:
Use o array interno só quando o JSON também tiver um objeto interno. Os dois formatos funcionam; escolha o que combina com o que o seu front-end envia.
Objeto opcional
Um array dentro das regras é sempre obrigatório. Para um objeto que pode faltar, use $rule->object() com optional():
'endereco' => $rule->object([
'rua' => $rule->text(),
'numero' => $rule->integer(),
'cidade' => $rule->text(),
])->optional(), // se não vier, endereco fica fora de validated()
Listas
// Lista de textos, de 1 a 5 itens
'tags' => $rule->list($rule->text())->length(1, 5),
// Lista de objetos (itens de um pedido)
'itens' => $rule->list([
'produto_id' => $rule->integer(),
'quantidade' => $rule->integer()->min(1),
])->length(1),
Mensagens e nomes dos campos
As mensagens usam o nome do campo. Para trocar por um nome mais amigável, defina labels():
public function labels(): array
{
return [
'email' => 'e-mail',
'endereco.cep' => 'CEP',
];
}
// "O campo e-mail precisa ser um e-mail válido."
Para trocar a mensagem inteira de uma regra, use o segundo argumento de pattern() e check(), ou message() para o campo todo:
'cep' => $rule->text()->pattern('/^\d{5}-?\d{3}$/', 'Informe um CEP como 12345-678.'),
'apelido' => $rule->text()->length(3, 20)->message('O apelido precisa ter de 3 a 20 letras.'),
Preparando os dados: prepare()
prepare() roda antes da validação. Use para limpar os dados, como tirar a máscara de um CPF:
Para regras que dependem do banco ou de vários campos, sobrescreva check(). Ele roda depois que todas as regras de rules() passaram e recebe os dados validados. Use $this->fail() para marcar um erro. A classe recebe dependências pelo construtor, como um controller:
final class CriarClienteRequest extends FormRequest
{
public function __construct(private readonly ClienteRepositoryInterface $clientes)
{
}
public function rules(Rule $rule): array
{
return [
'email' => $rule->email(),
'data_inicio' => $rule->date(),
'data_fim' => $rule->date(),
];
}
protected function check(array $data): void
{
if ($this->clientes->emailExiste($data['email'])) {
$this->fail('email', 'Este e-mail já está cadastrado.');
}
if ($data['data_fim'] < $data['data_inicio']) {
$this->fail('data_fim', 'A data final precisa ser depois da inicial.');
}
}
}
O comportamento é o mesmo: resposta 422 automática e dados convertidos. O segundo argumento opcional define os nomes amigáveis: $request->validate(..., ['email' => 'e-mail']).
Validando a query string
As regras valem para a query string e para o corpo juntos (se o mesmo campo vier nos dois, vale o do corpo). Assim, a mesma técnica serve para filtros de listagem:
// GET /produtos?busca=espada&pagina=2
public function rules(Rule $rule): array
{
return [
'busca' => $rule->text()->length(2)->optional(),
'pagina' => $rule->integer()->min(1)->optional(1),
'ordem' => $rule->oneOf('nome', 'preco')->optional('nome'),
];
}
Em que momento a validação roda
Middlewares, autenticação (->auth()) e perfil (->role()).
prepare() ajusta os dados.
As regras de rules() são aplicadas.
Se passaram, check() roda.
Se tudo deu certo, o controller é chamado.
Por isso uma requisição sem token recebe 401, e não 422: a autenticação vem antes.
Banco de dados
Conexão, model, interface e repository com PDO, do jeito certo.
Como o Haki trabalha com banco
O Haki não impõe um ORM. Você usa o PDO, que já vem no PHP, organizado em quatro peças, cada uma com uma responsabilidade. Se preferir um ORM pronto, o EloPHP é opcional e convive com este modelo.
Peça
Onde
Responsabilidade
Conexão
app/Database/Connection.php
Lê o .env e abre a conexão
Model
app/Models/
Representa um registro (um produto, um cliente)
Interface
app/Contracts/
Diz o que dá para fazer com os registros
Repository
app/Repositories/
Faz o SQL de verdade
Controller ──▶ ProdutoRepositoryInterface ──▶ PdoProdutoRepository ──▶ Connection ──▶ banco
│
└──▶ new Produto(...) (cada linha vira um objeto)
O controller nunca escreve SQL: ele pede a interface e recebe models prontas. Assim, todo o SQL fica num lugar só, e trocar de banco ou testar sem banco não exige mexer no controller.
1. Configurando o .env
.env (SQLite: um arquivo, não precisa de servidor)
Para começar e aprender, use SQLite. Para MySQL, ative a extensão pdo_mysql no php.ini.
2. A classe de conexão
Uma classe pequena que lê as variáveis DB_* e entrega o PDO. A conexão só é aberta na primeira vez que alguém precisa dela:
app/Database/Connection.php
<?php
declare(strict_types=1);
namespace App\Database;
use Haki\Support\Env;
use PDO;
use RuntimeException;
final class Connection
{
private ?PDO $pdo = null;
public function __construct(
private readonly string $driver,
private readonly string $database,
private readonly string $host = '127.0.0.1',
private readonly int $port = 3306,
private readonly ?string $username = null,
#[\SensitiveParameter] private readonly ?string $password = null,
) {
}
public static function fromEnv(string $basePath): self
{
$driver = (string) Env::get('DB_CONNECTION', 'sqlite');
$database = (string) Env::get('DB_DATABASE', 'database/app.sqlite');
// No SQLite, um caminho relativo é a partir da raiz do projeto.
if ($driver === 'sqlite' && !preg_match('#^([A-Za-z]:[\\\\/]|/)#', $database)) {
$database = rtrim($basePath, '/\\') . DIRECTORY_SEPARATOR . $database;
}
return new self(
$driver,
$database,
(string) Env::get('DB_HOST', '127.0.0.1'),
(int) Env::get('DB_PORT', 3306),
Env::get('DB_USERNAME'),
Env::get('DB_PASSWORD'),
);
}
public function pdo(): PDO
{
return $this->pdo ??= $this->connect();
}
private function connect(): PDO
{
$options = [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, // erro de SQL vira exceção
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC, // linhas como array associativo
];
return match ($this->driver) {
'sqlite' => new PDO('sqlite:' . $this->database, null, null, $options),
'mysql' => new PDO(
"mysql:host={$this->host};port={$this->port};dbname={$this->database};charset=utf8mb4",
$this->username,
$this->password,
$options,
),
default => throw new RuntimeException("DB_CONNECTION \"{$this->driver}\" não suportado. Use sqlite ou mysql."),
};
}
}
Registre como singleton no bootstrap, para todos os repositories usarem a mesma conexão:
bootstrap/app.php
use App\Database\Connection;
$app->container()->singleton(Connection::class, function () use ($app) {
return Connection::fromEnv($app->basePath());
});
Testando a conexão
php vendor/bin/haki db
✔ Conectado ao banco.
Driver: sqlite
Banco: C:\projetos\loja\database\app.sqlite
Versão: SQLite 3.45.1
Tabelas: produtos
Tempo: 0.5 ms
Se falhar, a mensagem diz o motivo. Veja o comando db.
3. Criando as tabelas
Guarde a estrutura do banco num arquivo SQL, versionado junto com o código:
database/schema.sql
CREATE TABLE IF NOT EXISTS produtos (
id INTEGER PRIMARY KEY AUTOINCREMENT,
nome TEXT NOT NULL,
preco REAL NOT NULL,
estoque INTEGER NOT NULL DEFAULT 0
);
E um script curto que aplica esse arquivo, usando a mesma conexão da aplicação:
Quando a estrutura mudar (uma coluna nova, por exemplo), crie arquivos numerados (002_adicionar_categoria.sql...) em vez de editar o antigo, para saber o que já foi aplicado em cada ambiente. Para projetos maiores, ferramentas como o Phinx fazem esse controle automaticamente.
4. A model
A model representa um registro. Ela só guarda os dados, com o tipo certo de cada coluna:
app/Models/Produto.php
<?php
declare(strict_types=1);
namespace App\Models;
final class Produto
{
public function __construct(
public readonly int $id,
public readonly string $nome,
public readonly float $preco,
public readonly int $estoque,
) {
}
}
readonly: depois de criado, o objeto não muda por acidente.
Uma coluna que aceita NULL vira uma propriedade com ?: public readonly ?string $telefone.
Retornada no controller, a model vira JSON com as propriedades públicas. Se ela tiver um campo que não pode aparecer (como o hash da senha), implemente JsonSerializable. Veja Respostas.
5. A interface
Lista o que dá para fazer com os registros, sem dizer como:
app/Contracts/ProdutoRepositoryInterface.php
<?php
declare(strict_types=1);
namespace App\Contracts;
use App\Models\Produto;
interface ProdutoRepositoryInterface
{
/** @return list<Produto> */
public function listar(int $pagina, int $porPagina): array;
public function buscar(int $id): ?Produto;
public function criar(string $nome, float $preco, int $estoque): Produto;
public function atualizar(int $id, string $nome, float $preco, int $estoque): void;
public function apagar(int $id): bool;
}
6. O repository: onde fica o SQL
O nome PdoProdutoRepository segue o padrão do discover(), então o Haki o liga à interface sem nenhum bind:
app/Repositories/PdoProdutoRepository.php
<?php
declare(strict_types=1);
namespace App\Repositories;
use App\Contracts\ProdutoRepositoryInterface;
use App\Database\Connection;
use App\Models\Produto;
use PDO;
final class PdoProdutoRepository implements ProdutoRepositoryInterface
{
private readonly PDO $pdo;
public function __construct(Connection $connection)
{
$this->pdo = $connection->pdo();
}
public function listar(int $pagina, int $porPagina): array
{
$stmt = $this->pdo->prepare('SELECT * FROM produtos ORDER BY id LIMIT :limite OFFSET :inicio');
$stmt->bindValue(':limite', $porPagina, PDO::PARAM_INT);
$stmt->bindValue(':inicio', ($pagina - 1) * $porPagina, PDO::PARAM_INT);
$stmt->execute();
$produtos = [];
foreach ($stmt->fetchAll() as $linha) {
$produtos[] = new Produto((int) $linha['id'], $linha['nome'], (float) $linha['preco'], (int) $linha['estoque']);
}
return $produtos;
}
public function buscar(int $id): ?Produto
{
$stmt = $this->pdo->prepare('SELECT * FROM produtos WHERE id = ?');
$stmt->execute([$id]);
$linha = $stmt->fetch();
if (!$linha) {
return null;
}
return new Produto((int) $linha['id'], $linha['nome'], (float) $linha['preco'], (int) $linha['estoque']);
}
public function criar(string $nome, float $preco, int $estoque): Produto
{
$stmt = $this->pdo->prepare('INSERT INTO produtos (nome, preco, estoque) VALUES (?, ?, ?)');
$stmt->execute([$nome, $preco, $estoque]);
return new Produto((int) $this->pdo->lastInsertId(), $nome, $preco, $estoque);
}
public function atualizar(int $id, string $nome, float $preco, int $estoque): void
{
$stmt = $this->pdo->prepare('UPDATE produtos SET nome = ?, preco = ?, estoque = ? WHERE id = ?');
$stmt->execute([$nome, $preco, $estoque, $id]);
}
public function apagar(int $id): bool
{
$stmt = $this->pdo->prepare('DELETE FROM produtos WHERE id = ?');
$stmt->execute([$id]);
return $stmt->rowCount() > 0;
}
}
Os comandos do PDO que você vai usar
Código
Faz
$pdo->prepare('... WHERE id = ?')
Prepara o SQL com lugares (?) para os valores
$stmt->execute([$id])
Roda, preenchendo os ? na ordem
$stmt->fetch()
Uma linha (array), ou false se não houver
$stmt->fetchAll()
Todas as linhas
$stmt->fetchColumn()
Um valor só (ex.: SELECT COUNT(*))
$stmt->rowCount()
Quantas linhas um UPDATE/DELETE afetou
$pdo->lastInsertId()
O id gerado pelo último INSERT
$stmt->bindValue(':limite', 20, PDO::PARAM_INT)
Preenche um parâmetro com nome, informando o tipo
Nunca coloque valores direto no SQL
Esta é a regra mais importante desta página. Colocar uma variável dentro do texto do SQL permite que alguém mande um "valor" que é, na verdade, outro comando. Isso se chama SQL injection:
// ERRADO: se $busca for ' OR 1=1 -- a consulta devolve tudo; com outros textos, pode apagar dados
$pdo->query("SELECT * FROM produtos WHERE nome = '$busca'");
// CERTO: o valor vai separado do SQL e nunca é interpretado como comando
$stmt = $pdo->prepare('SELECT * FROM produtos WHERE nome = ?');
$stmt->execute([$busca]);
Use sempre prepare() com ? (ou :nome) para qualquer valor que venha de fora. A única exceção são partes fixas que você mesmo escreveu, como o nome de uma coluna escolhida de uma lista permitida:
$ordem = in_array($request->query('ordem'), ['nome', 'preco'], true) ? $request->query('ordem') : 'id';
$stmt = $pdo->prepare("SELECT * FROM produtos ORDER BY $ordem"); // seguro: só valores da lista
Paginação
Nunca devolva uma tabela inteira: com milhares de linhas, a API fica lenta. Use LIMIT e OFFSET:
página 1, 20 por página → LIMIT 20 OFFSET 0
página 2, 20 por página → LIMIT 20 OFFSET 20
página 3, 20 por página → LIMIT 20 OFFSET 40
Como no listar() acima, passe LIMIT e OFFSET com bindValue(..., PDO::PARAM_INT). Se forem como texto, o MySQL recusa a consulta.
Transações: tudo ou nada
Quando várias gravações dependem umas das outras (criar um pedido e os itens dele), use uma transação. Se qualquer uma falhar, nada é gravado:
public function criarPedido(int $clienteId, array $itens): int
{
$this->pdo->beginTransaction();
try {
$this->pdo->prepare('INSERT INTO pedidos (cliente_id) VALUES (?)')->execute([$clienteId]);
$pedidoId = (int) $this->pdo->lastInsertId();
$item = $this->pdo->prepare('INSERT INTO itens (pedido_id, produto_id, quantidade) VALUES (?, ?, ?)');
foreach ($itens as $i) {
$item->execute([$pedidoId, $i['produto_id'], $i['quantidade']]);
}
$this->pdo->commit(); // grava tudo
return $pedidoId;
} catch (Throwable $e) {
$this->pdo->rollBack(); // desfaz tudo
throw $e;
}
}
7. Usando no controller
O controller pede a interface e não sabe nada de SQL:
app/Controllers/ProdutoController.php
final class ProdutoController
{
public function __construct(private readonly ProdutoRepositoryInterface $produtos)
{
}
public function show(int $id): array
{
$produto = $this->produtos->buscar($id);
if ($produto === null) {
throw new HttpException(404, 'Produto não encontrado');
}
return ['produto' => $produto];
}
public function store(ProdutoRequest $request, Response $response): Response
{
$produto = $this->produtos->criar($request->nome, $request->preco, $request->estoque);
return $response->json(['produto' => $produto], 201);
}
}
Depois de criar as peças, confira se está tudo ligado:
php vendor/bin/haki check
O Exemplo completo monta uma API inteira com banco seguindo exatamente esta página.
Erros comuns
Mensagem
Causa e solução
"could not find driver"
A extensão pdo_sqlite ou pdo_mysql está desativada. Ative no php.ini.
"no such table: produtos"
A tabela não foi criada, ou o DB_DATABASE aponta para outro arquivo. Rode php database/criar.php e confira com php vendor/bin/haki db.
"Access denied for user"
Usuário ou senha do MySQL errados no .env.
"Unknown database"
O banco não existe no MySQL. Crie com CREATE DATABASE loja;.
"UNIQUE constraint failed" / "Duplicate entry"
Tentou gravar um valor repetido numa coluna única (como e-mail). Confira antes, de preferência na validação (veja check() na classe).
Syntax error perto de '20' no LIMIT (MySQL)
O valor foi como texto. Use bindValue(..., PDO::PARAM_INT).
Do banco ao controller
Um exemplo completo: a migração, o model, a rota e o controller de um recurso "produtos".
O caminho de uma requisição
Uma funcionalidade nova passa por cinco arquivos, nesta ordem. Cada um tem uma única responsabilidade.
Passo
Arquivo
Responsabilidade
1
database/migracoes/...criar_produtos.php
Cria a tabela no banco
2
app/Models/Produto.php
Representa um registro e fala com a tabela
3
app/Services/ProdutoService.php
Regra de negócio (opcional em casos simples)
4
app/Controllers/ProdutoController.php
Recebe a requisição e devolve o resultado
5
routes/api.php
Liga a URL ao controller
Nota
Os exemplos de migração e de model usam o EloPHP, o ORM opcional do Haki. Se você preferir PDO puro, o fluxo é o mesmo: a tabela, uma classe que acessa o banco, e o controller.
1. A migração
Crie o arquivo na pasta database/migracoes/. O prefixo de data define a ordem em que as migrações rodam, então use a data de criação no início do nome.
<?php
use Elo\Coluna;
use Elo\Migracao;
use Elo\Tabela;
return new class extends Migracao
{
public function subir(): void
{
Tabela::criar('produtos', [
'nome' => Coluna::texto(120),
'preco' => Coluna::decimal(10, 2)->padrao(0),
'status' => Coluna::opcoes(['ATIVO', 'INATIVO'])->padrao('ATIVO'),
], ['exclusao_logica' => true]);
}
public function descer(): void
{
Tabela::apagar('produtos');
}
};
A tabela já nasce com id, criado_em, atualizado_em e, por causa de exclusao_logica, excluido_em.
Para criar a tabela no banco:
Terminal
php vendor/bin/elo migrar
Se algo der errado, php vendor/bin/elo migrar:reverter desfaz o último lote. Para ver o que já foi aplicado, use php vendor/bin/elo migrar:status.
2. O model
O model descreve o registro. Como o nome da tabela é produtos, não precisa declarar nada além da exclusão lógica:
app/Models/Produto.php
<?php
namespace App\Models;
use Elo\Modelo;
class Produto extends Modelo
{
protected bool $exclusaoLogica = true;
}
Com o model pronto, já dá para usar sem escrever SQL:
$produto = Produto::criar(['nome' => 'Espada', 'preco' => 150]); // INSERT
$produto = Produto::buscar(1); // SELECT pela chave, ou null
$produtos = Produto::onde('status', 'ATIVO')->ordenarPor('nome')->obter();
$produto->preco = 120;
$produto->salvar(); // UPDATE só de preco e atualizado_em
$produto->excluir(); // grava excluido_em
3. O service (opcional)
Se a regra for só "listar" ou "criar", o controller pode usar o model direto. Quando houver regra de negócio, ela fica no service, e não no controller:
app/Services/ProdutoService.php
<?php
namespace App\Services;
use App\Models\Produto;
final class ProdutoService
{
public function listarAtivos(): array
{
return Produto::onde('status', 'ATIVO')->ordenarPor('nome')->paginar(20, 1)->dados;
}
public function cadastrar(string $nome, float $preco): Produto
{
if ($preco < 0) {
throw new \InvalidArgumentException('O preço não pode ser negativo.');
}
return Produto::criar(['nome' => $nome, 'preco' => $preco]);
}
}
4. O controller
O controller recebe o service pelo construtor (o Haki injeta automaticamente) e só conecta as peças. Ele devolve um array, e o Haki transforma em JSON:
app/Controllers/ProdutoController.php
<?php
namespace App\Controllers;
use App\Services\ProdutoService;
use Haki\Http\Request;
use Haki\Http\Response;
final class ProdutoController
{
public function __construct(private ProdutoService $produtos)
{
}
public function index(): array
{
return ['produtos' => $this->produtos->listarAtivos()];
}
public function store(Request $request): Response
{
$produto = $this->produtos->cadastrar(
(string) $request->input('nome'),
(float) $request->input('preco'),
);
return (new Response())->json(['produto' => $produto], 201);
}
}
Dica
Para validar a entrada antes do controller, crie uma classe de validação e receba-a como parâmetro do método, no lugar do Request.
5. A rota
Por último, ligue as URLs ao controller em routes/api.php:
php vendor/bin/haki check # confere controllers e dependências
php -S localhost:8000 -t public
curl -X POST localhost:8000/produtos -H "Content-Type: application/json" -d '{"nome":"Espada","preco":150}'
curl localhost:8000/produtos
O haki check avisa antes de publicar se algum controller não consegue ser montado, por exemplo por causa de uma dependência sem tipo.
EloPHP: ORM opcional
Um ORM simples, com models, migrações e relacionamentos declarados em arrays.
O que é
O EloPHP é um ORM (Active Record) que já vem no Haki. Ele é opcional. Você pode usar PDO puro, como descrito em Banco de dados, ou um ORM só nos models que quiser. Nada do que está nas outras páginas depende dele.
<?php
use Elo\Coluna;
use Elo\Migracao;
use Elo\Tabela;
return new class extends Migracao
{
public function subir(): void
{
Tabela::criar('setores', [
'nome' => Coluna::texto(100),
'sigla' => Coluna::texto(15)->unico(),
]);
}
public function descer(): void
{
Tabela::apagar('setores');
}
};
app/Models/Setor.php
<?php
namespace App\Models;
use Elo\Modelo;
class Setor extends Modelo
{
protected array $temMuitos = [
'usuarios' => Usuario::class,
];
}
Uso
$setor = Setor::criar(['nome' => 'Núcleo de Apoio', 'sigla' => 'NAT']);
$setor->usuarios; // lista de usuários do setor
Setor::buscarPor('sigla', 'NAT'); // o setor, ou null
Diferenciais
Sem closures. Migrações e models são arrays e classes. Não existe function (Blueprint $table) { ... }.
Sem repetição. Relações são linhas em um array. Não é preciso escrever um método para cada uma, nem uma lista de colunas liberadas.
Nomes em português.criar, buscar, onde, ordenarPor, anexar, sincronizar. O nome da tabela é pluralizado pelas regras do português: Usuario vira usuarios.
Quatro bancos. MySQL/MariaDB, PostgreSQL, SQL Server e SQLite, com o mesmo código.
Seguro por padrão. Todo valor vai como parâmetro do PDO. Nomes de tabela e coluna são validados.
Comparação com outros ORMs
Assunto
Eloquent / Doctrine
EloPHP
Migração
Closure com $table->... repetido
Array 'coluna' => Coluna::...
Preenchimento em massa
Lista $fillable ou $guarded
Tudo liberado; só a chave primária é protegida
Relação
Método que retorna hasMany(...)
Uma linha no array $temMuitos
Nome da tabela
Plural pelas regras do inglês
Plural pelas regras do português
Configuração
Como o EloPHP descobre o banco e como trocar de banco.
Pelo .env
O EloPHP usa as mesmas variáveis DB_* do Haki. Se o .env já está certo para o PDO, o EloPHP funciona sem mais nada.
Opção 2: com um PDO que você já criou (útil em testes)
use Elo\Conexao;
Conexao::configurar(new PDO('sqlite::memory:'));
Caminhos relativos
Um caminho relativo de SQLite (como database/app.sqlite) é resolvido a partir da pasta do projeto. Se o PHP não estiver rodando na raiz (por exemplo, dentro de public/), informe a raiz com Conexao::raizDoProjeto(__DIR__ . '/..').
Comando elo
O comando elo lê só o .env. Uma conexão feita em bootstrap/app.php não vale para ele. Para as migrações, deixe a configuração no .env.
Os quatro bancos
DB_CONNECTION
Banco
Extensão PHP
O que o EloPHP trata por você
sqlite
SQLite
pdo_sqlite
Liga as chaves estrangeiras (PRAGMA foreign_keys), para o ON DELETE funcionar
mysql
MySQL / MariaDB
pdo_mysql
Crases, ENUM nativo e UNSIGNED
pgsql
PostgreSQL
pdo_pgsql
Aspas duplas, RETURNING para pegar o id e BOOLEAN
sqlsrv
SQL Server
pdo_sqlsrv
Colchetes, OFFSET/FETCH, OUTPUT para pegar o id e NVARCHAR
Trocar de banco é trocar o .env. Os models e as migrações não mudam, porque cada banco tem sua tradução (a gramática) dentro do EloPHP.
Erros comuns
Mensagem
O que fazer
Nenhum banco configurado
Defina DB_CONNECTION no .env ou use Conexao::configurar().
DB_CONNECTION não é suportado
Use sqlite, mysql, pgsql ou sqlsrv.
Driver de banco não suportado
Ative a extensão pdo_* correspondente no php.ini.
Migrações
Como criar, nomear, escrever, aplicar e desfazer as tabelas do banco.
O que é uma migração
Uma migração é um arquivo PHP que descreve uma mudança no banco. Ela tem duas partes: subir() aplica a mudança, e descer() desfaz. Como os arquivos rodam sempre na mesma ordem, o banco de cada pessoa do time (e de produção) chega ao mesmo estado.
1. A pasta e o nome
Os arquivos ficam em database/migracoes/, na raiz do projeto (a pasta que contém o vendor/). A pasta não é criada sozinha: crie-a antes da primeira migração.
Os arquivos rodam em ordem alfabética. Por isso, o nome começa com a data e um número:
Data e número (2026_01_10_000001): a ordem. Se criar mais de uma no mesmo dia, aumente o número.
Ação (criar_usuarios): o que a migração faz, em minúsculas.
Não renomeie uma migração aplicada
O banco guarda o nome de cada migração que já rodou. Renomear um arquivo faz o EloPHP tratá-lo como novo. Para mudar uma tabela que já existe, crie outra migração.
2. Escrevendo o arquivo
O arquivo retorna um objeto: uma classe anônima que estende Elo\Migracao. Ela não tem nome, porque o EloPHP usa o objeto que o arquivo devolve.
padrao() aceita textos, números e booleanos. padraoAtual() usa a data e hora do momento do insert. unico() e indice() criam, respectivamente, uma restrição de unicidade e um índice.
Chave estrangeira
Coluna::pertenceA('setores') aponta para setores.id. Para outra coluna, passe o segundo parâmetro: Coluna::pertenceA('setores', 'codigo').
aoExcluir() e aoAtualizar() aceitam CASCADE, SET NULL, RESTRICT e NO ACTION. Outro valor gera erro antes de chegar ao banco.
Ordem
A tabela referenciada precisa existir antes. Por isso, setores tem um número menor que usuarios.
Alterar e apagar
Tabela::alterar('usuarios', [
'telefone' => Coluna::texto(20)->nulo(), // adiciona a coluna
'cpf' => Coluna::remover(), // remove a coluna
]);
Tabela::apagar('usuarios'); // DROP TABLE IF EXISTS
Tabela::existe('usuarios'); // true ou false
Limite do SQLite
O SQLite não aceita UNIQUE nem chave estrangeira em ALTER TABLE. O EloPHP avisa com uma mensagem clara. Nesse caso, recrie a tabela.
Tabela pivô
A tabela que liga dois models em muitos-para-muitos (veja Relacionamentos) não precisa de id nem de datas:
Lista as migrações e mostra quais já foram aplicadas
php vendor/bin/elo migrar:reverter
Desfaz o último lote, na ordem inversa
Na primeira execução, o EloPHP cria sozinho a tabela migracoes, que guarda o nome e o lote de cada migração aplicada. Não crie essa tabela na mão.
Lotes
Tudo o que um migrar aplica recebe o mesmo número de lote. migrar:reverter desfaz só esse último lote. Rodar migrar de novo, sem arquivos novos, não faz nada.
Quando uma migração falha
A execução para na migração que falhou, e a mensagem mostra o nome dela. As migrações anteriores do mesmo comando já ficaram aplicadas. Corrija o arquivo e rode migrar de novo: só a que falhou e as seguintes são tentadas.
MySQL
No MySQL, CREATE e ALTER não entram em transação. Se a migração falhar no meio, uma tabela pode ter ficado pela metade. Confira o banco antes de rodar de novo.
4. Exemplo completo
Três arquivos, em ordem, que criam setores, usuários, perfis e cargos, e depois adicionam uma coluna:
<?php
use Elo\Coluna;
use Elo\Migracao;
use Elo\Tabela;
return new class extends Migracao
{
public function subir(): void
{
Tabela::criar('setores', [
'nome' => Coluna::texto(100),
'sigla' => Coluna::texto(15)->unico(),
]);
}
public function descer(): void
{
Tabela::apagar('setores');
}
};
<?php
use Elo\Coluna;
use Elo\Migracao;
use Elo\Tabela;
return new class extends Migracao
{
public function subir(): void
{
Tabela::alterar('usuarios', [
'telefone' => Coluna::texto(20)->nulo(),
]);
}
public function descer(): void
{
Tabela::alterar('usuarios', [
'telefone' => Coluna::remover(),
]);
}
};
Com as tabelas prontas, o próximo passo é o model.
Models
Uma classe por tabela: o que ela aceita, como salvar, buscar e excluir.
1. Criando um model
Crie o arquivo em app/Models/, com o namespace App\Models, e estenda Elo\Modelo. Se a classe não disser nada, o EloPHP já sabe a tabela pelo nome:
app/Models/Usuario.php
<?php
namespace App\Models;
use Elo\Modelo;
class Usuario extends Modelo
{
}
Só isso já permite criar, buscar, salvar e excluir.
Nome da tabela
O nome da classe vira o nome da tabela, no plural, pelas regras do português:
Classe
Tabela
Usuario
usuarios
Setor
setores
Edital
editais
ProcessoJudicial
processos_judiciais
Se a tabela tiver outro nome, defina protected ?string $tabela = 'nome_da_tabela';. As regras completas e as exceções do dicionário estão na seção Pluralização, no fim desta página.
2. Propriedades
Sobrescreva estas propriedades para mudar o comportamento do model. Todas têm um padrão que funciona sem configuração.
<?php
namespace App\Models;
use Elo\Modelo;
class Usuario extends Modelo
{
protected array $protegidos = ['id', 'status']; // não entra no criar() em massa
protected array $ocultos = ['senha']; // some do JSON
protected bool $exclusaoLogica = true; // excluir() só marca a data
protected array $temUm = [
'perfil' => Perfil::class,
];
protected array $pertenceA = [
'setor' => Setor::class,
];
protected array $pertenceAMuitos = [
'cargos' => Cargo::class,
];
}
3. Preenchimento em massa
Não há lista de campos liberados. Tudo entra no criar() e no preencher(), exceto o que está em $protegidos. Os protegidos são ignorados sem erro:
$usuario = Usuario::criar(['nome' => 'Ana', 'status' => 'INATIVO', 'id' => 999]);
echo $usuario->id; // 1: o id foi ignorado
$usuario = Usuario::buscar($usuario->id);
echo $usuario->status; // ATIVO: o status foi ignorado e o padrão do banco valeu
$usuario->status = 'INATIVO'; // a atribuição direta não passa pela proteção
$usuario->salvar();
Dica
Não passe $_POST direto para criar(). Valide antes com uma classe de validação e passe só os campos validados.
4. Campos ocultos
$ocultos remove campos do JSON do próprio model. Cada model oculta os seus: um perfil aninhado mostra só o que o model Perfil deixa aparecer.
5. Datas e exclusão lógica
Datas ($datas = true, padrão). O insert preenche criado_em e atualizado_em. O update preenche só atualizado_em. Um valor de criado_em informado por você é respeitado. A tabela precisa dessas colunas, que Tabela::criar() já cria.
Exclusão lógica ($exclusaoLogica = true).excluir() grava a data em excluido_em em vez de apagar a linha. As consultas escondem esses registros sozinhas:
$produto->excluir();
Produto::buscar($produto->id); // null
Produto::comExcluidos()->obter(); // inclui os excluídos
Produto::onde('ativo', true)->obter(); // o filtro de excluídos é aplicado sozinho
A tabela precisa da coluna excluido_em: crie-a com 'exclusao_logica' => true em Tabela::criar().
6. Métodos
Estáticos
Método
Faz
criar(array $dados)
Cria, salva e devolve o objeto.
buscar($id)
Busca pela chave primária, ou null.
buscarPor($coluna, $valor)
Devolve o primeiro registro com esse valor, ou null.
buscarTodos(array $filtros)
Lista com igualdade em cada coluna. Valor null vira IS NULL.
consulta()
O construtor de consultas do model.
Qualquer método do construtor também funciona direto no model: Usuario::onde(...), Usuario::com(...), Usuario::ordenarPor(...). Veja Consultas e transações.
De instância
Método
Faz
preencher(array $dados)
Atribui campos em massa, respeitando $protegidos.
salvar()
INSERT se o registro é novo. Se já existe, UPDATE só do que mudou.
atualizar(array $dados)
preencher() + salvar() numa chamada. É o jeito curto de editar.
excluir()
DELETE, ou grava excluido_em com exclusão lógica.
estaSalvo()
true depois de salvar ou de vir do banco.
toArray()
Campos (sem os ocultos) e relações já carregadas, como array. É o que o JSON usa.
nomeTabela(), nomeChavePrimaria()
Nome da tabela e da chave primária.
7. Lendo e alterando campos
$usuario->nome = 'Ana Maria'; // altera; ainda não foi gravado
echo $usuario->nome; // lê
isset($usuario->telefone); // verifica se tem valor
$usuario->salvar(); // UPDATE só de nome e atualizado_em
O model guarda como os dados estavam ao chegar do banco. Por isso, o salvar() grava apenas o que mudou, e não há consulta quando nada mudou.
8. Exemplo completo
Models ligados às tabelas da página de Migrações, e um service que os usa:
<?php
namespace App\Services;
use App\Models\Setor;
use App\Models\Usuario;
use Elo\Conexao;
use Elo\Suporte\Paginador;
final class UsuarioService
{
public function cadastrar(array $dados, array $cargosIds): Usuario
{
return Conexao::transacao(function () use ($dados, $cargosIds): Usuario {
$usuario = Usuario::criar($dados);
$usuario->cargos()->sincronizar($cargosIds);
$usuario->perfil()->criar(['bio' => null]);
return $usuario;
});
}
public function listarAtivos(int $pagina): Paginador
{
return Usuario::com('setor', 'cargos')
->onde('status', 'ATIVO')
->ordenarPor('nome')
->paginar(20, $pagina);
}
public function mudarSetor(Usuario $usuario, Setor $setor): void
{
$usuario->setor_id = $setor->id; // chave estrangeira é uma coluna comum
$usuario->salvar(); // UPDATE só de setor_id e atualizado_em
}
public function excluir(Usuario $usuario): void
{
$usuario->excluir(); // grava excluido_em; o registro some das consultas
}
}
Cuidado
perfil()->criar() insere um novo perfil. Como perfis.usuario_id é único, uma segunda chamada para o mesmo usuário falha no banco. Confira antes se ele já tem perfil.
Ao deduzir o nome da tabela, cada palavra da classe é pluralizada pelas regras de sufixo do português:
Termina em
Regra
Exemplo
-ao
vira -oes
Movimentacao → movimentacoes
-m
vira -ns
Item → itens
-al, -el, -ol, -ul
troca o l por is
Edital → editais, Papel → papeis
-il
troca o l por s
Funil → funis
-r, -z, -s
acrescenta -es
Setor → setores, Juiz → juizes
outras
acrescenta -s
Usuario → usuarios
Algumas palavras fogem da regra. Elas estão em um dicionário (Cidadao, Mao, Perfil), e você pode acrescentar as suas com Pluralizador::excecao('vilao', 'viloes'). Para qualquer caso, a saída segura é definir $tabela no model.
Relacionamentos
Como ligar models entre si, como usar as relações e como carregá-las em lote.
1. Os quatro tipos
Cada relação é uma linha em um dos quatro arrays do model. A chave padrão segue o nome do model que tem a coluna.
Para criar, o pai precisa estar salvo. Antes de salvar, criar() gera erro com essa explicação.
4. Muitos para muitos
A tabela pivô sai dos nomes das duas classes, em ordem alfabética e no singular: Usuario e Cargo geram cargo_usuario, com as colunas usuario_id e cargo_id. A criação dessa tabela está em Migrações.
Método
Faz
Devolve
anexar($ids)
Adiciona os vínculos que ainda não existem. Repetidos são ignorados.
Prefira sincronizar() quando a tela envia a lista final, por exemplo um formulário com checkboxes. Ele calcula sozinho o que entra e o que sai.
5. Carregar em lote: com()
Se você lista 100 usuários e lê $usuario->setor em cada um, são 101 consultas: uma para a lista e uma por setor. Com com(), são duas consultas, independentemente do tamanho da lista.
$usuarios = Usuario::com('setor', 'cargos', 'perfil')->ordenarPor('nome')->obter();
foreach ($usuarios as $usuario) {
echo $usuario->setor->sigla; // já carregado: nenhuma consulta nova
}
Você lista as relações no próprio com(), na mesma consulta. Não existe um "carregar depois" separado.
Consultas e transações
Referência completa do construtor de consultas do EloPHP: como montar, executar, paginar e agrupar gravações em transações.
1. Como uma consulta funciona
Cada método de consulta só monta a consulta. Nada vai ao banco até você chamar um método final, como obter(), primeiro(), contar(), existe() ou paginar().
Errado: não executa nada
// Devolve o construtor, não os usuários.
// Se o método for declarado para devolver uma lista, dá erro de tipo.
return Usuario::com('endereco');
Certo: termina com um método final
// Devolve a lista de usuários, com o endereço já carregado.
return Usuario::com('endereco')->ordenarPor('nome')->obter();
Regra de bolso
Se a função deve devolver dados, a última chamada da cadeia é um método final. Os demais métodos servem para montar a consulta.
2. Por onde começar
Toda consulta começa em um model. Qualquer método do construtor pode ser chamado direto no model:
Por padrão, a consulta traz todas as colunas da tabela (tabela.*). Com selecionar(), você traz só as que precisa:
Usuario::selecionar('id', 'nome')->obter();
// Com apelido (as), útil para renomear no resultado
Usuario::selecionar('id', 'nome as apelido')->obter();
// Com a tabela, útil quando há join
Usuario::selecionar('usuarios.nome', 'setores.sigla')->juntar('setores', 'setores.id', 'usuarios.setor_id')->obter();
Cuidado
Um model carregado com colunas selecionadas não tem as outras. Se você for salvá-lo, inclua a chave primária (id) na seleção, senão o salvar() não sabe qual registro atualizar.
4. Filtros
onde(): igualdade ou comparação
Com dois argumentos, compara com igualdade. Com três, usa o operador informado:
Processo::onde('status', 'ABERTO')->obter(); // status = 'ABERTO'
Processo::onde('ano', '>=', 2025)->obter(); // ano >= 2025
Processo::onde('titulo', 'LIKE', 'Ação%')->obter(); // título começa com "Ação"
Processo::onde('status', '!=', 'ARQUIVADO')->obter(); // status diferente de ARQUIVADO
Operador
Significa
=
igual (é o padrão quando você passa dois argumentos)
!= ou <>
diferente
<, <=, >, >=
menor, menor ou igual, maior, maior ou igual
LIKE
combina com um padrão; % é qualquer sequência, _ é um caractere
NOT LIKE
não combina com o padrão
Operadores fora dessa lista geram erro. Isso impede que alguém injete SQL pelo operador.
Comparar com null
onde('cpf', null) gera erro. Use ondeNulo() ou ondeNaoNulo().
ouOnde(): alternativas
Une uma condição com OR. Atenção: o construtor não cria parênteses para você. Como o AND tem prioridade sobre o OR, a ordem das chamadas importa.
Processo::onde('status', 'ABERTO')->ouOnde('status', 'SUSPENSO')->obter();
// WHERE status = 'ABERTO' OR status = 'SUSPENSO'
Quando o model tem exclusão lógica, a parte de filtros do usuário vai entre parênteses, e o filtro de excluídos continua valendo para tudo.
ondeEntre(): intervalo
Valor entre dois limites, incluindo os extremos (BETWEEN):
A lista precisa ter exatamente dois valores, senão dá erro.
ondeEm(): lista de valores
Valor igual a algum da lista (IN):
Usuario::ondeEm('id', [1, 5, 9])->obter();
// Lista vazia: não gera erro, e devolve nenhum resultado
Usuario::ondeEm('id', [])->obter(); // []
Esse caso é comum quando a lista vem de um formulário e pode estar vazia. Nesse caso, o resultado correto é nenhum registro.
ondeNulo() e ondeNaoNulo()
Usuario::ondeNulo('telefone')->obter(); // telefone IS NULL
Usuario::ondeNaoNulo('telefone')->obter(); // telefone IS NOT NULL
Combinando filtros
Filtros encadeados com onde() ou ondeEm() são unidos com AND. Para misturar AND e OR, use ouOnde() em um dos pontos:
// WHERE status = 'ATIVO' AND idade >= 18 OR cadastro_antigo = 1
// lido pelo banco como: (status = 'ATIVO' AND idade >= 18) OR cadastro_antigo = 1
Usuario::onde('status', 'ATIVO')
->onde('idade', '>=', 18)
->ouOnde('cadastro_antigo', true)
->obter();
Atenção à ordem
Não existe agrupamento com parênteses no construtor. Se a regra for status = 'ATIVO' AND (idade >= 18 OR cadastro_antigo = 1), não dá para escrevê-la com ouOnde(). Nesse caso, filtre parte no banco e o resto no código, ou use compilar() (seção 8) para conferir o SQL gerado antes de confiar nele.
5. Ordenação e limite
Método
Faz
Exemplo
ordenarPor($coluna, $direcao)
Ordena. Direção ASC (padrão) ou DESC.
->ordenarPor('criado_em', 'DESC')
limite($n)
No máximo $n registros.
->limite(10)
pular($n)
Pula os primeiros $n registros.
->pular(20)->limite(10)
// Os 10 mais recentes
Pedido::ordenarPor('criado_em', 'DESC')->limite(10)->obter();
// Terceira página de 10 itens (pula 20)
Pedido::ordenarPor('id')->pular(20)->limite(10)->obter();
Para paginar de verdade
Para uma API com páginas, use paginar() (seção 7). Ele já faz a conta e traz o total.
ordenarPor() aceita só ASC ou DESC, e limite()/pular() não aceitam números negativos.
6. Relações na consulta: com()
com() carrega as relações junto com a consulta, em lote. Sem ele, acessar $usuario->endereco em uma lista faria uma consulta extra por usuário.
// 2 consultas no total, não importa quantos usuários
$usuarios = Usuario::com('endereco', 'cargos')->obter();
foreach ($usuarios as $usuario) {
echo $usuario->endereco->cidade; // já carregado
}
Funciona com obter(), primeiro() e paginar(). Relações que não existem no model geram erro com o nome da relação.
7. Exclusão lógica: comExcluidos()
Se o model tem $exclusaoLogica = true, as consultas escondem os registros com excluido_em preenchido. Esse filtro é aplicado sozinho. Para incluí-los:
Produto::comExcluidos()->obter(); // todos, inclusive excluídos
Produto::comExcluidos()->onde('id', 7)->primeiro(); // o 7, mesmo que excluído
8. Métodos finais: executam a consulta
Estes são os métodos que realmente consultam o banco. Cada um devolve um tipo diferente:
Aplica os mesmos campos a todas as linhas que os filtros pegarem, com um único UPDATE. Devolve quantas linhas foram afetadas:
$afetados = Produto::onde('estoque', 0)->atualizar(['ativo' => false]);
// UPDATE "produtos" SET "ativo" = ?, "atualizado_em" = ? WHERE "estoque" = ?
O atualizado_em entra sozinho, quando o model usa datas. O filtro da exclusão lógica continua valendo: registros excluídos não são tocados. Para editar um registro só, prefira $modelo->atualizar(), que grava apenas as colunas que mudaram.
Sem filtro, atualiza tudo
Produto::consulta()->atualizar([...]) sem nenhum onde() altera a tabela inteira. Não funciona junto com juntar(), limite() ou pular(): cada banco escreve esse SQL de um jeito, então o Elo recusa em vez de gerar algo que só roda em um deles.
compilar(): ver o SQL
Devolve o SQL e os valores, sem executar. É a ferramenta de depuração quando um filtro não faz o que você espera:
[$sql, $valores] = Usuario::onde('status', 'ATIVO')->ouOnde('idade', '>', 60)->compilar();
// $sql = SELECT `usuarios`.* FROM `usuarios` WHERE ... (com os ? no lugar dos valores)
// $valores = ['ATIVO', 60]
[$sqlContagem] = Usuario::onde('status', 'ATIVO')->compilar(true); // SQL do contar()
9. Atalhos do model (sem consulta montada)
Estes métodos ficam no próprio model e cobrem os casos mais comuns. Por dentro, usam o construtor:
Método
Faz
Devolve
Usuario::buscar($id)
Busca pela chave primária
model ou null
Usuario::buscarPor('email', $valor)
Primeiro registro com aquele valor
model ou null
Usuario::buscarTodos(['status' => 'ATIVO'])
Lista com igualdade em cada coluna; null vira IS NULL
lista de models
Usuario::criar($dados)
Cria, salva e devolve
model
Usuario::consulta()
Devolve o construtor, para começar uma consulta
construtor
Usuario::buscarTodos(['status' => 'ATIVO', 'telefone' => null]);
// status = 'ATIVO' AND telefone IS NULL
10. Juntar outra tabela: juntar() (avançado)
Adiciona um INNER JOIN. Normalmente, as relações muitos-para-muitos já fazem isso sozinhas. Use juntar() quando precisar de uma junção fora das relações declaradas.
// juntar(tabela, coluna da tabela juntada, coluna da tabela principal)
Usuario::juntar('setores', 'setores.id', 'usuarios.setor_id')
->selecionar('usuarios.*')
->onde('setores.sigla', 'NAT')
->obter();
Use nomes completos
Nas junções, escreva as colunas como tabela.coluna, para não haver ambiguidade quando as duas tabelas tiverem id.
11. Segurança e erros
Os valores nunca entram no SQL como texto: vão como parâmetros do PDO. Nomes de tabelas e colunas são validados e colocados entre aspas pelo banco em uso. Isso bloqueia injeção de SQL pelos nomes, pelos operadores e pelas direções.
Situação
O que acontece
Operador desconhecido (ex.: 'OR 1=1')
Erro antes de consultar o banco
Comparação com null usando onde()
Erro, sugerindo ondeNulo()
Nome de coluna com espaço ou caractere especial
Erro de nome inválido
ordenarPor com direção diferente de ASC/DESC
Erro
ondeEm com lista vazia
Nenhum resultado (sem erro)
ondeEntre com lista que não tem 2 valores
Erro
limite/pular negativos
Erro
12. Transações: tudo ou nada
Uma transação agrupa gravações. Se qualquer uma falhar, todas são desfeitas. Use Conexao::transacao():
use Elo\Conexao;
$pedido = Conexao::transacao(function () use ($dados) {
$pedido = Pedido::criar(['cliente_id' => $dados['cliente_id']]);
foreach ($dados['itens'] as $item) {
$pedido->itens()->criar($item);
}
return $pedido; // este valor é devolvido por transacao()
});
Caso
O que acontece
O bloco termina sem erro
As gravações são confirmadas (commit)
O bloco lança um erro
Tudo é desfeito (rollback) e o erro é relançado
Chamada dentro de outra transação
Entra na transação que já está aberta; não abre outra
Exemplo com erro: nada é gravado
try {
Conexao::transacao(function () {
Cargo::criar(['nome' => 'Gerente']);
throw new \RuntimeException('falhou depois');
});
} catch (\RuntimeException) {
// o cargo "Gerente" não existe no banco
}
MySQL e comandos de estrutura
CREATE e ALTER fecham a transação automaticamente. Não misture migrações com gravações de dados na mesma transação.
13. Conexão: métodos de apoio
Para uso avançado, a classe Elo\Conexao expõe a conexão e o dialeto do banco. Você quase nunca precisa deles no dia a dia.
JSON automático, status, cabeçalhos e o que esconder das respostas.
As partes de uma resposta
Toda resposta HTTP tem três partes:
Status: um número que diz o resultado. 200 deu certo, 201 criado, 404 não encontrado. Veja a lista em Códigos usados.
Cabeçalhos: informações extras, como Content-Type: application/json (o formato do corpo).
Corpo: os dados em si, normalmente em JSON.
No Haki, na maioria das vezes você só se preocupa com o corpo: o resto é preenchido automaticamente.
Respostas automáticas
Basta retornar um valor no controller. O Haki decide o formato:
Você retorna
O cliente recebe
Um array ou objeto
JSON com status 200
Uma string
Texto puro com status 200
null
Status 204, sem corpo
Uma Response
Exatamente o que você montou
// JSON com status 200
$app->get('/produto', function () {
return ['nome' => 'Gomu Gomu', 'preco' => 9.9];
});
// 204 sem conteúdo (comum depois de apagar algo)
$app->delete('/produto/{id}', function (int $id) {
return null;
});
O JSON sai com acentos e barras legíveis ("Olá", e não "Olá").
Controlando status e cabeçalhos
Quando precisar de outro status ou de cabeçalhos, peça um Response no método e monte a resposta:
public function store(CriarProdutoRequest $request, Response $response): Response
{
$produto = $this->criarProduto->executar($request->validated());
return $response
->header('Location', '/produtos/' . $produto->id) // onde o recurso novo está
->json(['produto' => $produto], 201); // 201 = criado
}
Método
Faz
json($dados, $status = 200)
Corpo JSON com Content-Type: application/json
responseJson($dados, $status)
O mesmo que json()
text($texto, $status = 200)
Texto puro
status(204)
Muda só o status
header('Nome', 'valor')
Adiciona um cabeçalho
Respostas mais comuns
// Lista paginada
return $response->json(['dados' => $produtos, 'pagina' => $pagina, 'total' => $total]);
// Criado
return $response->json(['produto' => $produto], 201);
// Apagado (sem corpo)
return $response->status(204);
// Aceito para processar depois
return $response->json(['mensagem' => 'Seu relatório está sendo gerado'], 202);
// Não guardar em cache
return $response->header('Cache-Control', 'no-store')->json($dados);
Para responder com erro (404, 409, 422...), não monte a resposta à mão: lance uma HttpException. Veja Tratamento de erros.
Criando uma resposta direto
Fora de controllers (em um middleware, por exemplo), crie a resposta com new:
use Haki\Http\Response;
new Response(); // vazia, status 200
new Response('', 204); // corpo e status
new Response('ok', 200, ['Cache-Control' => 'no-store']); // com cabeçalhos
(new Response())->json(['erro' => 'Voltamos já'], 503);
Lendo uma resposta
Em middlewares e testes, você pode inspecionar a resposta:
Método
Retorna
getStatus()
O código HTTP, ex.: 201
getBody()
O corpo como texto
getJson()
O corpo JSON decodificado como array
getHeader('Content-Type')
Um cabeçalho, ou null
getHeaders()
Todos os cabeçalhos
Quando a resposta é enviada?
Os métodos de Response só montam a resposta e devolvem o próprio objeto (por isso dá para encadear ->header()->json()). Quem envia para o cliente é o $app->run(), uma única vez, depois que todos os middlewares terminam. Isso permite que um middleware adicione cabeçalhos à resposta do controller.
Por isso, sempre retorne a resposta:
return $response->json($dados); // certo
$response->json($dados); // errado: a resposta montada é descartada e o cliente recebe 204
Objetos no JSON e campos escondidos
Um objeto retornado vira JSON a partir das suas propriedades públicas. Isso pode vazar o que não devia, como o hash da senha. Para controlar exatamente o que sai, implemente JsonSerializable:
app/Models/Usuario.php
final class Usuario implements JsonSerializable
{
public function __construct(
public readonly int $id,
public readonly string $nome,
public readonly string $senhaHash,
) {
}
public function jsonSerialize(): array
{
return ['id' => $this->id, 'nome' => $this->nome]; // senhaHash fica de fora
}
}
Se os dados tiverem algo que não vira JSON (um texto com codificação quebrada, por exemplo), a resposta vira um erro 500. Em desenvolvimento, a dica explica o motivo.
Middleware
Código que roda antes e depois dos controllers, em várias rotas.
O que é um middleware
Um middleware é um código que roda antes e/ou depois do controller, em várias rotas de uma vez. É o lugar certo para o que se repete: liberar o acesso do front-end (CORS), registrar acessos, exigir uma chave de API, medir tempo, colocar a API em manutenção.
Pense em camadas de uma cebola. A requisição atravessa cada camada até chegar no controller, e a resposta volta pelo mesmo caminho, de dentro para fora:
Cada camada pode olhar a requisição, deixar passar, barrar ou alterar a resposta que volta.
Criando um middleware
Crie uma classe em app/Middleware que implemente MiddlewareInterface. Ela tem um único método, handle():
app/Middleware/MedirTempo.php
<?php
declare(strict_types=1);
namespace App\Middleware;
use Haki\Http\Request;
use Haki\Http\Response;
use Haki\Middleware\MiddlewareInterface;
final class MedirTempo implements MiddlewareInterface
{
public function handle(Request $request, callable $next): Response
{
// 1. ANTES: roda antes do controller
$inicio = microtime(true);
// 2. Chama a próxima camada (outro middleware ou o controller)
$response = $next($request);
// 3. DEPOIS: roda com a resposta já pronta
$ms = round((microtime(true) - $inicio) * 1000, 2);
return $response->header('X-Tempo-Ms', (string) $ms);
}
}
O segredo é o $next($request): tudo o que vem antes dele roda antes do controller, e tudo o que vem depois roda depois. O handle() sempre precisa retornar uma Response.
Onde aplicar
Há três lugares, do mais amplo ao mais específico:
// 1. Global: todas as requisições (em bootstrap/app.php)
$app->middleware(MedirTempo::class);
// 2. Em um grupo de rotas (em routes/api.php)
$app->group('/api', function (Haki $app) {
$app->get('/produtos', [ProdutoController::class, 'index']);
})->middleware(RegistrarAcesso::class);
// 3. Em uma rota só
$app->post('/upload', [UploadController::class, 'store'])->middleware(ExigirChaveApi::class);
Você pode passar o middleware de três formas:
Forma
Exemplo
Quando usar
Nome da classe
Cors::class
O normal. O container cria e injeta as dependências do construtor.
Instância
new Cors('https://meusite.com')
Quando o construtor precisa de um valor (texto, número).
Função anônima
function (Request $request, callable $next) { ... }
Middlewares globais, na ordem em que foram registrados
Middlewares do grupo
Autenticação (->auth())
Perfil (->role())
Middlewares da rota
Validação (se o controller pedir uma classe de validação) e o controller
Consequências práticas: quando um middleware de rota roda, $request->user() já está preenchido. E middlewares globais rodam até em respostas de erro (404, 401, 422...), o que é importante para o CORS.
Barrando a requisição
Para impedir que a requisição chegue no controller, retorne uma resposta sem chamar $next, ou lance uma HttpException:
app/Middleware/ExigirChaveApi.php
use Haki\Exceptions\HttpException;
use Haki\Support\Env;
final class ExigirChaveApi implements MiddlewareInterface
{
public function handle(Request $request, callable $next): Response
{
$esperada = Env::get('API_KEY'); // definida no .env
$chave = $request->header('X-Api-Key'); // enviada pelo cliente
if (!is_string($esperada) || $chave === null || !hash_equals($esperada, $chave)) {
throw new HttpException(401, 'Chave de API inválida');
}
return $next($request);
}
}
app/Middleware/ModoManutencao.php
final class ModoManutencao implements MiddlewareInterface
{
public function handle(Request $request, callable $next): Response
{
if (file_exists(__DIR__ . '/../../storage/manutencao')) {
return (new Response())
->header('Retry-After', '600')
->json(['erro' => 'Voltamos em instantes'], 503);
}
return $next($request);
}
}
Para ligar a manutenção, basta criar o arquivo storage/manutencao; para desligar, apagar.
Exemplo: CORS
O navegador bloqueia um site de chamar uma API em outro endereço, a menos que a API autorize. Esse middleware autoriza o seu front-end:
app/Middleware/Cors.php
final class Cors implements MiddlewareInterface
{
public function __construct(private readonly string $origem = 'http://localhost:5173')
{
}
public function handle(Request $request, callable $next): Response
{
// Antes da requisição real, o navegador manda um OPTIONS perguntando se pode ("preflight").
$response = $request->method() === 'OPTIONS' ? new Response('', 204) : $next($request);
return $response
->header('Access-Control-Allow-Origin', $this->origem)
->header('Access-Control-Allow-Headers', 'Authorization, Content-Type')
->header('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
}
}
Registre como global e como primeiro middleware. Assim, até as respostas de erro levam os cabeçalhos, e o navegador consegue mostrar a mensagem de erro em vez de um erro de CORS genérico.
Exemplo: registrando os acessos
app/Middleware/RegistrarAcesso.php
final class RegistrarAcesso implements MiddlewareInterface
{
public function handle(Request $request, callable $next): Response
{
$response = $next($request);
error_log(sprintf(
'%s %s → %d (usuário %s, IP %s)',
$request->method(),
$request->path(),
$response->getStatus(),
$request->user()?->id ?? 'anônimo',
$request->ip() ?? '?',
));
return $response;
}
}
Atenção
Nunca registre no log o token, a senha ou o corpo inteiro das requisições. Logs costumam ser lidos por mais pessoas e guardados por muito tempo.
Tratamento de erros
O formato padrão dos erros e como responder com um.
Formato padrão
Todo erro vira um JSON com o mesmo formato, então o front-end sempre sabe onde procurar a mensagem:
{ "erro": "Usuário não encontrado", "status": 404 }
Respondendo com um erro
Em qualquer lugar (controller, service, middleware), lance uma HttpException:
use Haki\Exceptions\HttpException;
$usuario = $this->usuarios->buscarPorId($id)
?? throw new HttpException(404, 'Usuário não encontrado');
if ($this->usuarios->emailExiste($email)) {
throw new HttpException(409, 'Este e-mail já está cadastrado');
}
Mensagem padrão e cabeçalhos
A mensagem é opcional. Sem ela, o Haki usa uma mensagem padrão para o código:
O terceiro argumento adiciona cabeçalhos à resposta de erro, e o quarto é uma dica que aparece só em desenvolvimento:
throw new HttpException(
429,
'Muitas tentativas. Tente de novo em 1 minuto',
['Retry-After' => '60'],
'O IP ' . $request->ip() . ' passou do limite de 5 tentativas.',
);
Exceções do Haki
O próprio Haki lança estas exceções. Você também pode lançá-las ou capturá-las:
Classe
Status
Quando
HttpException
o informado
Erro HTTP genérico, para você usar
AuthenticationException
401
Token ausente, inválido, expirado ou revogado
AuthorizationException
403
Usuário sem o perfil exigido
RouteNotFoundException
404
Nenhuma rota para o caminho
MethodNotAllowedException
405
O caminho existe, com outro método
ValidationException
422
Dados inválidos; errors() traz as mensagens por campo (namespace Haki\Validation)
ContainerException
500
Uma dependência não pôde ser criada ou injetada
TypeCheckException
500
Código sem tipo, com requireTypes() ativo; problems() lista o que falta
Durante o $app->run(), avisos do PHP (como acessar uma variável que não existe) viram exceções e resultam em erro 500. Assim, um aviso nunca é impresso no meio do JSON, e em desenvolvimento você vê exatamente onde ele aconteceu.
Códigos usados
Código
Quando
200
Deu certo
201
Recurso criado
204
Deu certo, sem conteúdo (ex.: exclusão)
400
Requisição inválida (ex.: JSON quebrado)
401
Não autenticado: sem token, ou token inválido/expirado
403
Autenticado, mas sem permissão
404
Rota ou recurso não encontrado
405
Método HTTP não permitido nesse caminho
422
Dados inválidos (validação), com as mensagens em campos
500
Erro inesperado no servidor
Desenvolvimento x produção
Em desenvolvimento, erros de cliente (4xx) trazem uma dica. Erros de servidor (500) trazem também a exceção, o arquivo, a linha e o trace:
{
"erro": "Token não informado",
"status": 401,
"detalhes": {
"dica": "Envie o cabeçalho \"Authorization: Bearer <token>\"."
}
}
Em produção, nenhum detalhe interno é enviado. Uma exceção inesperada vira apenas:
{ "erro": "Erro interno do servidor", "status": 500 }
O erro completo vai para o log do PHP (error_log), onde só você tem acesso.
Depuração com haki()
Inspecione qualquer valor com a função haki().
A função haki()
Depurar é descobrir o que está acontecendo dentro do código: qual valor uma variável tem, o que chegou na requisição, por que um if não entrou. A função global haki() mostra qualquer valor de forma organizada. Ela substitui o var_dump e o print_r, que são difíceis de ler.
haki($usuario); // um valor
haki($request->all(), $produtos, 123); // vários de uma vez
Ela está disponível em qualquer lugar do projeto, sem use.
O que aparece
Onde foi chamada: o arquivo e a linha, para você achar e apagar depois.
O tipo de cada valor, com uma cor e uma etiqueta: string, int, float, bool, null, array, object, enum, closure.
Textos com a quantidade de caracteres.
Arrays com a quantidade de itens e se são lista ([0, 1, 2]) ou associativo (['nome' => ...]).
Objetos com a classe, um número de identificação e a visibilidade de cada propriedade: + pública, # protegida, - privada.
Datas já formatadas e closures com a assinatura e onde foram criadas.
Referências circulares (um objeto que aponta para si mesmo) são marcadas, em vez de travar a página.
No terminal
Rodando um script pelo terminal, a saída é uma árvore colorida:
haki app/Services/LoginService.php:21
object App\Models\Usuario #12
├─ +id: int 1
├─ +nome: string(15) "Monkey D. Luffy"
├─ +perfis: array(2) lista
│ ├─ 0 => string(5) "admin"
│ └─ 1 => string(6) "membro"
└─ -senhaHash: string(60) "$2y$10$..."
No navegador
Acessando uma rota pelo navegador, aparece um bloco escuro com os níveis recolhíveis:
Clique na setinha ▸ para abrir ou fechar um nível.
Os botões expandir e recolher, no topo do bloco, abrem e fecham tudo.
Ctrl + clique em um item abre ou fecha tudo o que está dentro dele.
Exemplo: descobrindo o que chegou
Um cadastro está falhando e você não sabe por quê. Coloque um haki() no começo do método e chame a rota:
public function store(Request $request): array
{
haki($request->all(), $request->headers());
// ...
}
Na saída você vê, por exemplo, que o front-end mandou "Nome" com N maiúsculo, ou que o Content-Type não é application/json e por isso o corpo chegou vazio.
Parando a execução
Para ver um valor e parar ali, sem rodar o resto do código, use exit logo depois:
haki($pedido);
exit;
Usando no meio do código
haki() devolve o próprio valor recebido (ou um array, se receber vários). Assim, dá para usar no meio de uma expressão sem mudar o código:
$total = haki($this->calcularTotal($pedido)); // mostra o total e continua normalmente
Pegando a saída como texto
Para gravar o dump em um log em vez de imprimir na tela, use a classe Dumper, que é o motor por trás do haki():
use Haki\Support\Dumper;
$texto = Dumper::toText([$pedido]); // árvore em texto puro
$html = Dumper::toHtml([$pedido]); // bloco HTML
error_log($texto);
Remova antes de publicar
Em uma API, a saída do haki() aparece antes do JSON e quebra a resposta: o front-end recebe HTML misturado com JSON e não consegue ler. Antes de enviar o código, procure por haki( no projeto e apague as chamadas.
Como funciona a autenticação
Como o login com JWT funciona, do começo ao fim.
Visão geral
O Haki usa JSON Web Tokens (JWT). Depois do login, o cliente recebe um token e o envia em cada requisição protegida. O servidor confere a assinatura do token e sabe quem é o usuário sem guardar sessão.
O fluxo completo
O cliente envia e-mail e senha para POST /login.
A sua aplicação confere as credenciais (o Haki não sabe nada sobre senhas).
Se estiverem corretas, você chama $auth->login($usuario->id).
O Haki devolve um access token (curto, 15 min) e um refresh token (longo, 7 dias).
O cliente envia Authorization: Bearer <access_token> nas rotas protegidas.
Quando o access token expira, o cliente troca o refresh token por um par novo em POST /refresh.
No logout, os tokens daquela sessão são revogados.
Login, uso do access token, renovação com o refresh token e a proteção contra roubo.
Configurando
Gere um segredo forte. O comando grava o JWT_SECRET no seu .env:
php vendor/bin/haki key:generate
Pronto, nada mais é obrigatório. Para mudar os padrões, use $app->auth() no bootstrap:
Sem chamar $app->auth(), o Haki lê as variáveis do .env na primeira vez que a autenticação for usada. As opções são validadas assim que você chama $app->auth(): um segredo curto ou uma chave inválida geram erro na hora, nunca um padrão inseguro.
O que vai dentro do token
Claim
Significado
sub
ID do usuário
role
Perfil, se você informar no login
iat / exp
Quando foi emitido / quando expira
jti
ID único do token (usado no logout)
fid
ID da sessão de login (usado no logout e no refresh)
iss
Emissor, se configurado
Atenção
O conteúdo de um JWT pode ser lido por qualquer pessoa (ele é só assinado, não criptografado). Nunca coloque senhas, documentos ou dados sensíveis nos claims.
O que o Haki garante
O algoritmo é sempre o configurado: tokens com "alg": "none" ou com outro algoritmo são recusados.
A assinatura é comparada em tempo constante, o que protege contra ataques de tempo.
Tokens expirados, adulterados, malformados ou sem os claims obrigatórios recebem 401.
Não existe segredo padrão: sem JWT_SECRET, a autenticação não inicia.
O cliente sempre recebe uma mensagem genérica. O motivo real aparece só na dica, em desenvolvimento.
Login e tokens
Conferir a senha e gerar os tokens.
Quem faz o quê
No login, o trabalho é dividido em duas partes:
A sua aplicação confere se o e-mail e a senha estão certos. Só ela sabe onde os usuários estão guardados.
O Haki gera os tokens para o usuário que você já conferiu, com $auth->login($id).
Nesta página, vamos montar o login completo, em quatro arquivos.
Antes de começar
Gere o segredo dos tokens com php vendor/bin/haki key:generate. Veja Configurando.
0. Guardando a senha no cadastro
A senha nunca é salva como foi digitada. No cadastro, gere um hash com password_hash() e salve o hash:
$hash = password_hash($senhaDigitada, PASSWORD_DEFAULT);
// "$2y$10$Lq7..." ← é isso que vai para o banco
No login, password_verify($senhaDigitada, $hash) diz se a senha confere. Nem você consegue descobrir a senha original a partir do hash, e é exatamente essa a ideia.
1. A regra de login fica em um service
Conferir senha é regra de negócio, então fica em app/Services. O service usa um repository para encontrar o usuário:
app/Services/LoginService.php
<?php
declare(strict_types=1);
namespace App\Services;
use App\Contracts\UsuarioRepositoryInterface;
use App\Models\Usuario;
use Haki\Exceptions\HttpException;
final class LoginService
{
public function __construct(private readonly UsuarioRepositoryInterface $usuarios)
{
}
public function autenticar(string $email, string $senha): Usuario
{
$usuario = $this->usuarios->buscarPorEmail($email);
// Mesma mensagem nos dois casos: não revela quais e-mails existem.
if ($usuario === null || !password_verify($senha, $usuario->senhaHash)) {
throw new HttpException(401, 'E-mail ou senha incorretos');
}
return $usuario;
}
}
Por que a mesma mensagem?
Se a API respondesse "e-mail não encontrado" num caso e "senha errada" no outro, qualquer pessoa conseguiria descobrir quais e-mails têm conta. Com uma mensagem só, isso não é possível.
2. A validação dos dados
app/Requests/LoginRequest.php
<?php
declare(strict_types=1);
namespace App\Requests;
use Haki\Validation\FormRequest;
use Haki\Validation\Rule;
final class LoginRequest extends FormRequest
{
public function rules(Rule $rule): array
{
return [
'email' => $rule->email(),
'senha' => $rule->text(),
];
}
}
3. O controller só conecta as peças
app/Controllers/AuthController.php
<?php
declare(strict_types=1);
namespace App\Controllers;
use App\Requests\LoginRequest;
use App\Services\LoginService;
use Haki\Auth\Auth;
final class AuthController
{
public function __construct(private readonly LoginService $login)
{
}
public function login(LoginRequest $request, Auth $auth): array
{
$usuario = $this->login->autenticar($request->email, $request->senha);
return $auth->login($usuario->id, ['role' => $usuario->perfil]);
}
}
Lendo de cima para baixo: o LoginRequest já garantiu que o e-mail e a senha foram enviados; o service confere a senha; o $auth->login() gera os tokens.
4. A rota
routes/api.php
$app->post('/login', [AuthController::class, 'login']); // pública: ainda não há token
No próximo passo, veja como proteger as rotas para exigir esse token.
Limite de tentativas de login
O Haki não limita tentativas de login por padrão. Sem esse limite, alguém pode testar senhas sem parar. Use a classe LimiteDeTentativas no service de login: ela conta as falhas por chave (a conta e o IP) e, ao passar do máximo, responde 429 sem nem verificar a senha.
app/Services/LoginService.php
<?php
declare(strict_types=1);
namespace App\Services;
use App\Repositories\UsuarioRepositoryInterface;
use Haki\Auth\Auth;
use Haki\Auth\Tentativas\LimiteDeTentativas;
final class LoginService
{
public function __construct(
private UsuarioRepositoryInterface $usuarios,
private Auth $auth,
private LimiteDeTentativas $limite,
) {
}
public function entrar(string $email, string $senha, string $ip): array
{
$usuario = $this->limite->verificar(
['email:' . $email, 'ip:' . $ip],
function () use ($email, $senha) {
$usuario = $this->usuarios->buscarPorEmail($email);
return $usuario !== null && password_verify($senha, $usuario->senhaHash) ? $usuario : null;
},
);
return $this->auth->login($usuario->id, ['role' => $usuario->role]);
}
}
Configuração no bootstrap/app.php
use Haki\Auth\Tentativas\LimiteDeTentativas;
use Haki\Auth\Tentativas\PdoArmazenamentoDeTentativas;
$tentativas = new PdoArmazenamentoDeTentativas(new PDO('sqlite:storage/haki.sqlite'));
$tentativas->criarTabela();
$app->container()->singleton(
LimiteDeTentativas::class,
fn () => new LimiteDeTentativas($tentativas, maximo: 5, janela: 900), // 5 falhas em 15 minutos
);
O que o cliente recebe
Situação
Resposta
Senha ou e-mail errados
401, com a mensagem E-mail ou senha incorretos.
Muitas falhas na janela
429, com o cabeçalho Retry-After em segundos
Login certo
O normal, e as falhas dessas chaves voltam a zero
A resposta de erro não diz se o e-mail existe: os dois casos (usuário inexistente ou senha errada) são a mesma falha.
Como contar
Duas chaves:email: protege a conta contra ataque direcionado; ip: protege contra quem testa muitas contas de uma vez. Uma falha conta nas duas.
Erros de infraestrutura não contam: se o banco cair no meio da verificação, a falha não entra no contador.
Chaves são normalizadas:Ana@X.br e ana@x.br são a mesma conta.
Janela deslizante: o bloqueio passa quando a última falha contada tem mais que janela segundos.
Trade-off do IP
Muitos usuários podem sair pelo mesmo IP (rede da empresa, operadora). Um limite de IP baixo demais bloqueia todos eles. Comece com um valor folgado, como 20 falhas por IP, e a chave de conta com 5.
Vários servidores
O contador precisa ficar no banco compartilhado, o mesmo do PdoTokenStore. Se cada servidor tiver o próprio contador, o limite vale só para o servidor que recebeu as tentativas.
Protegendo rotas
Exigir login e perfis com ->auth() e ->role().
Exigindo login: ->auth()
Por padrão, toda rota é pública: qualquer pessoa pode chamar. Para exigir que o cliente esteja logado, adicione ->auth():
Lê o token do cabeçalho Authorization: Bearer ....
Confere a assinatura, a validade e se o token não foi revogado (logout).
Se tudo estiver certo, preenche $request->user() e chama o controller.
Se algo falhar, responde 401 e o controller nem é chamado.
Exigindo um perfil: ->role()
Algumas rotas são só para certos usuários, como administradores. ->role() exige um perfil específico e já inclui o ->auth():
// Só administradores
$app->get('/admin/painel', [AdminController::class, 'painel'])->role('admin');
// Administradores OU gerentes
$app->get('/relatorios', [RelatorioController::class, 'index'])->role('admin', 'gerente');
O perfil vem do claim role que você colocou no login: $auth->login($id, ['role' => 'admin']). A comparação é exata: 'Admin' e 'admin' são perfis diferentes.
Cada ->role() é um requisito a mais. Uma rota com ->role('gerente') dentro de um grupo com ->role('admin') exige os dois perfis ao mesmo tempo, o que normalmente não é o que se quer. Para aceitar um ou outro, liste os dois na mesma chamada: ->role('admin', 'gerente').
No front-end, a reação a cada um é diferente: com 401, tente renovar o token com o refresh token e, se não der, mande para a tela de login. Com 403, mostre que a pessoa não tem permissão; fazer login de novo não resolve.
Respostas 401 trazem o cabeçalho WWW-Authenticate: Bearer, o padrão do HTTP para dizer que tipo de credencial é esperado.
Problemas comuns
Sintoma
Causa
Sempre 401 "Token não informado", mesmo enviando
Faltou a palavra Bearer e o espaço: o certo é Authorization: Bearer eyJ.... No Apache, pode ser o cabeçalho sendo descartado; veja a configuração em Apache.
Funcionava e passou a dar 401
O access token venceu (15 minutos). Use o refresh token.
403 para um usuário que deveria ter acesso
O token foi gerado antes da mudança de perfil, ou o role está com outra grafia. Faça login de novo e confira o valor em /eu.
A rota protegida responde 422 em vez de 401
Não acontece: a autenticação roda antes da validação. Se aparecer 422, o token foi aceito.
Usuário autenticado
Descobrir quem fez a requisição com $request->user().
Descobrindo quem fez a requisição
Em rotas com ->auth(), $request->user() devolve quem está logado. Você não precisa ler o token nem buscar nada: o Haki já validou e montou a identidade.
public function eu(Request $request): array
{
return ['usuario' => $request->user()];
}
{ "usuario": { "id": "1", "role": "admin" } }
O que a identidade oferece
Uso
Retorna
$user->id
O ID do usuário, sempre como texto ('1')
$user->role
O perfil, ou null
$user->get('nome')
Um dado extra que você colocou no login
$user->get('nome', 'Visitante')
O mesmo, com valor padrão
$user->hasRole('admin', 'gerente')
true se tiver um dos perfis
$user->claims
Todos os dados do token, inclusive os de controle
Exemplos de uso
// Buscar os pedidos só do usuário logado
public function index(Request $request): array
{
$idUsuario = (int) $request->user()->id; // o id vem como texto; converta se o banco usa número
return ['pedidos' => $this->pedidos->doUsuario($idUsuario)];
}
// Impedir que alguém veja o pedido de outra pessoa
public function show(int $id, Request $request): array
{
$pedido = $this->pedidos->buscar($id) ?? throw new HttpException(404, 'Pedido não encontrado');
$usuario = $request->user();
if ($pedido->usuarioId !== (int) $usuario->id && !$usuario->hasRole('admin')) {
throw new HttpException(403, 'Este pedido não é seu');
}
return ['pedido' => $pedido];
}
Sempre confira o dono
->auth() garante que a pessoa está logada, mas não que o recurso é dela. Se a rota recebe um {id}, confira se ele pertence ao usuário (como no exemplo acima). Esquecer essa conferência é uma das falhas de segurança mais comuns em APIs.
Como a identidade vira JSON
Retornada em uma resposta, a identidade mostra id, role e os dados extras do login. Os dados de controle do token (iat, exp, jti, fid, iss) ficam de fora:
Em casos especiais, como uma rota pública que mostra algo a mais para quem está logado, valide o token você mesmo com $auth->authenticate(). Ele faz as mesmas verificações do ->auth() e lança AuthenticationException se o token for inválido:
use Haki\Auth\Auth;
use Haki\Exceptions\AuthenticationException;
$app->get('/vitrine', function (Request $request, Auth $auth) {
$usuario = null;
$token = $request->bearerToken();
if ($token !== null) {
try {
$usuario = $auth->authenticate($token); // devolve a identidade
} catch (AuthenticationException) {
// token inválido: segue como visitante
}
}
return ['saudacao' => $usuario ? 'Olá de novo, ' . $usuario->get('nome') : 'Bem-vindo!'];
});
Quando user() é null
Em rotas sem ->auth(), user() é sempre null, mesmo que o cliente envie um token. A identidade só é preenchida depois que o token é validado. Assim, ninguém consegue se passar por outro usuário mandando dados forjados.
A identidade vem do token, não do banco
O Haki não consulta o seu banco de dados. A identidade traz o que estava no token no momento do login. Na prática:
Se o usuário mudar de nome ou de perfil, o token antigo continua com os dados antigos até vencer (no máximo 15 minutos, por padrão).
Se o usuário for bloqueado, o token antigo continua funcionando até vencer.
Para mudanças que precisam valer na hora, revogue os tokens dele com $auth->logoutAll($id) (veja Sair de todos os dispositivos). Se você precisa conferir o banco a cada requisição, crie um middleware próprio e aplique depois do ->auth():
app/Middleware/UsuarioAtivo.php
final class UsuarioAtivo implements MiddlewareInterface
{
public function __construct(private readonly UsuarioRepositoryInterface $usuarios)
{
}
public function handle(Request $request, callable $next): Response
{
$usuario = $this->usuarios->buscarPorId((int) $request->user()?->id);
if ($usuario === null || $usuario->bloqueado) {
throw new HttpException(403, 'Conta bloqueada');
}
return $next($request);
}
}
$app->group('/', function (Haki $app) {
// ...
})->auth()->middleware(UsuarioAtivo::class);
O custo é uma consulta ao banco por requisição. Use só se a sua aplicação realmente precisar.
Trocou o perfil? Revogue as sessões
O perfil (role) fica dentro do token, e o Haki não consulta o banco a cada requisição. Por isso, depois de trocar o perfil de alguém, os tokens dele ainda carregam o perfil antigo até expirarem. Para o efeito valer na hora, revogue as sessões na mesma operação:
public function trocarPerfil(int $usuarioId, string $novoPerfil): void
{
$this->usuarios->atualizarPerfil($usuarioId, $novoPerfil);
// Derruba os tokens e os refresh tokens antigos desse usuário.
$this->auth->logoutAll($usuarioId);
}
Com isso, o access token antigo para de valer na próxima requisição, e o refresh token deixa de renovar. O usuário entra de novo e recebe um token com o perfil novo. Um login feito logo depois dessa operação funciona normalmente.
Bloqueio de conta
O mesmo padrão serve para bloquear alguém: marque a conta como inativa e chame logoutAll(). Assim, nenhum token dela continua valendo.
Refresh e logout
Renovar tokens, encerrar sessões e se proteger de roubo.
Por que dois tokens?
No login, o cliente recebe dois tokens com papéis diferentes:
Access token
Refresh token
Para que serve
Acessar as rotas protegidas
Pedir um access token novo
Validade padrão
15 minutos
7 dias
Enviado em
Toda requisição protegida
Só em POST /refresh
Se for roubado
Serve por poucos minutos
É detectado na primeira vez que for reutilizado
A vantagem: o token que viaja em toda requisição (e por isso tem mais chance de vazar) vence rápido, e o usuário não precisa digitar a senha a cada 15 minutos.
Renovando os tokens
Crie a rota de refresh. Ela é pública, porque é usada justamente quando o access token já venceu:
app/Controllers/AuthController.php
public function refresh(Request $request, Auth $auth): array
{
return $auth->refresh($request->input('refresh_token'));
}
A resposta tem o mesmo formato do login: um access_token novo e um refresh_token novo.
O fluxo no cliente
Faz a requisição normalmente com o access token.
Se receber 401, chama POST /refresh com o refresh token guardado.
Se o refresh der certo, guarda os dois tokens novos e repete a requisição original.
Se o refresh também der 401, a sessão acabou: manda o usuário para a tela de login.
JavaScript
async function api(url, opcoes = {}) {
let resposta = await fetch(url, comToken(opcoes));
if (resposta.status === 401 && await renovarTokens()) {
resposta = await fetch(url, comToken(opcoes)); // tenta de novo com o token novo
}
return resposta;
}
async function renovarTokens() {
const r = await fetch('/refresh', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ refresh_token: tokens.refresh }),
});
if (!r.ok) { irParaLogin(); return false; }
const novos = await r.json();
tokens.access = novos.access_token;
tokens.refresh = novos.refresh_token; // guarde o novo: o antigo não vale mais
return true;
}
Rotação: cada refresh token vale uma vez
Ao usar um refresh token, o cliente recebe um par novo e o refresh token usado deixa de valer. Por isso o cliente deve sempre substituir o refresh token guardado pelo novo.
Detecção de roubo
Imagine que alguém copiou o refresh token da Nami:
O atacante usa o token copiado e recebe um par novo.
Mais tarde, o app da Nami usa o mesmo token (que já foi usado pelo atacante).
O Haki percebe que um refresh token já usado apareceu de novo: há duas cópias, e uma é ilegítima.
Para proteger a conta, ele revoga todas as sessões da Nami, inclusive a do atacante.
A Nami faz login de novo; o atacante perde o acesso.
Você não precisa programar nada disso: acontece sozinho dentro do $auth->refresh().
Quando o refresh falha
Em todos estes casos, a resposta é 401 "Refresh token inválido ou expirado": token não enviado, inexistente, vencido, revogado por logout, ou reutilizado.
Logout
logout() encerra a sessão atual: o access token usado na requisição e os refresh tokens daquele login deixam de valer. As sessões em outros dispositivos continuam.
app/Controllers/AuthController.php
public function logout(Request $request, Auth $auth): null
{
$auth->logout($request);
return null; // 204 sem conteúdo
}
routes/api.php
$app->post('/logout', [AuthController::class, 'logout'])->auth(); // precisa de ->auth()
A rota precisa de ->auth() porque o logout usa o token da requisição para saber qual sessão encerrar. No cliente, depois do logout, apague os tokens guardados.
Sair de todos os dispositivos
logoutAll() revoga todos os tokens já emitidos para o usuário, em todos os dispositivos:
$auth->logoutAll($usuario->id);
Use quando:
A pessoa trocar a senha (outras sessões abertas podem ser de quem descobriu a senha antiga).
O perfil mudar, para o novo valer imediatamente.
A conta for bloqueada.
O usuário clicar em "sair de todos os dispositivos".
// Exemplo: trocar a senha
public function trocarSenha(TrocarSenhaRequest $request, Auth $auth): array
{
$id = (int) $request->user()->id;
$this->usuarios->atualizarSenha($id, password_hash($request->nova_senha, PASSWORD_DEFAULT));
$auth->logoutAll($id);
return $auth->login($id); // devolve tokens novos para o dispositivo atual
}
Nota
logoutAll() revoga os tokens emitidos antes da chamada. Um login() feito logo em seguida, como no exemplo acima, gera tokens novos que funcionam normalmente.
Chaves RS256
Par de chaves para outros serviços conferirem os seus tokens.
HS256 ou RS256?
O token JWT é assinado: uma espécie de lacre que prova que foi a sua API que o emitiu e que ninguém o alterou. Há duas formas de fazer esse lacre:
HS256 (padrão)
RS256
Como funciona
Um único segredo assina e confere
Um par de chaves: a privada assina, a pública confere
Quem pode conferir os tokens
Só quem tem o segredo (que também pode criar tokens)
Qualquer um com a chave pública (que não consegue criar tokens)
Configuração
Uma linha no .env
Dois arquivos de chave
Use quando
Só a sua API lida com os tokens
Outros serviços precisam conferir os tokens da sua API
Uma analogia: no HS256, todos que conferem a assinatura têm a mesma chave do cofre, e por isso também poderiam abri-lo. No RS256, a chave privada fica só com quem emite; os outros recebem uma chave que só serve para conferir.
Na dúvida, fique com o HS256. Ele é mais simples e igualmente seguro para uma API só.
1. Gerando as chaves
php vendor/bin/haki key:generate --rsa
✔ Chaves RSA geradas em C:\projetos\minha-api\storage\keys
Adicione ao .env:
JWT_ALGORITHM=RS256
JWT_PRIVATE_KEY=storage/keys/private.pem
JWT_PUBLIC_KEY=storage/keys/public.pem
O comando cria duas chaves RSA de 2048 bits em storage/keys/. Se elas já existirem, use --force para gerar novas (isso desconecta todos os usuários).
Esse serviço consegue proteger rotas com ->auth() e ler $request->user(), mas não consegue emitir tokens: se tentar chamar $auth->login(), recebe um erro explicando que falta a chave privada.
O que o Haki confere nas chaves
As chaves precisam ser RSA válidas, com pelo menos 2048 bits. Chaves menores são recusadas na hora.
Um token assinado com HS256 é recusado por uma API configurada com RS256 (e vice-versa). Isso impede um ataque conhecido em que o atacante tenta assinar um token usando a chave pública como se fosse segredo.
Proteja a chave privada
Ela é tão sensível quanto uma senha: quem tiver a chave privada consegue criar tokens de qualquer usuário. Nunca envie para o Git (o .gitignore do init já deixa storage/keys/ de fora) e nunca compartilhe com outros serviços: eles só precisam da pública.
Trocando a chave sem derrubar sessões
Trocar a chave de assinatura faz os tokens emitidos com a chave antiga pararem de valer, e todos os usuários precisariam entrar de novo. Para evitar isso, a troca acontece em duas etapas, com uma chave antiga que continua validando por um tempo.
Etapa 1: a chave nova assina, a antiga ainda valida (.env)
# chave nova (assina os tokens emitidos daqui para frente)
JWT_PRIVATE_KEY=storage/keys/jwt-private-2026.pem
JWT_PUBLIC_KEY=storage/keys/jwt-public-2026.pem
JWT_KID=k2
# chave antiga (só valida os tokens que ainda estão no prazo)
JWT_KID_ANTERIOR=k1
JWT_PUBLIC_KEY_ANTERIOR=storage/keys/jwt-public-2025.pem
Em HS256, o mesmo esquema vale com o segredo: JWT_SECRET e JWT_KID para a nova, e JWT_SECRET_ANTERIOR com JWT_KID_ANTERIOR para a antiga.
Etapa 2: depois de JWT_TTL (o tempo de vida do access token), remova as variáveis _ANTERIOR
# JWT_KID_ANTERIOR e JWT_PUBLIC_KEY_ANTERIOR removidas
Ponto
Como funciona
Quem assina
Sempre a chave com JWT_KID.
Quem valida
A chave indicada no kid do token. Tokens sem kid, emitidos antes da troca, são conferidos com todas as chaves.
Refresh tokens
Não mudam: são valores aleatórios guardados no armazenamento, não JWTs.
Chave desconhecida
Um token com kid que não está mais configurado recebe 401.
Use kid em toda chave
Com uma chave anterior configurada, o JWT_KID da chave atual é obrigatório. Sem ele, o Haki recusa a configuração, porque não saberia qual chave cada token usa.
Armazenamento de tokens
Onde o Haki guarda refresh tokens e revogações.
Por que guardar alguma coisa?
Um JWT é autossuficiente: o servidor confere a assinatura e pronto, sem consultar nada. O problema é que, sozinho, ele não pode ser cancelado antes de vencer. Para o logout e o refresh token funcionarem, o Haki precisa lembrar de algumas coisas:
Quais refresh tokens existem, se já foram usados e a qual login pertencem. Só o hash é guardado, nunca o token em si.
Quais access tokens foram revogados por logout, até a data em que venceriam.
A data do último logoutAll() de cada usuário.
Armazenamento automático
Com DB_CONNECTION=mysql, o Haki usa a conexão MySQL configurada em DB_* e cria as tabelas de tokens no primeiro uso. Ative pdo_mysql e conceda permissão para criar tabelas e índices. auth:install também prepara essas tabelas no deploy, e auth:clean usa o mesmo banco.
Crie antes o banco MySQL e gere a chave com php vendor/bin/haki key:generate. Não é necessário configurar PdoTokenStore no bootstrap: o Haki usa o mesmo PDO do EloPHP. O usuário do banco precisa de permissão para criar tabelas e índices também no primeiro uso de cada processo ou requisição.
Se storage for informado em $app->auth([...]), ele tem prioridade. A CLI escolhe o armazenamento padrão a partir do .env e não carrega essa configuração personalizada do bootstrap.
Ao atualizar uma instalação que já usa MySQL e guardava tokens em SQLite, refresh tokens e revogações não são migrados. Access tokens revogados podem voltar a ser aceitos até expirar; planeje a migração dos registros ou a troca da chave JWT.
Nos demais casos, essas informações ficam em um arquivo SQLite que é criado sozinho na primeira requisição que usa autenticação:
storage/
└── haki.sqlite criado automaticamente
Você não precisa criar tabela nem rodar migração. Só precisa de duas coisas:
A extensão pdo_sqlite ativa no PHP. Se não estiver, a mensagem de erro explica como ativar.
Permissão de escrita na pasta storage/ para o usuário do PHP.
Se preferir criar o banco de forma explícita (no deploy, por exemplo, para descobrir problemas de permissão antes do primeiro acesso):
php vendor/bin/haki auth:install
Limpeza dos registros vencidos
Tokens vencidos não servem para nada e são apagados sozinhos, de tempos em tempos, durante as requisições. Em APIs com muito tráfego, vale agendar a limpeza:
$app->auth([
'secret' => getenv('JWT_SECRET'),
'database' => 'storage/tokens/auth.sqlite', // relativo à raiz do projeto
]);
Ou pelo .env: JWT_DATABASE=storage/tokens/auth.sqlite. Essas opções de caminho se aplicam ao armazenamento SQLite; com DB_CONNECTION=mysql, o padrão é MySQL.
Um servidor ou vários?
Um servidor: o SQLite padrão basta, mesmo com bastante tráfego.
Vários servidores atrás de um balanceador: use um banco compartilhado. MySQL é selecionado automaticamente por DB_CONNECTION=mysql; outros bancos podem ser configurados com PdoTokenStore.
Vários servidores: PdoTokenStore
O PdoTokenStore guarda refresh tokens, revogações de logout e revogações por usuário em qualquer banco que o PDO atenda. Todos os servidores apontam para o mesmo banco, então uma revogação feita em um vale em todos.
1. Criar as tabelas (uma vez, no deploy)
use Haki\Auth\Storage\PdoTokenStore;
$pdo = new PDO('mysql:host=127.0.0.1;dbname=app', 'usuario', 'senha');
(new PdoTokenStore($pdo))->criarTabelas(); // pode rodar de novo: não apaga nada
Com DB_CONNECTION=mysql não é necessária configuração explícita: o Haki usa a conexão do EloPHP automaticamente. A configuração acima é útil para escolher outro banco manualmente.
Contador de tentativas de login
O mesmo banco serve para o limite de tentativas de login, pela classe PdoArmazenamentoDeTentativas. Use o mesmo PDO nos dois.
Limpeza
Os registros vencidos não somem sozinhos com o PdoTokenStore: a limpeza automática roda em pequena parte das validações. Se preferir, agende a remoção com purgeExpired().
Outro armazenamento
Para Redis ou outro sistema, implemente a interface TokenStore e informe a classe em storage. Os métodos estão descritos no código da interface, com o que cada um deve garantir (em especial a atomicidade de consumeRefreshToken()).
Tipagem
Como o Haki usa os tipos e como exigir tipagem em todo o projeto.
Por que tipar
Tipar é dizer, no próprio código, que tipo de valor cada parte espera e devolve: function buscar(int $id): ?Produto diz "recebo um número inteiro e devolvo um Produto ou nada". O PHP passa a conferir isso a cada chamada.
Sem tipo, o PHP aceita qualquer coisa e tenta converter sozinho. O erro aparece longe de onde nasceu, ou nem aparece:
// Sem tipos: "abc" vira 0, e o código segue como se estivesse tudo certo
function desconto($preco, $percentual) { return $preco - $preco * $percentual / 100; }
desconto("abc", 10); // 0, sem nenhum aviso
// Com tipos: o erro aparece na hora, apontando a linha
function desconto(float $preco, int $percentual): float { ... }
desconto("abc", 10); // TypeError: Argument #1 ($preco) must be of type float, string given
Com tipos, o editor também completa métodos, avisa erros enquanto você digita e qualquer pessoa entende a função sem precisar ler o corpo dela.
Tipagem obrigatória: $app->requireTypes()
O Haki pode exigir tipos no código do projeto. Com isto no bootstrap/app.php (o haki init já cria assim):
bootstrap/app.php
$app->requireTypes();
toda classe do projeto que o Haki for usar (controllers, services, repositories, classes de validação, middlewares) é conferida antes de rodar. Se faltar algum tipo, a requisição responde com erro dizendo exatamente o que corrigir.
O que é exigido
Onde
Exigência
Exemplo certo
Arquivo
declare(strict_types=1); logo depois do <?php
<?php declare(strict_types=1);
Parâmetros dos métodos
Todos com tipo
function show(int $id)
Retorno dos métodos
Todos com tipo (menos __construct)
function show(int $id): array
Propriedades
Todas com tipo
private int $total = 0;
Funções anônimas das rotas
Parâmetros com tipo (o retorno é livre)
function (int $id) { ... }
Só o seu código é conferido: as classes do Haki, do PHP e de pacotes em vendor/ ficam de fora.
Exemplo: o que acontece quando falta um tipo
Imagine que alguém escreveu o método show sem tipos:
app/Controllers/ProdutoController.php
public function show($id) // linha 29: sem tipo no $id e sem tipo de retorno
{
return ['produto' => $this->encontrar($id)];
}
1. A API responde com erro
Na primeira requisição a qualquer rota desse controller, o Haki confere a classe inteira e recusa. Em desenvolvimento, a resposta diz o que corrigir e em que linha:
GET /produtos/1 (APP_ENV=development)
{
"erro": "Erro interno do servidor",
"status": 500,
"detalhes": {
"dica": "Adicione os tipos indicados (ex.: function show(int $id): array). A exigência vem de $app->requireTypes() no bootstrap/app.php. Confira tudo de uma vez com: php vendor/bin/haki check",
"excecao": "Haki\\Exceptions\\TypeCheckException",
"mensagem": "Tipagem obrigatória: App\\Controllers\\ProdutoController tem 2 problemas. ProdutoController::show(): parâmetro $id sem tipo (linha 29). ProdutoController::show(): falta o tipo de retorno (linha 29)."
}
}
Em produção, o cliente vê só a mensagem genérica, e o detalhe vai para o log do PHP:
GET /produtos/1 (APP_ENV=production)
{ "erro": "Erro interno do servidor", "status": 500 }
2. O haki check aponta antes de publicar
Você não precisa esperar alguém acessar a rota. O check confere a tipagem de todas as classes da pasta app/, inclusive as que nenhuma rota usa, como as models:
php vendor/bin/haki check
Rotas
✔ POST /login → App\Controllers\AuthController::login
✖ GET /produtos/{id}
App\Controllers\ProdutoController tem problemas de tipagem (detalhes em "Tipagem", abaixo).
...
Tipagem
✖ App\Controllers\ProdutoController
ProdutoController::show(): parâmetro $id sem tipo (linha 29).
ProdutoController::show(): falta o tipo de retorno (linha 29).
✔ 12 classes tipadas corretamente
✖ 6 problemas encontrados.
3. Corrigindo
public function show(int $id): array
{
return ['produto' => $this->encontrar($id)];
}
Um Produto ounull (ex.: busca que pode não encontrar)
int|string
Um dos dois tipos
void
Método que não devolve nada
null
Método que sempre devolve null (ex.: rota que responde 204)
mixed
Qualquer coisa. Evite: só quando não houver outro jeito
never
Método que sempre lança exceção
Arrays com conteúdo conhecido
O PHP só entende array, sem dizer o que tem dentro. Para documentar o conteúdo (o editor e o PHPStan entendem), use um comentário: /** @return list<Produto> */ ou /** @param array<string, mixed> $dados */.
Desligando
Para um projeto antigo, com muito código sem tipo, remova a linha $app->requireTypes(); do bootstrap e vá tipando aos poucos, usando o haki check como guia. Com a linha removida, nada é conferido e tudo funciona como antes.
Indo além: PHPStan
O requireTypes() confere se os tipos existem. Para conferir se eles estão certos (por exemplo, se você passa uma string onde se espera int, ou chama um método em algo que pode ser null), use o PHPStan, que analisa o código sem executá-lo:
Os dois se completam: rode php vendor/bin/phpstan analyse app --level=9 && php vendor/bin/haki check antes de cada deploy.
Container de dependências
Injeção de dependências, bind, singleton e descoberta automática.
O problema que ele resolve
Imagine um controller que precisa de um service, que precisa de um repository, que precisa de uma conexão com o banco. Sem ajuda, você criaria tudo à mão, em ordem:
// Sem container: você monta a cadeia inteira, em todo lugar
$pdo = new PDO('mysql:host=localhost;dbname=loja', 'root', 'senha');
$repositorio = new PdoPedidoRepository($pdo);
$frete = new CalculadoraDeFrete();
$service = new CriarPedidoService($repositorio, $frete);
$controller = new PedidoController($service);
O container faz isso por você. Ele lê o construtor de cada classe, descobre do que ela precisa e cria tudo em cadeia. Esse processo se chama injeção de dependências: em vez de a classe criar o que usa, ela recebe pronto.
Criação automática
Para classes comuns (não interfaces), você não configura nada:
final class PedidoController
{
public function __construct(private readonly CriarPedidoService $criarPedido) {}
}
final class CriarPedidoService
{
public function __construct(private readonly CalculadoraDeFrete $frete) {}
}
// Ao chamar a rota, o Haki cria: CalculadoraDeFrete → CriarPedidoService → PedidoController
Funciona com qualquer profundidade e também nos middlewares, nas classes de validação e nos parâmetros dos métodos dos controllers.
Interfaces precisam de um bind
Quando uma classe pede uma interface, o container não tem como adivinhar qual implementação usar: pode haver várias (MySQL, arquivo, API externa). Você diz qual, uma vez, no bootstrap:
bootstrap/app.php
use App\Contracts\UsuarioRepositoryInterface;
use App\Repositories\PdoUsuarioRepository;
$app->container()->bind(UsuarioRepositoryInterface::class, PdoUsuarioRepository::class);
Lendo: "quando alguém pedir UsuarioRepositoryInterface, entregue um PdoUsuarioRepository". Se as suas classes seguem um padrão de nomes, dá para dispensar esse bind com a descoberta automática. Todas as classes que pedem a interface passam a receber essa implementação. Para trocar, você muda só essa linha.
Se você esquecer o bind, o erro explica o que fazer:
Não foi possível criar App\Contracts\UsuarioRepositoryInterface: a classe é uma interface.
Dica: Registre uma implementação: $app->container()->bind(UsuarioRepositoryInterface::class, SuaClasse::class);
Descoberta automática: sem bind para cada interface
Escrever um bind() para cada interface cansa. Se as suas classes seguem um padrão de nomes, o Haki encontra a implementação sozinho. O haki init já deixa isto no bootstrap/app.php:
Você cria a interface e a classe seguindo os nomes, e não escreve nenhum bind. Subpastas também funcionam: App\Contracts\Fiscal\NotaRepositoryInterface procura em App\Repositories\Fiscal\.
Outros padrões de nome
Se o seu projeto usa outro padrão, informe na chamada:
$app->container()->discover(
from: 'App\\Domain\\Contracts', // onde ficam as interfaces
to: 'App\\Infra\\Persistence', // onde ficam as classes
suffix: 'Contract', // parte removida do fim do nome da interface
prefix: '', // parte removida do começo (ex.: 'I')
patterns: ['Mysql{name}', '{name}'], // nomes procurados; {name} = nome sem prefixo/sufixo
);
O bind manual sempre vence. Para um caso fora do padrão, basta um bind(); o resto continua automático.
Nunca chuta. Se duas classes servirem (por exemplo, ProdutoRepository e PdoProdutoRepository), é erro, e a mensagem pede um bind para escolher.
A classe encontrada precisa implementar a interface. Uma classe com o nome certo, mas sem o implements, é recusada.
É opcional. Sem discover(), tudo funciona só com bind(), como antes.
Quando você erra um nome
O erro diz o que foi procurado e sugere a classe mais parecida que existe:
Nenhuma implementação encontrada para App\Contracts\ProdutoRepositoryInterface.
Procurei: App\Repositories\ProdutoRepository, App\Repositories\PdoProdutoRepository.
Dica: Você quis dizer App\Repositories\PdoProdutoRepositry? Renomeie a classe
para seguir o padrão ou faça um bind.
Conexão com banco, cliente HTTP, algo caro de criar
instance(A::class, $objeto)
Registra um objeto que você já criou
Testes, ou objetos montados fora do container
O segundo argumento é opcional quando é a própria classe: singleton(CalculadoraDeFrete::class) faz o container reaproveitar sempre o mesmo objeto dessa classe.
Criando com uma função
Quando o construtor precisa de valores (texto, número, configuração do .env), o container não tem como adivinhá-los. Ensine como criar com uma função:
bootstrap/app.php
use Haki\Support\Env;
$app->container()->singleton(PDO::class, function () {
return new PDO(
'mysql:host=' . Env::get('DB_HOST') . ';dbname=' . Env::get('DB_NAME'),
Env::get('DB_USER'),
Env::get('DB_PASS'),
[PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION],
);
});
A partir daí, qualquer repository que peça PDO $pdo no construtor recebe essa mesma conexão. A função também recebe o container, para pegar outras dependências:
use Haki\Container\Container;
$app->container()->bind(ServicoDeEmail::class, function (Container $c) {
return new ServicoDeEmail($c->get(ClienteSmtp::class), Env::get('EMAIL_REMETENTE'));
});
Parâmetros com valor padrão
Se um parâmetro do construtor não é uma classe mas tem valor padrão, o container usa o padrão. Isso é útil para configurações opcionais:
final class Cors implements MiddlewareInterface
{
public function __construct(private readonly string $origem = 'http://localhost:5173') {}
}
Pegando objetos do container
Normalmente o container trabalha sozinho, mas você pode pedir objetos a ele diretamente:
$container = $app->container();
$service = $container->get(CriarPedidoService::class); // cria (ou reaproveita, se singleton)
$container->has(UsuarioRepositoryInterface::class); // true se registrado ou se a classe existe
$novo = $container->build(CalculadoraDeFrete::class); // sempre cria um novo, ignorando registros
O Haki já registra, por conta própria: a aplicação (Haki), o Container, o Router, o Auth, o AuthConfig e o TokenStore. Qualquer classe pode recebê-los pelo construtor.
Erros comuns
Mensagem
Solução
"... a classe é uma interface."
Faça o bind() da interface no bootstrap.
"Não sei como injetar $x no construtor de Y."
O parâmetro é texto, número ou array sem valor padrão. Dê um padrão ou crie a classe com uma função (bind(Y::class, function () { ... })).
"Dependência circular detectada: A → B → A."
Duas classes pedem uma à outra no construtor. Separe a parte em comum em uma terceira classe.
"... a classe não existe."
Confira o namespace e rode composer dump-autoload.
SOLID na prática
Os cinco princípios aplicados à estrutura do Haki.
Por que se importar
SOLID são cinco princípios que deixam o código fácil de mudar sem quebrar o que já funciona. A estrutura de pastas recomendada já empurra você na direção certa. Veja como cada princípio aparece em um projeto Haki.
S: responsabilidade única
Cada classe tem um único motivo para mudar.
O controller lida com HTTP, o service com a regra de negócio e o repository com os dados. Se a regra de desconto mudar, você só mexe no service.
// Ruim: o controller faz tudo
public function store(Request $request): array
{
$pdo = new PDO('mysql:...');
$total = $request->input('valor') * 0.9; // regra de desconto escondida aqui
$pdo->prepare('INSERT INTO pedidos ...')->execute([...]);
return ['ok' => true];
}
// Bom: cada um no seu lugar
public function store(Request $request, Response $response): Response
{
$pedido = $this->criarPedido->executar($request->only(['produto_id', 'quantidade']));
return $response->json(['pedido' => $pedido], 201);
}
O: aberto para extensão
Adicione comportamento criando classes novas, sem editar as que já funcionam.
No Haki, isso aparece nos middlewares: para adicionar log, CORS ou limite de acesso, você cria um middleware novo e registra. Nenhum controller muda.
L: substituição
Qualquer implementação de uma interface deve funcionar no lugar da outra.
Um ArrayUsuarioRepository (para testes) e um PdoUsuarioRepository (produção) seguem o mesmo contrato. O service não percebe a troca.
I: interfaces enxutas
Prefira interfaces pequenas e específicas.
interface UsuarioRepositoryInterface
{
public function buscarPorId(int $id): ?Usuario;
public function buscarPorEmail(string $email): ?Usuario;
}
Se só o painel de relatórios precisa de estatísticas, crie uma RelatorioRepositoryInterface separada em vez de inchar essa.
D: dependa de abstrações
Classes de alto nível dependem de interfaces, não de implementações concretas.
O service pede UsuarioRepositoryInterface, e o bootstrap decide qual classe entregar. Para trocar de MySQL para uma API externa, você muda uma linha:
app/Models/Produto.php: os dados e o jsonSerialize().
Contrato
app/Contracts/ProdutoRepositoryInterface.php: os métodos de acesso a dados.
Repository
app/Repositories/PdoProdutoRepository.php: implementa a interface com SQL.
Service (se houver regra)
app/Services/CriarProdutoService.php: valida e aplica a regra de negócio.
Controller
app/Controllers/ProdutoController.php: lê a requisição, chama o service e retorna.
Bind e rotas
Um bind() no bootstrap e as rotas em routes/api.php.
Linha de comando
Todos os comandos do vendor/bin/haki.
Comandos disponíveis
O Haki instala o comando vendor/bin/haki. Rode sempre a partir da raiz do projeto (a pasta onde está o composer.json). Sem argumentos, ele lista os comandos:
php vendor/bin/haki
Haki 2.0.0
Uso: php vendor/bin/haki <comando> [opções]
Comandos:
init Cria a estrutura padrão do projeto (app, bootstrap, routes, public...); --force sobrescreve
make:request Cria uma classe de validação em app/Requests (ex.: make:request CriarClienteRequest)
check Confere interfaces, controllers e dependências antes de publicar
db Testa a conexão com o banco configurado no .env (DB_*)
key:generate Gera JWT_SECRET no .env (use --rsa para gerar chaves RS256, --force para sobrescrever)
auth:install Prepara o armazenamento de tokens
auth:clean Remove refresh tokens e revogações vencidos
init
Cria a estrutura padrão do projeto, com uma rota e um controller de exemplo, e configura o autoload do Composer.
Sem --force, arquivos que já existem são mantidos; só o que falta é criado. Por isso, rodar de novo é seguro, e serve para recriar uma pasta que você apagou. Veja o que é criado em Estrutura de pastas.
make:request
Cria uma classe de validação em app/Requests, já com o esqueleto pronto para preencher:
✔ criado app/Requests/CriarClienteRequest.php
Use no controller: public function store(CriarClienteRequest $request)
O nome precisa começar com letra maiúscula. Se o arquivo já existir, nada é sobrescrito, a menos que você use --force. Veja Validação.
check
Confere se a aplicação consegue montar tudo, sem precisar acessar cada rota: as interfaces encontradas pelo discover(), os controllers de cada rota e as dependências deles. Com $app->requireTypes() ativo, confere também a tipagem de todas as classes da pasta app/ (veja Tipagem).
php vendor/bin/haki check
Interfaces
✔ App\Contracts\ClienteRepositoryInterface → App\Repositories\PdoClienteRepository
✖ App\Contracts\ProdutoRepositoryInterface
Nenhuma implementação encontrada para App\Contracts\ProdutoRepositoryInterface. Procurei: ...
Você quis dizer App\Repositories\PdoProdutoRepositry? ...
Rotas
✔ GET / → App\Controllers\HomeController::index
✖ GET /produtos
Nenhuma implementação encontrada para App\Contracts\ProdutoRepositoryInterface. ...
✔ GET /clientes → App\Controllers\ClienteController::index
✖ 2 problemas encontrados.
Quando está tudo certo, a última linha é ✔ Tudo certo. e o comando termina com código 0. Com problemas, termina com código 1. Isso permite usá-lo antes de cada deploy ou num pipeline de CI para barrar código quebrado.
Nota
Para conferir de verdade, o check carrega o bootstrap/app.php e cria cada controller com as dependências, como aconteceria numa requisição. Se um repository abre a conexão com o banco no construtor, o banco precisa estar acessível.
db
Testa a conexão com o banco de dados configurado no .env. Use quando configurar o projeto pela primeira vez, ao trocar de servidor ou quando a API começar a dar erro de banco.
php vendor/bin/haki db
conectou
✔ Conectado ao banco.
Driver: mysql
Banco: root@127.0.0.1:3306/loja
Versão: MySQL 8.0.36
Tabelas: clientes, pedidos, produtos
Tempo: 4.2 ms
não conectou
✖ Não foi possível conectar: SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost'
Usuário ou senha incorretos. Confira DB_USERNAME e DB_PASSWORD.
O comando lê estas variáveis do .env:
.env
# SQLite (um arquivo, não precisa de servidor)
DB_CONNECTION=sqlite
DB_DATABASE=database/app.sqlite
# MySQL
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=loja
DB_USERNAME=root
DB_PASSWORD=senha
Problema
O que o comando diz
DB_CONNECTION faltando
Mostra as linhas que precisam ser adicionadas
Extensão pdo_mysql ou pdo_sqlite desativada
Qual linha ativar no php.ini
Arquivo SQLite inexistente
Avisa, em vez de criar um banco vazio sem você perceber
Usuário ou senha errados (MySQL 1045)
Confira DB_USERNAME e DB_PASSWORD
Banco inexistente (MySQL 1049)
Crie o banco ou corrija DB_DATABASE
Servidor desligado ou porta errada (MySQL 2002)
Confira se o MySQL está ligado e DB_HOST/DB_PORT
Como o check, termina com código 0 quando conecta e 1 quando falha, então pode ser usado num script de deploy.
Nota
As variáveis DB_* são usadas pelo comando db e pelo EloPHP. Com DB_CONNECTION=mysql, elas também configuram automaticamente o armazenamento de tokens JWT.
key:generate
Gera um segredo aleatório e forte para os tokens e grava no .env como JWT_SECRET. Se o .env não existir, ele é criado.
php vendor/bin/haki key:generate
php vendor/bin/haki key:generate --force # troca um segredo que já existe
php vendor/bin/haki key:generate --rsa # gera as chaves RS256 em storage/keys/
Trocar o segredo desconecta todos
Os tokens já emitidos foram assinados com o segredo antigo e deixam de valer. Por isso o comando se recusa a sobrescrever sem o --force. Use cada segredo em um só ambiente: o de desenvolvimento nunca deve ser o mesmo da produção.
auth:install
Prepara as tabelas de tokens no MySQL configurado ou no SQLite padrão. Elas também são criadas no primeiro uso; rodar no deploy ajuda a detectar problemas de permissão ou extensão.
php vendor/bin/haki auth:install
✔ Banco de tokens pronto em /var/www/minha-api/storage/haki.sqlite
auth:clean
Apaga refresh tokens e revogações que já venceram. A limpeza também acontece sozinha de vez em quando; o comando serve para agendar em um cron:
Os comandos são os mesmos no PowerShell e no Prompt de Comando: php vendor/bin/haki init. Se aparecer "php não é reconhecido como um comando", o PHP não está no PATH do sistema: adicione a pasta do PHP (por exemplo, C:\php) às variáveis de ambiente e abra o terminal de novo.
Testes
Testar a API inteira com PHPUnit, sem servidor.
Por que testar
Um teste automatizado é um código que chama a sua API e confere se a resposta está certa. Depois de escrito, ele roda em segundos, quantas vezes você quiser. Assim, quando você muda uma parte do código, descobre na hora se quebrou outra.
No Haki, dá para testar a API inteira sem subir servidor: $app->handle() processa uma requisição e devolve a resposta, como se ela tivesse vindo da internet.
Configurando o PHPUnit
Instale o PHPUnit
composer require --dev phpunit/phpunit
O --dev indica que ele só é usado em desenvolvimento e não vai para a produção.
<?php
declare(strict_types=1);
namespace Tests;
use Haki\Http\Request;
use PHPUnit\Framework\TestCase;
final class HomeTest extends TestCase
{
public function testHomeResponde(): void
{
// 1. Carrega a aplicação, como o public/index.php faz
$app = require __DIR__ . '/../bootstrap/app.php';
// 2. Monta uma requisição e processa
$response = $app->handle(Request::create('GET', '/'));
// 3. Confere a resposta
$this->assertSame(200, $response->getStatus());
$this->assertSame('Bem-vindo ao Haki!', $response->getJson()['mensagem']);
}
}
OK (1 test, 2 assertions)
Montando requisições
Request::create('GET', '/produtos?busca=espada'); // com query string
Request::create('POST', '/produtos', ['nome' => 'Gomu', 'preco' => 9.9]); // corpo JSON
Request::create('GET', '/eu', [], ['Authorization' => 'Bearer ...']); // com cabeçalhos
E para conferir a resposta: getStatus(), getJson(), getBody() e getHeader('Nome').
Graças às interfaces, você pode trocar um repository que acessa o banco por um que guarda tudo em memória, só no teste:
$app = require __DIR__ . '/../bootstrap/app.php';
$app->container()->instance(UsuarioRepositoryInterface::class, new ArrayUsuarioRepository());
Assim, os testes rodam rápido, não precisam de banco e não sujam dados reais.
O que testar primeiro
Comece pelo que mais dói se quebrar: login, rotas protegidas (401 e 403) e as validações dos cadastros. Um teste para cada caso de erro importante vale mais que muitos testes do caminho feliz.
Produção e segurança
O que conferir antes de colocar a API no ar.
Lista de verificação
Antes de colocar a API no ar, confira cada item. Ao lado, o porquê:
Item
Por quê
APP_ENV=production (ou ausente)
Em desenvolvimento, os erros mostram caminhos de arquivos e mensagens internas.
Servidor web apontando para public/
Se apontar para a raiz, qualquer pessoa pode baixar o .env e o banco de tokens.
HTTPS obrigatório
Sem ele, os tokens e senhas viajam abertos e podem ser lidos por quem estiver na mesma rede.
JWT_SECRET próprio da produção
Gerado com key:generate no servidor, diferente do de desenvolvimento.
.env, storage/*.sqlite* e storage/keys/ fora do Git
São segredos. O .gitignore do init já cuida disso.
storage/ com permissão de escrita
O banco de tokens fica ali.
Extensão PDO do banco de tokens ativa
Use pdo_mysql para o MySQL automático ou pdo_sqlite para o armazenamento SQLite.
Nenhum haki() esquecido
A saída do dump quebra o JSON das respostas.
CORS liberando só o seu domínio
Liberar * permite que qualquer site chame a sua API pelo navegador.
Passos de um deploy
Envie o código e instale as dependências
composer install --no-dev --optimize-autoloader
--no-dev deixa de fora o que só serve em desenvolvimento (como o PHPUnit), e --optimize-autoloader deixa o carregamento das classes mais rápido.
Depois, preencha o resto (banco, APP_ENV=production...).
Prepare o banco de tokens
php vendor/bin/haki auth:install
Configure o servidor web
Aponte para public/ e redirecione tudo para o index.php. Veja os exemplos de Nginx e Apache.
Agende a limpeza com auth:clean em um cron (veja auth:clean).
Desempenho
Ative o OPcache no php.ini (opcache.enable=1). Ele guarda o código PHP já compilado e é o ganho de velocidade mais simples que existe.
Use --optimize-autoloader no composer install.
Rotas públicas não tocam no banco de tokens. Rotas protegidas fazem uma consulta rápida a ele por requisição.
Onde o cliente guarda os tokens
Cliente
Recomendação
App mobile
Armazenamento seguro do sistema: Keychain no iOS, Keystore no Android (no React Native, bibliotecas como expo-secure-store).
Front-end web (SPA)
Access token em memória (uma variável). Evite localStorage para o refresh token: um ataque XSS consegue lê-lo.
Outro servidor
Variável de ambiente ou cofre de segredos.
Trocando o segredo
Trocar o JWT_SECRET (ou as chaves RSA) invalida todos os tokens existentes, e todos os usuários precisam fazer login de novo. Faça isso se suspeitar de vazamento:
php vendor/bin/haki key:generate --force
Proteja o login contra força bruta
O Haki não limita tentativas de login. Sem limite, alguém pode testar milhares de senhas por minuto. Algumas formas de resolver:
Configurar limite de requisições no servidor web ou proxy (Nginx limit_req, Cloudflare).
Criar um middleware que conte as tentativas por IP ($request->ip()) e responda 429 ao passar do limite, guardando a contagem em Redis ou no banco.
Bloquear temporariamente a conta depois de várias senhas erradas seguidas.
Logs
Em produção, erros 500 são registrados no log do PHP (error_log) com a exceção, o arquivo e a linha, enquanto o cliente vê só "Erro interno do servidor". Confira onde o seu servidor guarda esse log (a diretiva error_log do php.ini) e acompanhe-o depois de cada deploy.
Exemplo completo
Uma API de loja completa, com banco, login e permissões.
O que vamos construir
A API de uma loja, com banco de dados de verdade: as pessoas se cadastram, fazem login e veem os produtos; só administradores criam, alteram e apagam produtos. Todo o código desta página foi rodado e testado.
Depois, apague o app/Controllers/HomeController.php de exemplo e deixe o .env assim (o JWT_SECRET é o que o key:generate gerou):
APP_ENV=development
JWT_SECRET=(o valor gerado)
DB_CONNECTION=sqlite
DB_DATABASE=database/loja.sqlite
2. Banco de dados
A estrutura das tabelas e um script que as cria, já com um administrador:
database/schema.sql
CREATE TABLE IF NOT EXISTS usuarios (
id INTEGER PRIMARY KEY AUTOINCREMENT,
nome TEXT NOT NULL,
email TEXT NOT NULL UNIQUE,
senha_hash TEXT NOT NULL,
perfil TEXT NOT NULL DEFAULT 'cliente'
);
CREATE TABLE IF NOT EXISTS produtos (
id INTEGER PRIMARY KEY AUTOINCREMENT,
nome TEXT NOT NULL,
preco REAL NOT NULL,
estoque INTEGER NOT NULL DEFAULT 0
);
database/criar.php
<?php
declare(strict_types=1);
// Cria as tabelas e um administrador. Rode na raiz do projeto: php database/criar.php
use App\Database\Connection;
use Haki\Support\Env;
require __DIR__ . '/../vendor/autoload.php';
$raiz = dirname(__DIR__);
Env::load($raiz . '/.env');
$pdo = Connection::fromEnv($raiz)->pdo();
$pdo->exec((string) file_get_contents(__DIR__ . '/schema.sql'));
$existe = $pdo->prepare('SELECT 1 FROM usuarios WHERE email = ?');
$existe->execute(['admin@loja.com']);
if ($existe->fetchColumn() === false) {
$pdo->prepare('INSERT INTO usuarios (nome, email, senha_hash, perfil) VALUES (?, ?, ?, ?)')
->execute(['Administrador', 'admin@loja.com', password_hash('segredo123', PASSWORD_DEFAULT), 'admin']);
}
echo 'Banco pronto. Administrador: admin@loja.com / segredo123' . PHP_EOL;
<?php
declare(strict_types=1);
namespace App\Database;
use Haki\Support\Env;
use PDO;
use RuntimeException;
/**
* Conexão com o banco, configurada pelas variáveis DB_* do .env.
* A conexão só é aberta na primeira vez que pdo() é chamado.
*/
final class Connection
{
private ?PDO $pdo = null;
public function __construct(
private readonly string $driver,
private readonly string $database,
private readonly string $host = '127.0.0.1',
private readonly int $port = 3306,
private readonly ?string $username = null,
#[\SensitiveParameter] private readonly ?string $password = null,
) {
}
public static function fromEnv(string $basePath): self
{
$driver = (string) Env::get('DB_CONNECTION', 'sqlite');
$database = (string) Env::get('DB_DATABASE', 'database/app.sqlite');
if ($driver === 'sqlite' && !preg_match('#^([A-Za-z]:[\\\\/]|/)#', $database)) {
$database = rtrim($basePath, '/\\') . DIRECTORY_SEPARATOR . $database;
}
return new self(
$driver,
$database,
(string) Env::get('DB_HOST', '127.0.0.1'),
(int) Env::get('DB_PORT', 3306),
Env::get('DB_USERNAME'),
Env::get('DB_PASSWORD'),
);
}
public function pdo(): PDO
{
return $this->pdo ??= $this->connect();
}
private function connect(): PDO
{
$options = [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
];
return match ($this->driver) {
'sqlite' => new PDO('sqlite:' . $this->database, null, null, $options),
'mysql' => new PDO(
"mysql:host={$this->host};port={$this->port};dbname={$this->database};charset=utf8mb4",
$this->username,
$this->password,
$options,
),
default => throw new RuntimeException("DB_CONNECTION \"{$this->driver}\" não suportado. Use sqlite ou mysql."),
};
}
}
php database/criar.php
php vendor/bin/haki db
3. Models
O Usuario implementa JsonSerializable para que o hash da senha nunca apareça nas respostas. O Produto só tem os dados.
app/Models/Usuario.php
<?php
declare(strict_types=1);
namespace App\Models;
use JsonSerializable;
final class Usuario implements JsonSerializable
{
public function __construct(
public readonly int $id,
public readonly string $nome,
public readonly string $email,
public readonly string $senhaHash,
public readonly string $perfil,
) {
}
public function senhaConfere(string $senha): bool
{
return password_verify($senha, $this->senhaHash);
}
/** O hash da senha nunca vai para o JSON. */
public function jsonSerialize(): array
{
return ['id' => $this->id, 'nome' => $this->nome, 'email' => $this->email, 'perfil' => $this->perfil];
}
}
app/Models/Produto.php
<?php
declare(strict_types=1);
namespace App\Models;
final class Produto
{
public function __construct(
public readonly int $id,
public readonly string $nome,
public readonly float $preco,
public readonly int $estoque,
) {
}
}
4. Interfaces e repositories
Os nomes seguem o padrão do discover(), então nenhum bind é necessário.
app/Contracts/UsuarioRepositoryInterface.php
<?php
declare(strict_types=1);
namespace App\Contracts;
use App\Models\Usuario;
interface UsuarioRepositoryInterface
{
public function buscarPorEmail(string $email): ?Usuario;
public function criar(string $nome, string $email, string $senhaHash): Usuario;
}
app/Contracts/ProdutoRepositoryInterface.php
<?php
declare(strict_types=1);
namespace App\Contracts;
use App\Models\Produto;
interface ProdutoRepositoryInterface
{
/** @return list<Produto> */
public function listar(int $pagina, int $porPagina): array;
public function buscar(int $id): ?Produto;
public function criar(string $nome, float $preco, int $estoque): Produto;
public function atualizar(int $id, string $nome, float $preco, int $estoque): void;
public function apagar(int $id): bool;
}
app/Repositories/PdoUsuarioRepository.php
<?php
declare(strict_types=1);
namespace App\Repositories;
use App\Contracts\UsuarioRepositoryInterface;
use App\Database\Connection;
use App\Models\Usuario;
use PDO;
final class PdoUsuarioRepository implements UsuarioRepositoryInterface
{
private readonly PDO $pdo;
public function __construct(Connection $connection)
{
$this->pdo = $connection->pdo();
}
public function buscarPorEmail(string $email): ?Usuario
{
$stmt = $this->pdo->prepare('SELECT * FROM usuarios WHERE email = ?');
$stmt->execute([$email]);
$linha = $stmt->fetch();
if (!$linha) {
return null;
}
return new Usuario((int) $linha['id'], $linha['nome'], $linha['email'], $linha['senha_hash'], $linha['perfil']);
}
public function criar(string $nome, string $email, string $senhaHash): Usuario
{
$stmt = $this->pdo->prepare('INSERT INTO usuarios (nome, email, senha_hash) VALUES (?, ?, ?)');
$stmt->execute([$nome, $email, $senhaHash]);
return new Usuario((int) $this->pdo->lastInsertId(), $nome, $email, $senhaHash, 'cliente');
}
}
app/Repositories/PdoProdutoRepository.php
<?php
declare(strict_types=1);
namespace App\Repositories;
use App\Contracts\ProdutoRepositoryInterface;
use App\Database\Connection;
use App\Models\Produto;
use PDO;
final class PdoProdutoRepository implements ProdutoRepositoryInterface
{
private readonly PDO $pdo;
public function __construct(Connection $connection)
{
$this->pdo = $connection->pdo();
}
public function listar(int $pagina, int $porPagina): array
{
$stmt = $this->pdo->prepare('SELECT * FROM produtos ORDER BY id LIMIT :limite OFFSET :inicio');
$stmt->bindValue(':limite', $porPagina, PDO::PARAM_INT);
$stmt->bindValue(':inicio', ($pagina - 1) * $porPagina, PDO::PARAM_INT);
$stmt->execute();
$produtos = [];
foreach ($stmt->fetchAll() as $linha) {
$produtos[] = new Produto((int) $linha['id'], $linha['nome'], (float) $linha['preco'], (int) $linha['estoque']);
}
return $produtos;
}
public function buscar(int $id): ?Produto
{
$stmt = $this->pdo->prepare('SELECT * FROM produtos WHERE id = ?');
$stmt->execute([$id]);
$linha = $stmt->fetch();
if (!$linha) {
return null;
}
return new Produto((int) $linha['id'], $linha['nome'], (float) $linha['preco'], (int) $linha['estoque']);
}
public function criar(string $nome, float $preco, int $estoque): Produto
{
$stmt = $this->pdo->prepare('INSERT INTO produtos (nome, preco, estoque) VALUES (?, ?, ?)');
$stmt->execute([$nome, $preco, $estoque]);
return new Produto((int) $this->pdo->lastInsertId(), $nome, $preco, $estoque);
}
public function atualizar(int $id, string $nome, float $preco, int $estoque): void
{
$stmt = $this->pdo->prepare('UPDATE produtos SET nome = ?, preco = ?, estoque = ? WHERE id = ?');
$stmt->execute([$nome, $preco, $estoque, $id]);
}
public function apagar(int $id): bool
{
$stmt = $this->pdo->prepare('DELETE FROM produtos WHERE id = ?');
$stmt->execute([$id]);
return $stmt->rowCount() > 0;
}
}
5. Validação
O CadastroRequest usa o repository no check() para recusar e-mails repetidos, e o prepare() para padronizar o e-mail em minúsculas.
app/Requests/CadastroRequest.php
<?php
declare(strict_types=1);
namespace App\Requests;
use App\Contracts\UsuarioRepositoryInterface;
use Haki\Validation\FormRequest;
use Haki\Validation\Rule;
final class CadastroRequest extends FormRequest
{
public function __construct(private readonly UsuarioRepositoryInterface $usuarios)
{
}
public function rules(Rule $rule): array
{
return [
'nome' => $rule->text()->length(3, 100),
'email' => $rule->email(),
'senha' => $rule->text()->length(8, 72),
'senha_confirmacao' => $rule->text()->same('senha'),
];
}
protected function prepare(array $data): array
{
$data['email'] = strtolower(trim((string) ($data['email'] ?? '')));
return $data;
}
protected function check(array $data): void
{
if ($this->usuarios->buscarPorEmail($data['email']) !== null) {
$this->fail('email', 'Este e-mail já está cadastrado.');
}
}
}
app/Requests/LoginRequest.php
<?php
declare(strict_types=1);
namespace App\Requests;
use Haki\Validation\FormRequest;
use Haki\Validation\Rule;
final class LoginRequest extends FormRequest
{
public function rules(Rule $rule): array
{
return [
'email' => $rule->email(),
'senha' => $rule->text(),
];
}
}
app/Requests/ProdutoRequest.php
<?php
declare(strict_types=1);
namespace App\Requests;
use Haki\Validation\FormRequest;
use Haki\Validation\Rule;
final class ProdutoRequest extends FormRequest
{
public function rules(Rule $rule): array
{
return [
'nome' => $rule->text()->length(3, 100),
'preco' => $rule->number()->min(0.01),
'estoque' => $rule->integer()->min(0)->optional(0),
];
}
public function labels(): array
{
return ['preco' => 'preço'];
}
}
6. Service de login
app/Services/LoginService.php
<?php
declare(strict_types=1);
namespace App\Services;
use App\Contracts\UsuarioRepositoryInterface;
use App\Models\Usuario;
use Haki\Exceptions\HttpException;
final class LoginService
{
public function __construct(private readonly UsuarioRepositoryInterface $usuarios)
{
}
public function autenticar(string $email, string $senha): Usuario
{
$usuario = $this->usuarios->buscarPorEmail(strtolower($email));
// Mesma mensagem nos dois casos: não revela quais e-mails existem.
if ($usuario === null || !$usuario->senhaConfere($senha)) {
throw new HttpException(401, 'E-mail ou senha incorretos');
}
return $usuario;
}
}
7. Controllers
app/Controllers/AuthController.php
<?php
declare(strict_types=1);
namespace App\Controllers;
use App\Contracts\UsuarioRepositoryInterface;
use App\Requests\CadastroRequest;
use App\Requests\LoginRequest;
use App\Services\LoginService;
use Haki\Auth\Auth;
use Haki\Http\Request;
use Haki\Http\Response;
final class AuthController
{
public function __construct(
private readonly UsuarioRepositoryInterface $usuarios,
private readonly LoginService $login,
) {
}
// POST /cadastro
public function cadastro(CadastroRequest $request, Response $response): Response
{
$usuario = $this->usuarios->criar(
$request->nome,
$request->email,
password_hash($request->senha, PASSWORD_DEFAULT),
);
return $response->json(['usuario' => $usuario], 201);
}
// POST /login
public function login(LoginRequest $request, Auth $auth): array
{
$usuario = $this->login->autenticar($request->email, $request->senha);
return $auth->login($usuario->id, ['role' => $usuario->perfil, 'nome' => $usuario->nome]);
}
// POST /refresh
public function refresh(Request $request, Auth $auth): array
{
return $auth->refresh($request->input('refresh_token'));
}
// POST /logout (protegida)
public function logout(Request $request, Auth $auth): null
{
$auth->logout($request);
return null;
}
// GET /eu (protegida)
public function eu(Request $request): array
{
return ['usuario' => $request->user()];
}
}
app/Controllers/ProdutoController.php
<?php
declare(strict_types=1);
namespace App\Controllers;
use App\Contracts\ProdutoRepositoryInterface;
use App\Models\Produto;
use App\Requests\ProdutoRequest;
use Haki\Exceptions\HttpException;
use Haki\Http\Request;
use Haki\Http\Response;
final class ProdutoController
{
public function __construct(private readonly ProdutoRepositoryInterface $produtos)
{
}
// GET /produtos?pagina=1
public function index(Request $request): array
{
$pagina = max(1, (int) $request->query('pagina', 1));
return ['pagina' => $pagina, 'produtos' => $this->produtos->listar($pagina, 20)];
}
// GET /produtos/{id}
public function show(int $id): array
{
return ['produto' => $this->encontrar($id)];
}
// POST /produtos (admin)
public function store(ProdutoRequest $request, Response $response): Response
{
$produto = $this->produtos->criar($request->nome, $request->preco, $request->estoque);
return $response->json(['produto' => $produto], 201);
}
// PUT /produtos/{id} (admin)
public function update(int $id, ProdutoRequest $request): array
{
$this->encontrar($id);
$this->produtos->atualizar($id, $request->nome, $request->preco, $request->estoque);
return ['produto' => $this->encontrar($id)];
}
// DELETE /produtos/{id} (admin)
public function destroy(int $id): null
{
if (!$this->produtos->apagar($id)) {
throw new HttpException(404, 'Produto não encontrado');
}
return null;
}
private function encontrar(int $id): Produto
{
return $this->produtos->buscar($id) ?? throw new HttpException(404, 'Produto não encontrado');
}
}
8. Bootstrap e rotas
bootstrap/app.php
<?php
declare(strict_types=1);
use App\Database\Connection;
use Haki\Haki;
require __DIR__ . '/../vendor/autoload.php';
$app = new Haki(dirname(__DIR__));
// Banco de dados: uma conexão só, configurada pelas variáveis DB_* do .env.
$app->container()->singleton(Connection::class, function () use ($app) {
return Connection::fromEnv($app->basePath());
});
// Interfaces de app/Contracts ligadas às classes de app/Repositories pelo nome.
$app->container()->discover('App\\Contracts', 'App\\Repositories');
// Exige tipagem em todo o código do projeto.
$app->requireTypes();
// Rotas
$app->routes(__DIR__ . '/../routes/api.php');
return $app;
routes/api.php
<?php
declare(strict_types=1);
use App\Controllers\AuthController;
use App\Controllers\ProdutoController;
use Haki\Haki;
/** @var Haki $app */
// Públicas
$app->post('/cadastro', [AuthController::class, 'cadastro']);
$app->post('/login', [AuthController::class, 'login']);
$app->post('/refresh', [AuthController::class, 'refresh']);
$app->get('/produtos', [ProdutoController::class, 'index']);
$app->get('/produtos/{id}', [ProdutoController::class, 'show']);
// Qualquer usuário logado
$app->group('/', function (Haki $app) {
$app->get('/eu', [AuthController::class, 'eu']);
$app->post('/logout', [AuthController::class, 'logout']);
})->auth();
// Só administradores
$app->group('/produtos', function (Haki $app) {
$app->post('/', [ProdutoController::class, 'store']);
$app->put('/{id}', [ProdutoController::class, 'update']);
$app->delete('/{id}', [ProdutoController::class, 'destroy']);
})->role('admin');
9. Rodando e testando
php vendor/bin/haki check
php -S localhost:8000 -t public
# Cadastro
curl -X POST localhost:8000/cadastro -H "Content-Type: application/json" \
-d '{"nome":"Nami","email":"nami@exemplo.com","senha":"tangerina1","senha_confirmacao":"tangerina1"}'
# Login do administrador (guarde o access_token)
curl -X POST localhost:8000/login -H "Content-Type: application/json" \
-d '{"email":"admin@loja.com","senha":"segredo123"}'
# Criar produto como admin
curl -X POST localhost:8000/produtos -H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{"nome":"Mapa da Grand Line","preco":89.5,"estoque":25}'
# Listar (público)
curl localhost:8000/produtos
Próximos passos
Para continuar: adicione categorias aos produtos (uma tabela nova, uma model, uma interface, um repository), crie testes para as rotas (veja Testes) e confira a lista de Produção e segurança antes de publicar.
Problemas comuns
Os erros mais comuns, organizados pela mensagem que você vê.
Os erros que mais aparecem, organizados pelo que você vê na tela. Use a busca (Ctrl + K) com um trecho da mensagem para chegar direto.
Antes de tudo
Deixe APP_ENV=development no .env enquanto desenvolve: assim cada erro vem com uma dica explicando a causa. E rode php vendor/bin/haki check e php vendor/bin/haki db: eles encontram boa parte dos problemas abaixo sozinhos.
Instalação
"The zip extension and unzip/7z commands are both missing"
Causa: o Composer baixa os pacotes compactados e o PHP está sem a extensão zip. A pasta vendor/ não é criada.
Solução: no php.ini (veja onde está com php --ini), troque ;extension=zip por extension=zip, abra o terminal de novo e rode composer require shankscode/haki outra vez.
"php não é reconhecido como um comando"
Causa: a pasta do PHP não está no PATH do Windows.
Solução: adicione a pasta (por exemplo, C:\php) às variáveis de ambiente do sistema, em Configurações → Sistema → Sobre → Configurações avançadas → Variáveis de Ambiente, e abra o terminal de novo.
"Your requirements could not be resolved" / "php ^8.2"
Causa: a versão do PHP é anterior à 8.2.
Solução: confira com php -v e atualize o PHP.
Classes e autoload
"Class ... not found" / "a classe não existe"
Causas mais comuns, nesta ordem:
O namespace do arquivo não bate com a pasta. Em app/Controllers/ProdutoController.php, precisa ser namespace App\Controllers;.
O nome da classe não é igual ao nome do arquivo (atenção às maiúsculas: ProdutoController ≠ produtoController).
Faltou o use App\...; no arquivo que usa a classe.
O composer.json não tem o autoload de App\, ou ele foi editado sem rodar composer dump-autoload.
Em desenvolvimento, a mensagem do Haki costuma trazer "Você quis dizer ...?" com o nome mais parecido que existe.
"... a classe é uma interface" / "Nenhuma implementação encontrada"
Causa: o controller pede uma interface e o Haki não sabe qual classe entregar.
Solução: confira se o bootstrap/app.php tem o discover('App\\Contracts', 'App\\Repositories') e se os nomes seguem o padrão (ProdutoRepositoryInterface → ProdutoRepository ou PdoProdutoRepository). Para nomes fora do padrão, use bind(). Veja Descoberta automática.
"Tipagem obrigatória: ... tem N problemas"
Causa: o bootstrap/app.php tem $app->requireTypes() e uma classe do projeto tem parâmetro, retorno ou propriedade sem tipo, ou não tem declare(strict_types=1).
Solução: a mensagem diz a classe, o método e a linha. Adicione os tipos e confira tudo com php vendor/bin/haki check. Veja Tipagem.
"Não sei como injetar $x em ..."
Causa: um parâmetro do método (ou do construtor) não é uma classe e não é um parâmetro da rota.
Solução: se é um valor da URL, o nome precisa ser igual ao da rota ({id} → $id). Se é configuração, dê um valor padrão ou crie a classe com uma função no container. Veja Criando com uma função.
Rotas e servidor
Toda rota dá 404 (menos a página inicial)
Causa: o servidor web não está mandando as requisições para o public/index.php.
Solução: com o servidor do PHP, use php -S localhost:8000 -t public (o -t public é obrigatório). No Apache, crie o public/.htaccess; no Nginx, configure o try_files. Veja Servidores web.
"Rota não encontrada" numa rota que existe
Causas: o método HTTP não é o mesmo (a rota é post e você chamou com GET, o que daria 405), o caminho tem um erro de digitação, ou o arquivo de rotas não foi carregado no bootstrap ($app->routes(...)).
Solução: leia a dica do erro: ela sugere rotas parecidas. E rode php vendor/bin/haki check para ver a lista de rotas registradas.
"Método não permitido" (405)
Causa: o caminho existe, mas com outro método. O cabeçalho Allow da resposta lista os métodos aceitos.
A resposta começa com HTML (ou um bloco escuro) antes do JSON
Causa: um haki(), echo, var_dump ou print_r esquecido no código. Também pode ser um espaço ou linha em branco antes do <?php em algum arquivo.
Solução: procure por haki(, echo e var_dump no projeto, e confira se todo arquivo começa exatamente com <?php.
Dados enviados
input() sempre devolve null
Causa: o cliente enviou JSON sem o cabeçalho Content-Type: application/json, então o corpo não foi lido como JSON.
Solução: envie o cabeçalho. No curl: -H "Content-Type: application/json"; no fetch: headers: { 'Content-Type': 'application/json' }. Para conferir o que chegou, use haki($request->all(), $request->headers()).
"JSON inválido no corpo da requisição" (400)
Causa: o corpo tem um erro de sintaxe (vírgula sobrando, aspas simples no lugar de duplas, chave sem aspas). A dica diz qual foi o erro.
Se a dica for "Malformed UTF-8 characters" e o texto tiver acentos, o problema é a codificação de quem enviou: alguns terminais do Windows (como o Git Bash) mandam o "é" fora do padrão UTF-8. Salve o JSON num arquivo UTF-8 e envie com curl --data-binary @dados.json, ou use Insomnia, Postman ou o próprio front-end, que enviam em UTF-8.
Recebo 422 e não entendo por quê
Causa: a validação recusou os dados. O campo campos da resposta diz exatamente o que está errado em cada campo.
Lembre que todo campo é obrigatório, a menos que tenha ->optional(), e que "" (texto vazio) conta como não enviado. Veja Obrigatório e opcional.
"O campo \"x\" não existe em ...Request"
Causa: você usou $request->x numa classe de validação, mas x não está em rules(). Só os campos declarados ficam disponíveis.
Solução: adicione o campo em rules() (com ->optional(), se ele puder faltar).
Login e tokens
"Token não informado" mesmo enviando o token
Causas:
Faltou a palavra Bearer e o espaço. O certo é Authorization: Bearer eyJ....
No Apache, o cabeçalho Authorization é descartado. Adicione ao public/.htaccess as linhas mostradas em Apache.
"Token inválido ou expirado"
A dica (em desenvolvimento) diz o motivo exato:
Dica
O que fazer
"Token expirado."
Normal depois de 15 minutos. Renove com o refresh token (veja o fluxo no cliente).
"Assinatura inválida"
O token foi gerado com outro JWT_SECRET (por exemplo, o segredo foi trocado, ou o token é de outro ambiente). Faça login de novo.
"Token revogado (logout)."
O usuário fez logout com esse token. Faça login de novo.
"Token malformado"
O valor enviado não é um token completo: confira se não foi cortado ou se não enviou o refresh token no lugar do access token.
"O segredo JWT não foi definido" / "precisa ter pelo menos 32 caracteres"
Solução: rode php vendor/bin/haki key:generate. Ele grava um segredo forte no .env.
"Acesso negado" (403) para quem deveria ter acesso
Causa: o perfil no token é diferente do exigido pelo ->role(). A comparação é exata (Admin ≠ admin), e o perfil fica gravado no token no momento do login.
Solução: confira o valor em GET /eu e, se o perfil mudou, faça login de novo.
"A extensão pdo_sqlite não está ativa"
Causa: o login guarda os tokens num SQLite, e a extensão está desativada.
Solução: ative extension=pdo_sqlite no php.ini.
Banco de dados
Mensagem
Solução
"could not find driver"
Ative pdo_sqlite ou pdo_mysql no php.ini.
"no such table"
Crie as tabelas (php database/criar.php) e confira o arquivo com php vendor/bin/haki db.
"Access denied for user"
Usuário ou senha do MySQL errados no .env.
"Unknown database"
Crie o banco no MySQL ou corrija DB_DATABASE.
"UNIQUE constraint failed" / "Duplicate entry"
Valor repetido numa coluna única. Confira antes, na validação.
Causa: o front-end está em outro endereço (por exemplo, localhost:5173) e a API não autorizou esse endereço.
Solução: crie o middleware de CORS e registre como o primeiro middleware global, com o endereço do seu front-end. Veja Exemplo: CORS. Se o erro só aparece em requisições com token, confira se o middleware responde ao OPTIONS e libera o cabeçalho Authorization.
Em produção só aparece "Erro interno do servidor"
Causa: em produção, os detalhes nunca vão para o cliente, de propósito.
Solução: leia o log do PHP no servidor (o caminho está na diretiva error_log do php.ini): o erro completo, com arquivo e linha, está lá.
Referência da API
Todos os métodos públicos do Haki, classe por classe.
Esta página lista tudo o que o Haki oferece, classe por classe. Use-a para consultar rapidamente um método. As outras páginas explicam cada assunto com calma e com exemplos.
Haki
Haki\Haki: a aplicação. É criada no bootstrap/app.php.
Método
Faz
new Haki(?string $basePath = null, ?bool $debug = null)
Cria a aplicação e carrega o .env da raiz. Veja os argumentos.
get / post / put / patch / delete($caminho, $handler)
Qual classe o discover() encontra para a interface.
bound($id)
true se há um bind, singleton ou instance para o id.
requireTypes() / assertTyped($classe)
Liga a tipagem obrigatória / confere uma classe (lança TypeCheckException).
$implementacao pode ser o nome de uma classe ou uma função: function (Container $c) { return new ...; }.
MiddlewareInterface
namespace Haki\Middleware;
interface MiddlewareInterface
{
public function handle(Request $request, callable $next): Response;
}
Um middleware pode ser uma classe que implementa essa interface, o nome dela (Cors::class) ou uma função anônima function (Request $request, callable $next) { ... }. Veja Middleware.
Auth
Haki\Auth\Auth: peça um parâmetro Auth $auth no controller.
Método
Faz
login($idUsuario, array $claims = [])
Emite access e refresh token. Retorna access_token, refresh_token, token_type e expires_in.
refresh(?string $refreshToken)
Troca um refresh token por um par novo (com rotação).
logout(Request $request)
Revoga a sessão atual. Use em rota com ->auth().
logoutAll($idUsuario)
Revoga todas as sessões do usuário.
authenticate(string $token)
Valida um access token e retorna a Identity. Veja validação manual.
Identity
Haki\Auth\Identity: o usuário autenticado, devolvido por $request->user().
Membro
Retorna
->id
ID do usuário (texto).
->role
Perfil, ou null.
->claims
Todos os claims do token.
get($claim, $padrao = null)
Um claim específico.
hasRole(...$perfis)
true se tiver um dos perfis.
Convertida em JSON, mostra id, role e os claims extras do login, sem os claims de controle (iat, exp, jti...).
TokenStore
Haki\Auth\Storage\TokenStore: onde os tokens ficam guardados. Implementações incluídas:
Classe
Uso
SqliteTokenStore($caminho)
Padrão quando DB_CONNECTION não é mysql. Cria o arquivo e as tabelas sozinho. Tem install() e path().
ArrayTokenStore()
Em memória, para testes.
Métodos que uma implementação própria precisa ter:
Método
Deve
revokeAccessToken(string $jti, int $expiraEm)
Marcar o access token como revogado até expirar.
isAccessTokenRevoked(string $jti): bool
Dizer se ele foi revogado.
revokeUser(string $idUsuario, int $antesDe)
Revogar tudo o que foi emitido antes de $antesDe (nunca voltar no tempo).
consumeRefreshToken(string $hash, int $agora): bool
Marcar como usado de forma atômica; false se já usado ou revogado.
revokeFamily(string $idFamilia, int $agora)
Revogar todos os refresh tokens daquele login.
purgeExpired(int $agora): int
Apagar vencidos e dizer quantos.
RefreshTokenRecord tem as propriedades hash, userId, familyId, claims, createdAt, expiresAt, usedAt e revokedAt.
Validação
Haki\Validation\FormRequest: classe base das classes de validação. Veja Validação.
Método
Faz
rules(Rule $rule): array
Obrigatório. As regras de cada campo.
labels(): array
Opcional. Nomes amigáveis para as mensagens.
prepare(array $data): array
Opcional. Ajusta os dados antes de validar.
check(array $data): void
Opcional. Regras com lógica, depois de rules().
fail($campo, $mensagem)
Marca um erro (use dentro de check()).
validated()
Todos os campos validados e convertidos.
get($campo, $padrao = null)
Um campo; aceita 'endereco.cidade'.
only([...])
Só os campos informados.
$request->nome
Acesso direto a um campo validado.
user() / request()
Usuário autenticado / requisição original.
Haki\Validation\Rule (o $rule) cria os campos: text(), integer(), number(), boolean(), email(), url(), uuid(), date($formato), cep(), cpf(), cnpj(), cpfOrCnpj(), phone(), mobile(), plate(), uf(), time(), slug(), hexColor(), oneOf(...), enum($classe), list($regra) e object([...]).
Cada campo aceita: optional($padrao), length($min, $max), min(), max(), between(), oneOf(...), pattern($regex, $mensagem), same($campo), check($funcao, $mensagem) e message($mensagem).
Haki\Validation\Formats faz as mesmas conferências fora da validação: Formats::cpf($valor) devolve o valor limpo ou null. Métodos: cep, cpf, cnpj, cpfOrCnpj, phone, mobile, plate, uf, time, slug, hexColor; constante UFS.
Sem classe: $request->validate(function (Rule $rule) { return [...]; }, $nomes = []) devolve os dados validados.