Haki

Introdução

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:

routes/api.php
/** @var Haki\Haki $app */

$app->get('/ola/{nome}', function (string $nome) {
    return ['mensagem' => "Olá, $nome"];
});

Acessando /ola/Shanks no navegador, a resposta é:

{ "mensagem": "Olá, Shanks" }

O que é uma API REST, em poucas palavras

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:

  1. Encontra a rota certa para o método e o caminho (ou responde 404/405).
  2. Roda os middlewares: código que se repete em várias rotas, como CORS e logs.
  3. Confere o login, se a rota exigir, validando o token JWT.
  4. Valida os dados enviados, se você pedir, respondendo 422 com mensagens claras.
  5. Chama o seu código (o controller), entregando tudo o que ele pediu.
  6. Transforma o retorno em JSON e envia a resposta.
  7. Se algo der errado em qualquer etapa, responde com um erro padronizado, sem expor detalhes internos em produção.
Requisição chega no public/index.php 1. Encontra a rota routes/api.php 2. Middlewares globais → do grupo → da rota 3. Login: ->auth() e ->role() valida o token e o perfil 4. Validação classe FormRequest, se o método pedir 5. Controller com tudo injetado 6. Resposta JSON 200, 201, 204... 404 rota não existe · 405 método um middleware pode barrar 401 sem token · 403 sem perfil 422 dados inválidos HttpException · 500 erro Todo erro vira o mesmo JSON: { "erro": "...", "status": 401 } Middlewares globais também veem as respostas de erro no caminho de volta.
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.

OndeComo o Haki usa os tipos
Parâmetros da rotafunction show(int $id): "10" vira o número 10, e /produtos/abc responde 404 antes do seu código rodar.
Injeção de dependênciasO 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 geradosTudo o que o init e o make:request criam já vem com declare(strict_types=1) e tudo tipado.
Tipagem obrigatóriaCom $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

RequisitoPara quê
PHP 8.2 ou superiorObrigatório. Veja a sua versão com php -v.
ComposerInstalar o pacote e carregar as classes
Extensão zipUsada pelo Composer para baixar e extrair o pacote
Extensões json, mbstring, opensslObrigatórias (já vêm em quase toda instalação)
Extensão pdo_sqliteSó 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:

  1. Instalação e Estrutura de pastas: o projeto rodando.
  2. Rotas, Controllers, Requisições e Respostas: o básico de toda API.
  3. Validação: conferir os dados que chegam.
  4. Autenticação: login, rotas protegidas e perfis.
  5. Exemplo completo: tudo junto em uma API de verdade.

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ãoPor que precisa
zipO Composer baixa os pacotes compactados em .zip. Sem ela, o Haki não é instalado.
pdo_sqliteGuarda 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

  1. Instale o Haki em uma pasta vazia
    composer require shankscode/haki
  2. 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.

  3. Suba o servidor embutido do PHP
    php -S localhost:8000 -t public
  4. 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.

Nginx

server {
    root /var/www/minha-api/public;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    }
}

Apache

public/.htaccess
RewriteEngine On
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

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:

  1. public/index.php recebe a requisição e carrega bootstrap/app.php.
  2. O Haki procura a rota em routes/api.php.
  3. Os middlewares rodam (CORS, autenticação, perfil...).
  4. O controller lê os dados da requisição e chama um service.
  5. O service aplica a regra de negócio e usa um repository para buscar ou salvar dados.
  6. 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:

routes/api.php
<?php

declare(strict_types=1);

use App\Controllers\HomeController;

/** @var Haki\Haki $app */

$app->get('/', [HomeController::class, 'index']);
De onde vem o $app?

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:

bootstrap/app.php
$app->routes(__DIR__ . '/../routes/api.php');
$app->routes(__DIR__ . '/../routes/admin.php');

app/Controllers/HomeController.php

app/Controllers/HomeController.php
<?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:

composer.json
{
    "require": {
        "shankscode/haki": "^1.4"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    }
}

Se o init avisar que não conseguiu atualizar o autoload, rode composer dump-autoload. Faça o mesmo sempre que editar o composer.json à mão.

Adicionando sua próxima rota

Crie o controller em app/Controllers e registre a rota em routes/api.php:

routes/api.php
$app->get('/', [HomeController::class, 'index']);
$app->get('/produtos', [ProdutoController::class, 'index']);

Convenções de nomes

O quêExemploOnde
ControllerProdutoControllerapp/Controllers/ProdutoController.php
ValidaçãoCriarPedidoRequestapp/Requests/CriarPedidoRequest.php
ServiceCriarPedidoServiceapp/Services/CriarPedidoService.php
InterfaceProdutoRepositoryInterfaceapp/Contracts/ProdutoRepositoryInterface.php
RepositoryPdoProdutoRepositoryapp/Repositories/PdoProdutoRepository.php
ModelProdutoapp/Models/Produto.php
MiddlewareCors, RegistrarAcessoapp/Middleware/Cors.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_ENVModoErros mostram
development, dev ou localDesenvolvimentoUma dica de solução; em erros 500, também arquivo, linha e trace.
qualquer outro valor, ou ausenteProduçãoSó 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:

__DIR__             →  C:\projetos\minha-api\bootstrap
dirname(__DIR__)    →  C:\projetos\minha-api

Para consultar esses valores depois:

$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ávelPadrãoDescrição
APP_ENVproductionModo da aplicação
JWT_SECRETnenhumSegredo do login (HS256), com no mínimo 32 caracteres
JWT_ALGORITHMHS256HS256 ou RS256
JWT_PRIVATE_KEYnenhumCaminho da chave privada (RS256)
JWT_PUBLIC_KEYnenhumCaminho da chave pública (RS256)
JWT_TTL900Validade do access token em segundos (15 min)
JWT_REFRESH_TTL604800Validade do refresh token em segundos (7 dias)
JWT_ISSUERnenhumNome do emissor (claim iss), opcional
JWT_DATABASEstorage/haki.sqliteArquivo de tokens quando o armazenamento padrão é SQLite; não usado no MySQL automático
DB_CONNECTIONnenhumsqlite ou mysql (usado pelo comando db e pela sua conexão)
DB_DATABASEnenhumCaminho do arquivo (SQLite) ou nome do banco (MySQL)
DB_HOST / DB_PORT127.0.0.1 / 3306Servidor MySQL
DB_USERNAME / DB_PASSWORDnenhumUsuá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 .envEnv::get() devolve
X=true / X=falsetrue / false
X= (vazio) ou X=nullo valor padrão
X=900'900' (texto: converta com (int))
variável inexistenteo 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:

routes/api.php
$app->get('/produtos', [ProdutoController::class, 'index']);         // listar
$app->post('/produtos', [ProdutoController::class, 'store']);        // criar
$app->get('/produtos/{id}', [ProdutoController::class, 'show']);     // ver um
$app->put('/produtos/{id}', [ProdutoController::class, 'update']);   // substituir
$app->patch('/produtos/{id}', [ProdutoController::class, 'patch']);  // alterar parte
$app->delete('/produtos/{id}', [ProdutoController::class, 'destroy']); // remover

Closures ou controllers?

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:

FormatoExemplo
Controller e método[ProdutoController::class, 'index']
Função anônimafunction (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);

Em todos os formatos, os parâmetros são injetados automaticamente.

Parâmetros na URL

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:

$app->group('/admin', function (Haki $app) {
    $app->get('/usuarios', [AdminController::class, 'usuarios']);   // /admin/usuarios
    $app->get('/relatorios', [AdminController::class, 'relatorios']); // /admin/relatorios
})->role('admin');

Grupos podem ser aninhados, e um grupo aceita ->auth(), ->role() e ->middleware(), exatamente como uma rota.

Rotas inexistentes e métodos errados

SituaçãoResposta
O caminho não existe404. Em desenvolvimento, a dica sugere rotas parecidas.
O caminho existe, mas com outro método405, com o cabeçalho Allow listando os métodos aceitos.
{
  "erro": "Rota não encontrada",
  "status": 404,
  "detalhes": {
    "dica": "A rota GET /usuarios/10 não existe. Rotas parecidas: GET /usuario/{id}. Você quis dizer alguma delas?"
  }
}

Arquivos de rotas

As rotas ficam em routes/api.php, carregado no bootstrap com $app->routes(). Dentro do arquivo, a variável $app é a sua aplicação:

routes/api.php
<?php

declare(strict_types=1);

use App\Controllers\HomeController;

/** @var Haki\Haki $app */

$app->get('/', [HomeController::class, 'index']);

Para separar as rotas em vários arquivos, chame routes() mais de uma vez. O caminho pode ser absoluto ou relativo à raiz do projeto:

bootstrap/app.php
$app->routes(__DIR__ . '/../routes/api.php');
$app->routes('routes/admin.php');

Arquivos no formato antigo, que retornam function (Haki $app) { ... }, também funcionam.

Listando as rotas registradas

Para conferir o que foi registrado (útil para depurar):

foreach ($app->router()->routes() as $rota) {
    echo $rota->getMethod() . ' ' . $rota->getPath() . ($rota->requiresAuth() ? ' (auth)' : '') . PHP_EOL;
}
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.

PontoComo funciona
O que contaCada chamada, com ou sem sucesso. Para contar só senhas erradas, use LimiteDeTentativas no service de login.
Por quemPor IP e por rota. Quem não tem IP identificado divide um mesmo contador.
OrdemRoda antes da autenticação, então um IP bloqueado não gasta consulta ao token.
ArmazenamentoMySQL 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

  1. 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.

  2. Registre as rotas
    routes/api.php
    use App\Controllers\ProdutoController;
    
    /** @var Haki\Haki $app */
    
    $app->get('/produtos', [ProdutoController::class, 'index']);
    $app->get('/produtos/{id}', [ProdutoController::class, 'show']);

    [ProdutoController::class, 'index'] quer dizer: "nessa rota, chame o método index da classe ProdutoController".

  3. 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:

RotaMétodoFaz
GET /produtosindexLista
GET /produtos/{id}showMostra um
POST /produtosstoreCria
PUT /produtos/{id}updateSubstitui
PATCH /produtos/{id}patchAltera uma parte
DELETE /produtos/{id}destroyApaga

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.

Se o parâmetro for...O Haki entrega
Request $requestA requisição atual
Response $responseUma resposta nova, para você montar
Auth $authO serviço de autenticação
Uma classe de validação (CriarProdutoRequest)Os dados já validados (veja Validação)
Qualquer outra classeUma instância criada pelo container
int $id (sem classe)O parâmetro {id} da URL, convertido
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

RetornoO cliente recebe
Array ou objetoJSON, status 200
ResponseExatamente o que você montou (status, cabeçalhos, corpo)
stringTexto puro, status 200
nullStatus 204, sem corpo

Veja os detalhes em Respostas.

Controller de uma ação só

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

MensagemCausa 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çoOnde estáMétodoResultado
Parâmetro de rotaCaminho: /produtos/10param('id')'10'
Query stringDepois do ?: notificar=simquery('notificar')'sim'
CorpoJSON depois dos cabeçalhosinput('nome')'Chapéu de palha'
CabeçalhoContent-Type: ...header('Content-Type')'application/json'
TokenAuthorization: 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 &.

http://localhost:8000/produtos?busca=espada&pagina=2
                               └──── query string ────┘
$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';

Listas na query string

Use colchetes no nome para enviar vários valores:

// GET /produtos?tags[]=php&tags[]=api&preco[min]=10&preco[max]=50

$request->query('tags');   // ['php', 'api']
$request->query('preco');  // ['min' => '10', 'max' => '50']

Exemplo: busca com paginação

public function index(Request $request): array
{
    $busca = trim((string) $request->query('busca', ''));
    $pagina = max(1, (int) $request->query('pagina', 1));

    $produtos = $this->produtos->buscar($busca, $pagina);

    return ['pagina' => $pagina, 'produtos' => $produtos];
}

Parâmetros de rota: param()

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 argumentoAceitaSe o valor for inválido
int10, -3Responde 404
float9.9, 10Responde 404
booltrue, false, 1, 0Responde 404
string ou sem tipoQualquer 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().
  • Formulário, quando vem de um <form> HTML comum.
corpo enviado
{
  "nome": "Nami",
  "idade": 20,
  "endereco": { "cidade": "Cocoyashi", "pais": "East Blue" },
  "tags": ["navegadora", "cartógrafa"]
}
$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.

Enviando um corpo JSON (cliente)

curl -X POST http://localhost:8000/clientes \
     -H "Content-Type: application/json" \
     -d '{"nome": "Nami", "idade": 20}'
JavaScript
await fetch('http://localhost:8000/clientes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ nome: 'Nami', idade: 20 }),
});

Cabeçalhos e token

$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étodoRetorna
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)
header($nome, $padrao = null)Um cabeçalho
headers()Todos os cabeçalhos (nomes em minúsculas)
isJson()true se o corpo é JSON
bearerToken()Token do cabeçalho Authorization
method()Método HTTP em maiúsculas
path()Caminho, sem query string
uri()Caminho com query string, como chegou
ip()IP da conexão
user()Usuário autenticado ou null

Validando o que chega

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:

$dados = $request->validate(function (Rule $rule) {
    return [
        'nome'  => $rule->text()->length(3, 100),
        'email' => $rule->email(),
    ];
});

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.

Criando uma classe de validação

  1. Gere a classe
    php vendor/bin/haki make:request CriarClienteRequest

    O arquivo é criado em app/Requests/CriarClienteRequest.php.

  2. 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')),
            ];
        }
    }
  3. 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:

RegraCliente enviouVocê 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.

Tipos de campo

RegraAceita
$rule->text()Texto. Números também são aceitos e viram texto.
$rule->integer()Número inteiro: 20 ou "20".
$rule->number()Inteiro ou decimal: 9.9 ou "9.9".
$rule->boolean()true/false, 1/0, "sim"/"não", "on"/"off", "yes"/"no".
$rule->email()E-mail válido.
$rule->url()URL começando com http:// ou https://.
$rule->uuid()UUID (é convertido para minúsculas).
$rule->date()Data 2026-12-31. Outro formato: date('d/m/Y') ou date('Y-m-d H:i').
$rule->cep(), cpf(), cnpj(), phone()...Formatos brasileiros prontos. Veja Formatos prontos.
$rule->oneOf('a', 'b')Um dos valores listados.
$rule->enum(Plano::class)Um dos valores de um enum; vira o próprio enum.
$rule->list($regra)Uma lista em que cada item segue a regra.
[ ... ] ou $rule->object([ ... ])Um objeto com campos próprios.

Formatos prontos (CEP, CPF, telefone...)

Para os formatos mais usados no Brasil você não precisa escrever expressão regular. Use o tipo pronto:

return [
    'cpf'      => $rule->cpf(),
    'cep'      => $rule->cep(),
    'celular'  => $rule->mobile(),
    'telefone' => $rule->phone()->optional(),
    'uf'       => $rule->uf(),
];

Todos aceitam o valor com ou sem máscara e entregam a versão limpa, pronta para salvar no banco:

RegraAceitaVocê 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étodoParaExemplo
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 regularpattern('/^\d{5}-?\d{3}$/')
same('campo')Igual a outro campo do mesmo nívelsame('senha')
check($funcao, $mensagem)Regra própriaveja 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 campomessage('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.

Declaração
'idade'      => $rule->integer()->min(18)->max(65),
'quantidade' => $rule->integer()->between(1, 10),
'preco'      => $rule->number()->between(0.01, 9999.99),
'desconto'   => $rule->number()->max(100)->optional(0),
Resposta quando o valor sai da faixa (422)
{
  "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:

JSON enviado
{
  "nome": "Nami",
  "endereco": {
    "rua": "Rua das Laranjas",
    "numero": 42,
    "cidade": "Cocoyashi"
  }
}

Repare que endereco não é um texto: é um grupo de campos entre { }. Por isso a regra também é um grupo, entre [ ]:

rules()
return [
    'nome' => $rule->text(),

    'endereco' => [                    // "endereco" é um objeto com estes campos:
        'rua'    => $rule->text(),     //    endereco.rua    precisa ser texto
        'numero' => $rule->integer(),  //    endereco.numero precisa ser inteiro
        'cidade' => $rule->text(),     //    endereco.cidade precisa ser texto
    ],
];

Lendo em português: "endereco é obrigatório e precisa ter rua (texto), numero (inteiro) e cidade (texto)." Veja como os dois têm o mesmo formato:

JSON                          Regra
{                             [
  "nome": "Nami",               'nome' => $rule->text(),
  "endereco": {                 'endereco' => [
    "rua": "...",                   'rua'    => $rule->text(),
    "numero": 42,                   'numero' => $rule->integer(),
    "cidade": "..."                 'cidade' => $rule->text(),
  }                             ],
}                             ]

Pegando os valores do objeto

$request->get('endereco.cidade');   // 'Cocoyashi' (o ponto entra dentro do objeto)
$request->endereco;                 // ['rua' => '...', 'numero' => 42, 'cidade' => 'Cocoyashi']
$request->endereco['numero'];       // 42 (já convertido para inteiro)

Como os erros aparecem

Se o cliente mandar o endereço sem a cidade e com o número errado:

{ "nome": "Nami", "endereco": { "rua": "Rua das Laranjas", "numero": "abc" } }

A resposta usa o ponto para mostrar onde está o erro:

"campos": {
  "endereco.numero": ["O campo numero precisa ser um número inteiro."],
  "endereco.cidade": ["O campo cidade é obrigatório."]
}

E se o cliente não mandar o endereco inteiro:

"campos": { "endereco": ["O campo endereco é obrigatório."] }

Quando você não precisa de objeto

Se o seu front-end envia os campos soltos, sem agrupar:

{ "nome": "Nami", "rua": "Rua das Laranjas", "numero": 42, "cidade": "Cocoyashi" }

então as regras também ficam soltas, sem o array em volta:

return [
    'nome'   => $rule->text(),
    'rua'    => $rule->text(),
    'numero' => $rule->integer(),
    'cidade' => $rule->text(),
];
Regra prática

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:

protected function prepare(array $data): array
{
    $data['cpf'] = preg_replace('/\D/', '', (string) ($data['cpf'] ?? '')); // "123.456.789-01" → "12345678901"
    $data['email'] = strtolower((string) ($data['email'] ?? ''));

    return $data;
}

Regras com lógica própria

check() em um campo

Para uma regra que não existe pronta, passe uma função que recebe o valor (já convertido) e retorna true se estiver certo:

'cpf' => $rule->text()->check(function (string $cpf): bool {
    return Cpf::valido($cpf);
}, 'Informe um CPF válido.'),

check() na classe

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.');
        }
    }
}

Exemplo: cadastro com confirmação de senha

app/Requests/CadastroRequest.php
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'),
        'aceitou_termos'    => $rule->boolean()->check(function (bool $aceitou): bool {
            return $aceitou;
        }, 'Você precisa aceitar os termos de uso.'),
    ];
}

Validação rápida: $request->validate()

Para poucos campos, valide direto no controller, sem criar uma classe:

use Haki\Validation\Rule;

public function login(Request $request, Auth $auth): array
{
    $dados = $request->validate(function (Rule $rule) {
        return [
            'email' => $rule->email(),
            'senha' => $rule->text()->length(8),
        ];
    });

    // $dados = ['email' => '...', 'senha' => '...']
}

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

  1. Middlewares, autenticação (->auth()) e perfil (->role()).
  2. prepare() ajusta os dados.
  3. As regras de rules() são aplicadas.
  4. Se passaram, check() roda.
  5. 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çaOndeResponsabilidade
Conexãoapp/Database/Connection.phpLê o .env e abre a conexão
Modelapp/Models/Representa um registro (um produto, um cliente)
Interfaceapp/Contracts/Diz o que dá para fazer com os registros
Repositoryapp/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)
DB_CONNECTION=sqlite
DB_DATABASE=database/app.sqlite
.env (MySQL)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=loja
DB_USERNAME=root
DB_PASSWORD=sua-senha

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:

database/criar.php
<?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(file_get_contents(__DIR__ . '/schema.sql'));

echo 'Banco pronto.' . PHP_EOL;
php database/criar.php
SQLiteMySQL
INTEGER PRIMARY KEY AUTOINCREMENTINT AUTO_INCREMENT PRIMARY KEY
TEXTVARCHAR(255) ou TEXT
REALDECIMAL(10,2) (para dinheiro)
TEXT DEFAULT CURRENT_TIMESTAMPDATETIME DEFAULT CURRENT_TIMESTAMP

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ódigoFaz
$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

MensagemCausa 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.

PassoArquivoResponsabilidade
1database/migracoes/...criar_produtos.phpCria a tabela no banco
2app/Models/Produto.phpRepresenta um registro e fala com a tabela
3app/Services/ProdutoService.phpRegra de negócio (opcional em casos simples)
4app/Controllers/ProdutoController.phpRecebe a requisição e devolve o resultado
5routes/api.phpLiga 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.

database/migracoes/2026_01_10_000001_criar_produtos.php
<?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:

routes/api.php
<?php

declare(strict_types=1);

use App\Controllers\ProdutoController;

/** @var Haki\Haki $app */

$app->get('/produtos', [ProdutoController::class, 'index']);
$app->post('/produtos', [ProdutoController::class, 'store']);

Testando o caminho

Terminal
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.

QueroUse
Escrever SQL à mão, sem nada a maisPDO
Models com CRUD, relações e migrações prontasEloPHP
As duas coisas no mesmo projetoEloPHP em alguns models; PDO nos outros

O caminho de um recurso

Com o EloPHP, cada peça tem uma página própria, e elas aparecem nesta ordem:

PassoO que você escrevePágina
1. ConfigurarAs variáveis DB_* no .envConfiguração
2. Criar as tabelasUma migração em database/migracoes/Migrações
3. Descrever o registroUm model em app/Models/Models
4. Ligar as entidadesAs relações do modelRelacionamentos
5. Buscar e gravarConsultas e transaçõesConsultas e transações
6. Usar no controllerO model dentro de um serviceDo banco ao controller

Visão rápida

Assim fica um recurso completo, em três arquivos:

database/migracoes/2026_01_10_000001_criar_setores.php
<?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

AssuntoEloquent / DoctrineEloPHP
MigraçãoClosure com $table->... repetidoArray 'coluna' => Coluna::...
Preenchimento em massaLista $fillable ou $guardedTudo liberado; só a chave primária é protegida
RelaçãoMétodo que retorna hasMany(...)Uma linha no array $temMuitos
Nome da tabelaPlural pelas regras do inglêsPlural 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.

.env (SQLite)
DB_CONNECTION=sqlite
DB_DATABASE=database/app.sqlite
.env (MySQL, PostgreSQL ou SQL Server)
DB_CONNECTION=mysql        # ou pgsql, sqlsrv
DB_HOST=127.0.0.1
DB_PORT=3306               # 5432 no pgsql, 1433 no sqlsrv
DB_DATABASE=loja
DB_USERNAME=root
DB_PASSWORD=sua-senha

O banco só é aberto quando um model ou uma migração precisa dele. Antes disso, nada é conectado.

Pelo código

Você pode informar a conexão no bootstrap/app.php, sem depender do .env. Escolha uma das formas. Cada chamada a configurar() substitui a anterior.

Opção 1: com os dados (o EloPHP abre o PDO)
use Elo\Conexao;

Conexao::configurar([
    'driver'  => 'sqlite',
    'arquivo' => __DIR__ . '/../database/app.sqlite',
]);
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_CONNECTIONBancoExtensão PHPO que o EloPHP trata por você
sqliteSQLitepdo_sqliteLiga as chaves estrangeiras (PRAGMA foreign_keys), para o ON DELETE funcionar
mysqlMySQL / MariaDBpdo_mysqlCrases, ENUM nativo e UNSIGNED
pgsqlPostgreSQLpdo_pgsqlAspas duplas, RETURNING para pegar o id e BOOLEAN
sqlsrvSQL Serverpdo_sqlsrvColchetes, 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

MensagemO que fazer
Nenhum banco configuradoDefina DB_CONNECTION no .env ou use Conexao::configurar().
DB_CONNECTION não é suportadoUse sqlite, mysql, pgsql ou sqlsrv.
Driver de banco não suportadoAtive 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.

Estrutura
meu-projeto/
├── vendor/
├── .env
└── database/
    └── migracoes/
        ├── 2026_01_10_000001_criar_setores.php
        ├── 2026_01_10_000002_criar_usuarios.php
        └── 2026_01_12_000001_adicionar_telefone_em_usuarios.php

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.

database/migracoes/2026_01_10_000002_criar_usuarios.php
<?php

use Elo\Coluna;
use Elo\Migracao;
use Elo\Tabela;

return new class extends Migracao
{
    public function subir(): void
    {
        Tabela::criar('usuarios', [
            'nome'     => Coluna::texto(150),
            'email'    => Coluna::texto()->unico(),
            'senha'    => Coluna::texto(255),
            'status'   => Coluna::opcoes(['ATIVO', 'INATIVO'])->padrao('ATIVO'),
            'setor_id' => Coluna::pertenceA('setores')->aoExcluir('SET NULL')->nulo(),
        ], ['exclusao_logica' => true]);
    }

    public function descer(): void
    {
        Tabela::apagar('usuarios');
    }
};

descer() deve fazer o oposto de subir(). Se uma tabela aponta para outra com chave estrangeira, apague a que aponta antes da que é apontada.

Tabela::criar()

Por padrão, a tabela ganha id no início e criado_em e atualizado_em no fim. Você só descreve as suas colunas.

OpçãoEfeito
'sem_id' => trueNão cria o id. Use em tabelas pivô.
'sem_datas' => trueNão cria criado_em e atualizado_em.
'exclusao_logica' => trueAcrescenta excluido_em, usado pela exclusão lógica do model.

Tipos de coluna

Cada tipo é um método de Coluna. Os modificadores vêm depois, encadeados.

ColunaPara que serveModificadores
Coluna::texto(100)Texto de tamanho limitadonulo(), unico(), padrao(), indice()
Coluna::textoLongo()Texto sem limite práticonulo()
Coluna::inteiro()Números inteirosnulo(), unico(), padrao(), semSinal(), indice()
Coluna::decimal(10, 2)Valores monetários e medidas (10 dígitos, 2 casas)nulo(), padrao()
Coluna::booleano()Sim ou nãonulo(), padrao(true)
Coluna::opcoes([...])Uma lista fechada de valoresnulo(), padrao()
Coluna::data()Só a datanulo(), padraoAtual()
Coluna::dataHora()Data e horanulo(), padraoAtual()
Coluna::json()Dados em JSONnulo()
Coluna::pertenceA('tabela')Chave estrangeiranulo(), aoExcluir(), aoAtualizar(), unico(), indice()

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:

Tabela::criar('cargo_usuario', [
    'usuario_id' => Coluna::pertenceA('usuarios')->aoExcluir('CASCADE'),
    'cargo_id'   => Coluna::pertenceA('cargos')->aoExcluir('CASCADE'),
], ['sem_id' => true, 'sem_datas' => true]);

3. Aplicando no banco

Na raiz do projeto, use o comando elo do pacote:

ComandoFaz
php vendor/bin/elo migrarAplica as migrações pendentes
php vendor/bin/elo migrar:statusLista as migrações e mostra quais já foram aplicadas
php vendor/bin/elo migrar:reverterDesfaz 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:

database/migracoes/2026_01_10_000001_criar_setores.php
<?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');
    }
};
database/migracoes/2026_01_10_000002_criar_usuarios.php
<?php

use Elo\Coluna;
use Elo\Migracao;
use Elo\Tabela;

return new class extends Migracao
{
    public function subir(): void
    {
        Tabela::criar('usuarios', [
            'nome'     => Coluna::texto(150),
            'email'    => Coluna::texto()->unico(),
            'senha'    => Coluna::texto(255),
            'status'   => Coluna::opcoes(['ATIVO', 'INATIVO'])->padrao('ATIVO'),
            'setor_id' => Coluna::pertenceA('setores')->aoExcluir('SET NULL')->nulo(),
        ], ['exclusao_logica' => true]);

        Tabela::criar('perfis', [
            'usuario_id' => Coluna::pertenceA('usuarios')->aoExcluir('CASCADE')->unico(),
            'bio'        => Coluna::textoLongo()->nulo(),
        ]);

        Tabela::criar('cargos', [
            'nome' => Coluna::texto(50)->unico(),
        ]);

        Tabela::criar('cargo_usuario', [
            'usuario_id' => Coluna::pertenceA('usuarios')->aoExcluir('CASCADE'),
            'cargo_id'   => Coluna::pertenceA('cargos')->aoExcluir('CASCADE'),
        ], ['sem_id' => true, 'sem_datas' => true]);
    }

    public function descer(): void
    {
        Tabela::apagar('cargo_usuario');
        Tabela::apagar('cargos');
        Tabela::apagar('perfis');
        Tabela::apagar('usuarios');
    }
};
database/migracoes/2026_01_12_000001_adicionar_telefone_em_usuarios.php
<?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(),
        ]);
    }
};
Terminal
php vendor/bin/elo migrar
# ✔ Migrada: 2026_01_10_000001_criar_setores
# ✔ Migrada: 2026_01_10_000002_criar_usuarios
# ✔ Migrada: 2026_01_12_000001_adicionar_telefone_em_usuarios

php vendor/bin/elo migrar:status

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:

ClasseTabela
Usuariousuarios
Setorsetores
Editaleditais
ProcessoJudicialprocessos_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.

PropriedadePadrãoPara que serve
$tabelanullNome da tabela. Vazio = deduzido da classe.
$chavePrimaria'id'Coluna da chave primária.
$protegidos['id']Colunas que o preenchimento em massa ignora.
$ocultos[]Colunas que não saem no JSON.
$datastruePreenche criado_em e atualizado_em.
$exclusaoLogicafalseexcluir() grava excluido_em em vez de apagar.
$temUm, $temMuitos, $pertenceA, $pertenceAMuitos[]Relações. Veja Relacionamentos.
Com as propriedades mais usadas
<?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étodoFaz
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étodoFaz
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:

app/Models/Usuario.php
<?php

namespace App\Models;

use Elo\Modelo;

class Usuario extends Modelo
{
    protected array $protegidos = ['id', 'status'];
    protected array $ocultos = ['senha'];
    protected bool $exclusaoLogica = true;

    protected array $temUm = [
        'perfil' => Perfil::class,            // perfis.usuario_id
    ];

    protected array $pertenceA = [
        'setor' => Setor::class,              // usuarios.setor_id
    ];

    protected array $pertenceAMuitos = [
        'cargos' => Cargo::class,             // tabela cargo_usuario
    ];
}
app/Models/Setor.php
<?php

namespace App\Models;

use Elo\Modelo;

class Setor extends Modelo
{
    protected array $temMuitos = [
        'usuarios' => Usuario::class,         // usuarios.setor_id
    ];
}
app/Models/Cargo.php
<?php

namespace App\Models;

use Elo\Modelo;

class Cargo extends Modelo
{
    protected array $pertenceAMuitos = [
        'usuarios' => Usuario::class,         // tabela cargo_usuario
    ];
}
app/Models/Perfil.php
<?php

namespace App\Models;

use Elo\Modelo;

class Perfil extends Modelo
{
    protected array $pertenceA = [
        'usuario' => Usuario::class,          // perfis.usuario_id
    ];
}
app/Services/UsuarioService.php
<?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.

O controller que chama esse service está em Do banco ao controller.

Pluralização

Ao deduzir o nome da tabela, cada palavra da classe é pluralizada pelas regras de sufixo do português:

Termina emRegraExemplo
-aovira -oesMovimentacao → movimentacoes
-mvira -nsItem → itens
-al, -el, -ol, -ultroca o l por isEdital → editais, Papel → papeis
-iltroca o l por sFunil → funis
-r, -z, -sacrescenta -esSetor → setores, Juiz → juizes
outrasacrescenta -sUsuario → 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.

ArrayTipoOnde fica a chaveExemplo
$temUm1 para 1Na tabela do outro model'perfil' => Perfil::class: perfis.usuario_id
$temMuitos1 para muitosNa tabela do outro model'processos' => Processo::class: processos.usuario_id
$pertenceAMuitos para 1Na tabela deste model'setor' => Setor::class: usuarios.setor_id
$pertenceAMuitosMuitos para muitosEm uma tabela pivô'cargos' => Cargo::class: cargo_usuario

Chaves diferentes

Quando a convenção não serve, troque a classe por um array com as opções:

protected array $temMuitos = [
    'processos' => [Processo::class, 'fk' => 'autor_id'],
];

protected array $pertenceA = [
    'responsavel' => [Usuario::class, 'fk' => 'usuario_id'],
];

protected array $pertenceAMuitos = [
    'cargos' => [Cargo::class, 'pivo' => 'vinculos', 'chave_pai' => 'usuario_id', 'chave_alvo' => 'cargo_id'],
];
OpçãoUsada emSignifica
'fk'$temUm, $temMuitos, $pertenceANome da coluna da chave estrangeira
'pivo'$pertenceAMuitosNome da tabela pivô
'chave_pai'$pertenceAMuitosColuna da pivô com o id deste model
'chave_alvo'$pertenceAMuitosColuna da pivô com o id do outro model

2. Acessar: dado ou motor

O mesmo nome pode devolver o dado ou o motor da relação. A diferença é um par de parênteses:

CódigoDevolveConsulta o banco?
$usuario->setorO Setor, ou nullSim, na primeira vez. Depois usa a memória.
$usuario->cargosLista de CargoSim, na primeira vez.
$usuario->cargos()O motor da relaçãoNão. Só ao executar obter(), contar() etc.
$usuario->cargos()->onde('nome', 'LIKE', 'Ger%')->ordenarPor('nome')->obter();
$usuario->perfil;                   // carrega uma vez; depois usa a memória

3. Criar o registro já vinculado

Em $temUm e $temMuitos, o criar() preenche a chave do pai sozinho:

$perfil   = $usuario->perfil()->criar(['bio' => 'Desenvolvedora']);   // perfis.usuario_id = $usuario->id
$processo = $usuario->processos()->criar(['titulo' => 'Ação 1']);

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étodoFazDevolve
anexar($ids)Adiciona os vínculos que ainda não existem. Repetidos são ignorados.Quantos foram criados
desanexar($ids)Remove os ids informados. Com null, remove todos.Quantos foram removidos
sincronizar($ids)Deixa a pivô com exatamente esses ids.['anexados' => [...], 'desanexados' => [...]]
$usuario->cargos()->anexar([1, 2]);
$usuario->cargos()->desanexar(2);
$usuario->cargos()->desanexar();              // remove todos

$resultado = $usuario->cargos()->sincronizar([2, 3]);
// $resultado['anexados']    -> [3]
// $resultado['desanexados'] -> [1]
Dica

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:

Usuario::onde('ativo', true)->obter();            // equivalente a:
Usuario::consulta()->onde('ativo', true)->obter();

consulta() é útil quando você quer guardar a consulta em uma variável antes de executá-la:

$consulta = Usuario::consulta()->onde('status', 'ATIVO');

if ($pedidoComBusca) {
    $consulta->onde('nome', 'LIKE', '%' . $busca . '%');
}

$usuarios = $consulta->ordenarPor('nome')->obter();

3. Escolher colunas: selecionar()

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
OperadorSignifica
=igual (é o padrão quando você passa dois argumentos)
!= ou <>diferente
<, <=, >, >=menor, menor ou igual, maior, maior ou igual
LIKEcombina com um padrão; % é qualquer sequência, _ é um caractere
NOT LIKEnã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):

Pedido::ondeEntre('valor', [100, 500])->obter();
Pedido::ondeEntre('criado_em', ['2026-01-01', '2026-03-31'])->obter();

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étodoFazExemplo
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:

MétodoDevolveQuando não há resultado
obter()lista de models (array)[]
primeiro()um modelnull
contar()quantidade (int)0
existe()true ou falsefalse
paginar($porPagina, $pagina)um Paginadordados vazio, total 0
atualizar(array $dados)linhas afetadas (int)0
compilar()array com o SQL e os valoresnão executa

obter()

$usuarios = Usuario::onde('status', 'ATIVO')->ordenarPor('nome')->obter();

foreach ($usuarios as $usuario) {
    echo $usuario->nome;
}

primeiro()

Traz no máximo um registro. Use quando a consulta deve achar um só, como buscar por e-mail:

$usuario = Usuario::onde('email', 'ana@exemplo.br')->primeiro();

if ($usuario === null) {
    // não encontrado
}

contar() e existe()

contar() usa COUNT(*), sem trazer os dados. É mais rápido que obter() quando só o número interessa:

$abertos = Processo::onde('status', 'ABERTO')->contar();     // 42

if (Usuario::onde('email', $email)->existe()) {
    // já existe
}

contar() ignora limite(), pular() e a ordenação, porque conta o conjunto inteiro.

paginar()

Traz uma página e o total, pronto para uma API com paginação:

$pagina = Processo::onde('status', 'ABERTO')
    ->ordenarPor('criado_em', 'DESC')
    ->paginar(20, 2);     // 20 por página, página 2

$pagina->dados;          // os processos da página 2
$pagina->total;          // quantos existem no total
$pagina->pagina;         // 2
$pagina->por_pagina;     // 20
$pagina->ultima_pagina; // número da última página

Ao devolver da rota, o Paginador vira este JSON:

Resposta
{
  "dados": [ { "id": 21, "titulo": "..." } ],
  "total": 42,
  "pagina": 2,
  "por_pagina": 20,
  "ultima_pagina": 3
}

Valores inválidos (página ou quantidade menor que 1) geram erro. Para aceitar valores vindos da URL, limite-os antes:

$porPagina = min(100, max(1, (int) $request->query('por_pagina', 20)));
$pagina = max(1, (int) $request->query('pagina', 1));

atualizar(): editar várias linhas de uma vez

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étodoFazDevolve
Usuario::buscar($id)Busca pela chave primáriamodel ou null
Usuario::buscarPor('email', $valor)Primeiro registro com aquele valormodel ou null
Usuario::buscarTodos(['status' => 'ATIVO'])Lista com igualdade em cada coluna; null vira IS NULLlista de models
Usuario::criar($dados)Cria, salva e devolvemodel
Usuario::consulta()Devolve o construtor, para começar uma consultaconstrutor
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çãoO 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 especialErro de nome inválido
ordenarPor com direção diferente de ASC/DESCErro
ondeEm com lista vaziaNenhum resultado (sem erro)
ondeEntre com lista que não tem 2 valoresErro
limite/pular negativosErro

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()
});
CasoO que acontece
O bloco termina sem erroAs gravações são confirmadas (commit)
O bloco lança um erroTudo é desfeito (rollback) e o erro é relançado
Chamada dentro de outra transaçãoEntra 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.

MétodoFaz
Conexao::configurar($dados_ou_pdo)Define a conexão (veja Configuração)
Conexao::obter()Devolve o PDO em uso
Conexao::gramatica()Devolve o dialeto do banco (MySQL, PostgreSQL, SQL Server ou SQLite)
Conexao::executar($sql, $valores)Executa um SQL com ? e devolve o PDOStatement
Conexao::executarDdl($sql)Executa um comando de estrutura, sem parâmetros
Conexao::limpar()Esquece a conexão atual (usado em testes)
// Consulta feita à mão, com parâmetros
$linhas = Conexao::executar(
    'SELECT COUNT(*) FROM usuarios WHERE status = ?',
    ['ATIVO']
)->fetchColumn();
Prefira o construtor

O executar() não passa pela validação de nomes nem pelo filtro de exclusão lógica. Use-o só quando o construtor não resolve o caso.

14. Tabela de referência

GrupoMétodosTipo
Colunasselecionarmonta
Filtrosonde, ouOnde, ondeEntre, ondeEm, ondeNulo, ondeNaoNulomonta
Ordem e limitesordenarPor, limite, pularmonta
Relações e junçõescom, juntarmonta
Exclusão lógicacomExcluidosmonta
Execuçãoobter, primeiro, contar, existe, paginarexecuta
Depuraçãocompilarnão executa
Atalhos do modelbuscar, buscarPor, buscarTodos, criar, consultaexecuta ou monta
TransaçõesConexao::transacaoexecuta

Respostas

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ê retornaO cliente recebe
Um array ou objetoJSON com status 200
Uma stringTexto puro com status 200
nullStatus 204, sem corpo
Uma ResponseExatamente 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étodoFaz
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étodoRetorna
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
    }
}

Agora, return ['usuario' => $usuario]; devolve só {"usuario": {"id": 1, "nome": "Nami"}}.

Quando o JSON não pode ser gerado

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:

requisição ──▶ [ CORS ] ──▶ [ Log ] ──▶ [ Auth ] ──▶  Controller
                                                            │
resposta   ◀── [ CORS ] ◀── [ Log ] ◀── [ Auth ] ◀──────────┘

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:

FormaExemploQuando usar
Nome da classeCors::classO normal. O container cria e injeta as dependências do construtor.
Instâncianew Cors('https://meusite.com')Quando o construtor precisa de um valor (texto, número).
Função anônimafunction (Request $request, callable $next) { ... }Algo bem curto, usado em um lugar só.
$app->middleware(function (Request $request, callable $next) {
    return $next($request)->header('X-Powered-By', 'Haki');
});

Ordem de execução

A ordem é sempre a mesma:

  1. Middlewares globais, na ordem em que foram registrados
  2. Middlewares do grupo
  3. Autenticação (->auth())
  4. Perfil (->role())
  5. Middlewares da rota
  6. 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');
    }
}
bootstrap/app.php
$app->middleware(new Cors('https://meusite.com.br'));

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:

throw new HttpException(404);   // { "erro": "Não encontrado", "status": 404 }
throw new HttpException(429);   // { "erro": "Muitas requisições", "status": 429 }

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:

ClasseStatusQuando
HttpExceptiono informadoErro HTTP genérico, para você usar
AuthenticationException401Token ausente, inválido, expirado ou revogado
AuthorizationException403Usuário sem o perfil exigido
RouteNotFoundException404Nenhuma rota para o caminho
MethodNotAllowedException405O caminho existe, com outro método
ValidationException422Dados inválidos; errors() traz as mensagens por campo (namespace Haki\Validation)
ContainerException500Uma dependência não pôde ser criada ou injetada
TypeCheckException500Código sem tipo, com requireTypes() ativo; problems() lista o que falta
ConfigurationException500Configuração inválida (segredo curto, chave RSA inválida, extensão faltando)
HakiException500Base de todas as anteriores; tem getHint()

Todas ficam no namespace Haki\Exceptions.

Avisos do PHP

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ódigoQuando
200Deu certo
201Recurso criado
204Deu certo, sem conteúdo (ex.: exclusão)
400Requisição inválida (ex.: JSON quebrado)
401Não autenticado: sem token, ou token inválido/expirado
403Autenticado, mas sem permissão
404Rota ou recurso não encontrado
405Método HTTP não permitido nesse caminho
422Dados inválidos (validação), com as mensagens em campos
500Erro 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

  1. O cliente envia e-mail e senha para POST /login.
  2. A sua aplicação confere as credenciais (o Haki não sabe nada sobre senhas).
  3. Se estiverem corretas, você chama $auth->login($usuario->id).
  4. O Haki devolve um access token (curto, 15 min) e um refresh token (longo, 7 dias).
  5. O cliente envia Authorization: Bearer <access_token> nas rotas protegidas.
  6. Quando o access token expira, o cliente troca o refresh token por um par novo em POST /refresh.
  7. No logout, os tokens daquela sessão são revogados.
Cliente (app/site) Sua API (Haki) Banco de tokens 1. LOGIN POST /login (e-mail e senha) sua aplicação confere a senha e chama login() guarda o hash do refresh access_token + refresh_token 2. USANDO A API (ATÉ 15 MIN) GET /pedidos · Bearer access foi revogado? 200 com os dados 3. O ACCESS TOKEN VENCEU GET /pedidos · Bearer access 401 Token expirado 4. RENOVANDO POST /refresh (refresh_token) marca o antigo como usado par NOVO de tokens 5. SE UM REFRESH JÁ USADO APARECER (ROUBO) POST /refresh (token já usado) revoga TODAS as sessões 401 · login de novo
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:

bootstrap/app.php
$app->auth([
    'secret'     => getenv('JWT_SECRET'),
    'expires_in' => 900,      // access token: 15 minutos
    'refresh_in' => 604800,   // refresh token: 7 dias
    'issuer'     => 'minha-api',
]);

Todas as opções de $app->auth()

OpçãoPadrãoDescriçãoVariável do .env
algorithm'HS256''HS256' ou 'RS256'JWT_ALGORITHM
secretnenhumSegredo do HS256 (mínimo 32 caracteres)JWT_SECRET
private_keynenhumChave privada RS256: caminho do .pem ou o conteúdoJWT_PRIVATE_KEY
public_keyderivada da privadaChave pública RS256JWT_PUBLIC_KEY
expires_in900Validade do access token, em segundosJWT_TTL
refresh_in604800Validade do refresh token, em segundosJWT_REFRESH_TTL
issuernenhumEmissor (claim iss), validado em cada tokenJWT_ISSUER
database'storage/haki.sqlite'Arquivo SQLite dos tokensJWT_DATABASE
storageMySQL ou SQLite automáticoOutro armazenamento (TokenStore)não tem

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

ClaimSignificado
subID do usuário
rolePerfil, se você informar no login
iat / expQuando foi emitido / quando expira
jtiID único do token (usado no logout)
fidID da sessão de login (usado no logout e no refresh)
issEmissor, 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

O que o cliente recebe

curl -X POST http://localhost:8000/login \
     -H "Content-Type: application/json" \
     -d '{"email": "luffy@exemplo.com", "senha": "segredo123"}'
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "9f2c4e1a7b...",
  "token_type": "Bearer",
  "expires_in": 900
}
CampoSignificado
access_tokenO token para acessar as rotas protegidas. Vale 15 minutos.
refresh_tokenServe só para pedir um access token novo quando o atual vencer. Vale 7 dias. Veja Refresh e logout.
token_typeSempre Bearer: é a palavra que vai antes do token no cabeçalho.
expires_inEm quantos segundos o access token vence.

Respostas de erro do login

SituaçãoResposta
Faltou e-mail ou senha, ou e-mail em formato inválido422 com as mensagens em campos (pelo LoginRequest)
E-mail não cadastrado ou senha errada401 "E-mail ou senha incorretos" (pelo service)

Dados extras no token

O segundo argumento de login() adiciona informações (claims) ao token. Use para dados pequenos que você consulta sempre, como o perfil:

$auth->login($usuario->id, ['role' => 'admin', 'nome' => $usuario->nome]);

Esses dados ficam disponíveis em $request->user() nas rotas protegidas. Os nomes sub, iat, exp, jti, fid e iss são reservados e não podem ser usados.

Atenção

Qualquer pessoa com o token consegue ler o que está dentro dele. Nunca coloque senha, CPF ou outros dados sensíveis nos claims.

Usando o token no cliente

Em toda requisição a uma rota protegida, o cliente envia o access token no cabeçalho Authorization, com a palavra Bearer e um espaço antes:

curl http://localhost:8000/eu -H "Authorization: Bearer eyJhbGciOi..."
JavaScript
const resposta = await fetch('http://localhost:8000/eu', {
  headers: { Authorization: `Bearer ${accessToken}` },
});

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çãoResposta
Senha ou e-mail errados401, com a mensagem E-mail ou senha incorretos.
Muitas falhas na janela429, com o cabeçalho Retry-After em segundos
Login certoO 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():

$app->get('/perfil', [PerfilController::class, 'show'])->auth();

Com isso, antes de chamar o controller, o Haki:

  1. Lê o token do cabeçalho Authorization: Bearer ....
  2. Confere a assinatura, a validade e se o token não foi revogado (logout).
  3. Se tudo estiver certo, preenche $request->user() e chama o controller.
  4. 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.

Protegendo várias rotas de uma vez

Em vez de repetir ->auth() em cada rota, agrupe:

routes/api.php
// Públicas
$app->post('/login', [AuthController::class, 'login']);
$app->post('/refresh', [AuthController::class, 'refresh']);

// Qualquer usuário logado
$app->group('/', function (Haki $app) {
    $app->get('/eu', [AuthController::class, 'eu']);
    $app->post('/logout', [AuthController::class, 'logout']);
    $app->get('/pedidos', [PedidoController::class, 'index']);
})->auth();

// Só administradores
$app->group('/admin', function (Haki $app) {
    $app->get('/usuarios', [AdminController::class, 'usuarios']);
    $app->delete('/usuarios/{id}', [AdminController::class, 'remover']);
})->role('admin');

Perfis em grupos aninhados

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').

401 ou 403?

São dois "não" diferentes:

StatusQuer dizerQuando acontece
401"Não sei quem você é."Sem token, token inválido, vencido ou revogado
403"Sei quem você é, mas você não pode."Token válido, mas sem o perfil exigido
{ "erro": "Token não informado", "status": 401 }
{ "erro": "Token inválido ou expirado", "status": 401 }
{ "erro": "Acesso negado", "status": 403 }

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

SintomaCausa
Sempre 401 "Token não informado", mesmo enviandoFaltou 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 401O access token venceu (15 minutos). Use o refresh token.
403 para um usuário que deveria ter acessoO 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 401Nã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

UsoRetorna
$user->idO ID do usuário, sempre como texto ('1')
$user->roleO 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->claimsTodos 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:

$auth->login(7, ['role' => 'membro', 'nome' => 'Usopp']);
// depois, em uma rota protegida:
return ['usuario' => $request->user()];
// { "usuario": { "id": "7", "role": "membro", "nome": "Usopp" } }

Validando um token manualmente

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 tokenRefresh token
Para que serveAcessar as rotas protegidasPedir um access token novo
Validade padrão15 minutos7 dias
Enviado emToda requisição protegidaSó em POST /refresh
Se for roubadoServe 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'));
}
routes/api.php
$app->post('/refresh', [AuthController::class, 'refresh']);
curl -X POST http://localhost:8000/refresh \
     -H "Content-Type: application/json" \
     -d '{"refresh_token": "9f2c4e1a7b..."}'

A resposta tem o mesmo formato do login: um access_token novo e um refresh_token novo.

O fluxo no cliente

  1. Faz a requisição normalmente com o access token.
  2. Se receber 401, chama POST /refresh com o refresh token guardado.
  3. Se o refresh der certo, guarda os dois tokens novos e repete a requisição original.
  4. 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:

  1. O atacante usa o token copiado e recebe um par novo.
  2. Mais tarde, o app da Nami usa o mesmo token (que já foi usado pelo atacante).
  3. O Haki percebe que um refresh token já usado apareceu de novo: há duas cópias, e uma é ilegítima.
  4. Para proteger a conta, ele revoga todas as sessões da Nami, inclusive a do atacante.
  5. 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 funcionaUm único segredo assina e confereUm par de chaves: a privada assina, a pública confere
Quem pode conferir os tokensSó quem tem o segredo (que também pode criar tokens)Qualquer um com a chave pública (que não consegue criar tokens)
ConfiguraçãoUma linha no .envDois arquivos de chave
Use quandoSó a sua API lida com os tokensOutros 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).

Se preferir gerar com o OpenSSL diretamente:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out storage/keys/private.pem
openssl rsa -in storage/keys/private.pem -pubout -out storage/keys/public.pem

2. Configurando o .env

.env
JWT_ALGORITHM=RS256
JWT_PRIVATE_KEY=storage/keys/private.pem
JWT_PUBLIC_KEY=storage/keys/public.pem

Pronto. O resto (login, refresh, ->auth()) funciona igual ao HS256, sem mudar nenhum código. O JWT_SECRET não é usado no RS256.

Configurando pelo código

Em vez do .env, você pode configurar no bootstrap:

$app->auth([
    'algorithm'   => 'RS256',
    'private_key' => 'storage/keys/private.pem', // caminho relativo à raiz, absoluto, ou o conteúdo PEM
    'public_key'  => 'storage/keys/public.pem',
]);

Se você informar só a chave privada, a pública é calculada a partir dela.

Um serviço que só confere tokens

Em outro serviço que só precisa saber se o token é válido, configure apenas a chave pública:

$app->auth(['algorithm' => 'RS256', 'public_key' => 'chaves/public.pem']);

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
PontoComo funciona
Quem assinaSempre a chave com JWT_KID.
Quem validaA chave indicada no kid do token. Tokens sem kid, emitidos antes da troca, são conferidos com todas as chaves.
Refresh tokensNão mudam: são valores aleatórios guardados no armazenamento, não JWTs.
Chave desconhecidaUm 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.

.env — MySQL e autenticação
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=loja
DB_USERNAME=seu_usuario
DB_PASSWORD=sua_senha
JWT_SECRET=sua_chave_gerada

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:

php vendor/bin/haki auth:clean
crontab (todo dia às 3h)
0 3 * * * cd /var/www/minha-api && php vendor/bin/haki auth:clean

Mudando o local do arquivo

$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
2. Usar no bootstrap/app.php
$app->auth([
    'secret'  => getenv('JWT_SECRET'),
    'storage' => new PdoTokenStore(new PDO('mysql:host=127.0.0.1;dbname=app', 'usuario', 'senha')),
]);
Mesmo banco do EloPHP

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

OndeExigênciaExemplo certo
Arquivodeclare(strict_types=1); logo depois do <?php<?php declare(strict_types=1);
Parâmetros dos métodosTodos com tipofunction show(int $id)
Retorno dos métodosTodos com tipo (menos __construct)function show(int $id): array
PropriedadesTodas com tipoprivate int $total = 0;
Funções anônimas das rotasParâ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)];
}
Tipagem
✔ 13 classes tipadas corretamente

✔ Tudo certo.

Guia rápido de tipos

TipoQuando usar
int, float, string, boolValores simples
arrayListas e arrays associativos
Produto, Request...Um objeto daquela classe
?ProdutoUm Produto ou null (ex.: busca que pode não encontrar)
int|stringUm dos dois tipos
voidMétodo que não devolve nada
nullMétodo que sempre devolve null (ex.: rota que responde 204)
mixedQualquer coisa. Evite: só quando não houver outro jeito
neverMé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:

composer require --dev phpstan/phpstan
php vendor/bin/phpstan analyse app --level=9

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:

bootstrap/app.php
$app->container()->discover('App\\Contracts', 'App\\Repositories');

A partir daí, quando alguém pedir uma interface de App\Contracts, o Haki tira o Interface do fim do nome e procura a classe em App\Repositories:

App\Contracts\ProdutoRepositoryInterface
    → procura App\Repositories\ProdutoRepository
    → procura App\Repositories\PdoProdutoRepository

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
);
InterfaceClasseConfiguração
ProdutoRepositoryInterfaceProdutoRepository ou PdoProdutoRepositoryo padrão
ProdutoRepositoryContractProdutoRepositorysuffix: 'Contract'
IProdutoRepositoryProdutoRepositoryprefix: 'I', suffix: ''
IPagamentoStripePagamentoprefix: 'I', suffix: '', patterns: ['Stripe{name}']

Chame discover() mais de uma vez para pastas diferentes:

$app->container()->discover('App\\Contracts', 'App\\Repositories');
$app->container()->discover('App\\Contracts\\Gateways', 'App\\Integrations', patterns: ['Stripe{name}']);

Regras de segurança

  • 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.
ErroMensagem
Nome errado na classe"Nenhuma implementação encontrada... Você quis dizer ...?"
Nome errado no construtor do controller"a classe não existe. Você quis dizer ...?"
Faltou o implements"... foi encontrada, mas não implementa essa interface. Adicione na classe: implements ..."
Duas classes servem"Mais de uma classe serve para ... Escolha uma com um bind explícito."

Para descobrir esses erros sem precisar acessar cada rota, rode php vendor/bin/haki check.

bind, singleton e instance

MétodoComportamentoQuando usar
bind(A::class, B::class)Cria um objeto novo a cada vez que alguém pedeO normal, para services e repositories
singleton(A::class, B::class)Cria uma vez e entrega o mesmo objeto para todosConexão com banco, cliente HTTP, algo caro de criar
instance(A::class, $objeto)Registra um objeto que você já criouTestes, 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

MensagemSoluçã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:

bootstrap/app.php
$app->container()->bind(UsuarioRepositoryInterface::class, PdoUsuarioRepository::class);
// amanhã:
$app->container()->bind(UsuarioRepositoryInterface::class, ApiUsuarioRepository::class);

Receita para um recurso novo

Para adicionar, por exemplo, produtos à API:

  1. Model

    app/Models/Produto.php: os dados e o jsonSerialize().

  2. Contrato

    app/Contracts/ProdutoRepositoryInterface.php: os métodos de acesso a dados.

  3. Repository

    app/Repositories/PdoProdutoRepository.php: implementa a interface com SQL.

  4. Service (se houver regra)

    app/Services/CriarProdutoService.php: valida e aplica a regra de negócio.

  5. Controller

    app/Controllers/ProdutoController.php: lê a requisição, chama o service e retorna.

  6. 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.

php vendor/bin/haki init
php vendor/bin/haki init --force   # recria os arquivos padrão, sobrescrevendo

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:

php vendor/bin/haki make:request CriarClienteRequest
✔ 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
ProblemaO que o comando diz
DB_CONNECTION faltandoMostra as linhas que precisam ser adicionadas
Extensão pdo_mysql ou pdo_sqlite desativadaQual linha ativar no php.ini
Arquivo SQLite inexistenteAvisa, 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:

php vendor/bin/haki auth:clean
crontab (todo dia às 3h)
0 3 * * * cd /var/www/minha-api && php vendor/bin/haki auth:clean

No Windows

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

  1. 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.

  2. Ensine o Composer a carregar a pasta tests/
    composer.json
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    }

    Depois, rode composer dump-autoload.

  3. Crie o arquivo de configuração
    phpunit.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <phpunit bootstrap="vendor/autoload.php" colors="true">
        <testsuites>
            <testsuite name="API">
                <directory>tests</directory>
            </testsuite>
        </testsuites>
    </phpunit>
  4. Rode os testes
    php vendor/bin/phpunit

Seu primeiro teste

tests/HomeTest.php
<?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').

Testando a validação

public function testCadastroRecusaEmailInvalido(): void
{
    $app = require __DIR__ . '/../bootstrap/app.php';

    $response = $app->handle(Request::create('POST', '/clientes', ['nome' => 'Nami', 'email' => 'x']));

    $this->assertSame(422, $response->getStatus());
    $this->assertArrayHasKey('email', $response->getJson()['campos']);
}

Testando rotas protegidas

Use o ArrayTokenStore, que guarda os tokens em memória (os testes não criam arquivos), e gere o token direto pelo Auth, sem passar pela rota de login:

use Haki\Auth\Auth;
use Haki\Auth\Storage\ArrayTokenStore;

public function testPainelExigePerfilAdmin(): void
{
    $app = require __DIR__ . '/../bootstrap/app.php';
    $app->auth(['secret' => str_repeat('t', 32), 'storage' => new ArrayTokenStore()]);

    $auth = $app->container()->get(Auth::class);
    $admin = $auth->login(1, ['role' => 'admin'])['access_token'];
    $membro = $auth->login(2, ['role' => 'membro'])['access_token'];

    $comToken = function (string $token) {
        return Request::create('GET', '/admin/painel', [], ['Authorization' => "Bearer $token"]);
    };

    $this->assertSame(401, $app->handle(Request::create('GET', '/admin/painel'))->getStatus());
    $this->assertSame(403, $app->handle($comToken($membro))->getStatus());
    $this->assertSame(200, $app->handle($comToken($admin))->getStatus());
}

Trocando dependências por versões de teste

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ê:

ItemPor 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órioSem ele, os tokens e senhas viajam abertos e podem ser lidos por quem estiver na mesma rede.
JWT_SECRET próprio da produçãoGerado com key:generate no servidor, diferente do de desenvolvimento.
.env, storage/*.sqlite* e storage/keys/ fora do GitSão segredos. O .gitignore do init já cuida disso.
storage/ com permissão de escritaO banco de tokens fica ali.
Extensão PDO do banco de tokens ativaUse pdo_mysql para o MySQL automático ou pdo_sqlite para o armazenamento SQLite.
Nenhum haki() esquecidoA saída do dump quebra o JSON das respostas.
CORS liberando só o seu domínioLiberar * permite que qualquer site chame a sua API pelo navegador.

Passos de um deploy

  1. 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.

  2. Crie o .env da produção
    cp .env.example .env
    php vendor/bin/haki key:generate

    Depois, preencha o resto (banco, APP_ENV=production...).

  3. Prepare o banco de tokens
    php vendor/bin/haki auth:install
  4. Configure o servidor web

    Aponte para public/ e redirecione tudo para o index.php. Veja os exemplos de Nginx e Apache.

  5. 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

ClienteRecomendação
App mobileArmazenamento 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 servidorVariá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.

RotaQuem podeFaz
POST /cadastroqualquer umCria uma conta de cliente
POST /loginqualquer umDevolve os tokens
POST /refreshqualquer umRenova os tokens
GET /produtos, GET /produtos/{id}qualquer umLista e mostra produtos
GET /eu, POST /logoutlogadoMostra quem está logado / sai
POST, PUT, DELETE /produtosadminCria, altera e apaga produtos

Os arquivos, todos na estrutura recomendada:

loja/ ├── app/ │ ├── Contracts/ ProdutoRepositoryInterface.php, UsuarioRepositoryInterface.php │ ├── Controllers/ AuthController.php, ProdutoController.php │ ├── Database/ Connection.php │ ├── Models/ Produto.php, Usuario.php │ ├── Repositories/ PdoProdutoRepository.php, PdoUsuarioRepository.php │ ├── Requests/ CadastroRequest.php, LoginRequest.php, ProdutoRequest.php │ └── Services/ LoginService.php ├── bootstrap/app.php ├── database/schema.sql, criar.php ├── routes/api.php ├── public/index.php gerado pelo init, sem mudanças └── .env

1. Criando o projeto

mkdir loja
cd loja
composer require shankscode/haki
php vendor/bin/haki init
php vendor/bin/haki key:generate

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;

A classe de conexão (explicada em Banco de dados):

app/Database/Connection.php
<?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
✔ App\Contracts\ProdutoRepositoryInterface → App\Repositories\PdoProdutoRepository
✔ App\Contracts\UsuarioRepositoryInterface → App\Repositories\PdoUsuarioRepository
...
✔ Tudo certo.

Em outro terminal, siga a ordem abaixo. Ao lado, a resposta que você deve ver:

PassoRequisiçãoResposta
CadastroPOST /cadastro com nome, email, senha e senha_confirmacao201 com o usuário (sem a senha)
Cadastro repetidoo mesmo e-mail de novo422 "Este e-mail já está cadastrado."
Login erradoPOST /login com senha errada401 "E-mail ou senha incorretos"
LoginPOST /login certo200 com access_token e refresh_token
Quem sou euGET /eu com o token{"usuario": {"id": "2", "role": "cliente", "nome": "Nami"}}
Criar produto sem tokenPOST /produtos401 "Token não informado"
Criar produto como clientePOST /produtos com o token da Nami403 "Acesso negado"
Criar produto como adminlogin com admin@loja.com / segredo123201 com o produto
Produto inválido{"nome": "X", "preco": 0}422 com as mensagens de nome e preço
ListarGET /produtos sem token200 com a lista
LogoutPOST /logout e depois GET /eu com o mesmo token204, depois 401
# 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:

  1. O namespace do arquivo não bate com a pasta. Em app/Controllers/ProdutoController.php, precisa ser namespace App\Controllers;.
  2. O nome da classe não é igual ao nome do arquivo (atenção às maiúsculas: ProdutoController ≠ produtoController).
  3. Faltou o use App\...; no arquivo que usa a classe.
  4. 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:

DicaO 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

MensagemSoluçã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.

Mais detalhes em Banco de dados.

Navegador e front-end

"blocked by CORS policy" no console do navegador

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étodoFaz
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)Registra uma rota. Retorna Route.
group($prefixo, function (Haki $app) { ... })Agrupa rotas com prefixo. Retorna RouteGroup.
routes($arquivo)Carrega um arquivo de rotas.
middleware(...$middlewares)Adiciona middlewares globais.
auth(array $opcoes)Configura a autenticação. Veja as opções.
requireTypes()Exige tipagem no código do projeto. Veja Tipagem.
container()Retorna o container de dependências.
router()Retorna o roteador (para listar rotas).
basePath($caminho = '')Caminho absoluto a partir da raiz do projeto.
isDebug()true em modo de desenvolvimento.
run()Processa a requisição atual e envia a resposta. Usado no public/index.php.
handle(Request $request)Processa uma requisição e devolve a Response sem enviar. Usado em testes.
Haki::VERSIONVersão instalada, ex.: '1.2.0'.

Route e RouteGroup

Retornados ao registrar uma rota ou um grupo. Os três métodos podem ser encadeados e funcionam igual nos dois.

MétodoFaz
->auth()Exige um token válido (401 se não houver).
->role('admin', 'gerente')Exige um dos perfis (403 se não tiver). Já inclui auth().
->middleware(...$middlewares)Middlewares só para essa rota ou esse grupo.

Para inspecionar uma rota (vinda de $app->router()->routes()): getMethod(), getPath(), getHandler(), requiresAuth(), getRoles() e getMiddleware().

Request

Haki\Http\Request: a requisição. Todos os métodos estão na página Requisições. Resumo:

GrupoMétodos
Query stringquery()
Rotaparam(), params()
Corpoinput(), has(), all(), only(), body(), isJson()
Validaçãovalidate()
Cabeçalhosheader(), headers(), bearerToken()
Informaçõesmethod(), path(), uri(), ip(), user()
CriarRequest::create() (testes), Request::capture() (usado pelo run())

Response

Haki\Http\Response: a resposta. Os métodos de montagem retornam o próprio objeto, para encadear.

MétodoFaz
new Response($corpo = '', $status = 200, $cabecalhos = [])Cria uma resposta.
json($dados, $status = 200)Corpo JSON e Content-Type: application/json.
responseJson($dados, $status = 200)O mesmo que json().
text($texto, $status = 200)Corpo em texto puro.
status($codigo)Muda o código HTTP.
header($nome, $valor)Define um cabeçalho.
getStatus(), getBody(), getJson(), getHeader($nome), getHeaders()Leem a resposta (middlewares e testes).

Container

Haki\Container\Container, acessado por $app->container().

MétodoFaz
bind($id, $implementacao = null)Diz como criar $id. Novo objeto a cada uso.
singleton($id, $implementacao = null)Como bind, mas reaproveita o mesmo objeto.
instance($id, $objeto)Registra um objeto já pronto.
get($id)Devolve o objeto, criando-o se preciso.
has($id)true se registrado ou se a classe existe.
build($classe)Sempre cria um objeto novo, resolvendo o construtor.
discover($de, $para, $suffix, $prefix, $patterns)Encontra a implementação das interfaces pelo nome (veja Descoberta automática).
discoverFor($interface)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étodoFaz
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().

MembroRetorna
->idID do usuário (texto).
->rolePerfil, ou null.
->claimsTodos 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:

ClasseUso
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étodoDeve
revokeAccessToken(string $jti, int $expiraEm)Marcar o access token como revogado até expirar.
isAccessTokenRevoked(string $jti): boolDizer se ele foi revogado.
revokeUser(string $idUsuario, int $antesDe)Revogar tudo o que foi emitido antes de $antesDe (nunca voltar no tempo).
userRevokedBefore(string $idUsuario): ?intDevolver a data guardada acima.
saveRefreshToken(RefreshTokenRecord $registro)Guardar um refresh token (só o hash).
findRefreshToken(string $hash): ?RefreshTokenRecordBuscar pelo hash.
consumeRefreshToken(string $hash, int $agora): boolMarcar 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): intApagar 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étodoFaz
rules(Rule $rule): arrayObrigatório. As regras de cada campo.
labels(): arrayOpcional. Nomes amigáveis para as mensagens.
prepare(array $data): arrayOpcional. Ajusta os dados antes de validar.
check(array $data): voidOpcional. 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->nomeAcesso 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.

Exceções

ClasseConstrutor
HttpExceptionnew HttpException($status, $mensagem = '', $cabecalhos = [], $dica = null)
HakiExceptionnew HakiException($mensagem, $dica = null)

Métodos: getStatus() e getHeaders() (HttpException), getHint() (todas). A lista completa está em Exceções do Haki.

Env

MétodoFaz
Env::get($nome, $padrao = null)Lê uma variável. "true"/"false" viram booleanos; vazio ou "null" devolve o padrão.
Env::load($arquivo)Carrega um arquivo .env. O new Haki() já faz isso.

Depuração

FunçãoFaz
haki(...$valores)Mostra os valores (HTML no navegador, árvore no terminal) e devolve o valor recebido.
Dumper::toText(array $valores)Devolve o dump como texto.
Dumper::toHtml(array $valores)Devolve o dump como HTML.

Linha de comando

ComandoFaz
php vendor/bin/hakiLista os comandos.
php vendor/bin/haki init [--force]Cria a estrutura padrão do projeto.
php vendor/bin/haki make:request Nome [--force]Cria uma classe de validação.
php vendor/bin/haki checkConfere interfaces, controllers e dependências.
php vendor/bin/haki dbTesta a conexão com o banco (variáveis DB_*).
php vendor/bin/haki key:generate [--force]Cria o JWT_SECRET no .env.
php vendor/bin/haki key:generate --rsa [--force]Cria as chaves RS256 em storage/keys/.
php vendor/bin/haki auth:installCria o banco de tokens.
php vendor/bin/haki auth:cleanApaga tokens vencidos.

Limitações e roadmap

O que o Haki ainda não faz e o que vem por aí.

Limitações conhecidas

  • Armazenamento padrão: MySQL quando configurado em DB_CONNECTION; caso contrário, SQLite. Para vários servidores, use um banco compartilhado.
  • Perfil no token: uma troca de perfil só vale na hora se você chamar logoutAll() na mesma operação. Veja o padrão.
  • Uma chave assina por vez: a troca de chave usa uma chave anterior só para validar. Veja a rotação.
  • Limite de tentativas: por rota, com ->limite(), e por conta, com LimiteDeTentativas no login.

Próximos passos

  • ES256 e outras famílias de algoritmo
  • Middleware de CORS
  • Esqueleto de projeto: composer create-project shankscode/haki-app
  • Comandos make:controller e serve
Esc