shankscode / haki
Miniframework PHP simples para APIs REST, com rotas, injeção de dependências, middleware e autenticação JWT própria.
Requires
- php: ^8.2
- ext-json: *
- ext-mbstring: *
- ext-openssl: *
Requires (Dev)
- phpunit/phpunit: ^11.0
Suggests
- ext-pdo: Necessária apenas se você usar o EloPHP (ORM opcional)
- ext-pdo_mysql: Necessária para o armazenamento MySQL de tokens e para o EloPHP com MySQL
- ext-pdo_sqlite: Necessária para o armazenamento SQLite de tokens da autenticação JWT
Provides
None
Conflicts
None
Replaces
None
README
Documentação: https://joaocstt.github.io/haki/
Miniframework PHP para APIs REST: rotas, injeção de dependências, middleware e autenticação JWT própria (HS256/RS256, refresh token e logout). Não depende de nenhuma biblioteca externa.
Com DB_CONNECTION=mysql, a autenticação usa automaticamente o banco MySQL configurado em DB_* para tokens e revogações. As tabelas são criadas no primeiro uso; auth:install permite prepará-las no deploy. A conta do banco precisa ter permissão para criar tabelas e índices. Nos demais casos, o armazenamento padrão continua sendo o SQLite em JWT_DATABASE (ou storage/haki.sqlite). Um storage explícito em $app->auth() prevalece sobre essa escolha.
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 o banco no MySQL, habilite pdo_mysql e gere a chave com php vendor/bin/haki key:generate. Não é necessário configurar o armazenamento no bootstrap. A aplicação precisa de permissão de criação também no primeiro uso em cada processo ou requisição. Os comandos auth:install e auth:clean selecionam o armazenamento padrão pelo .env; eles não leem um storage personalizado do bootstrap.
Ao mudar de uma instalação existente com MySQL de aplicação e tokens em SQLite, os refresh tokens e as revogações antigas não são migrados. Os usuários precisarão entrar novamente e access tokens anteriormente revogados poderão voltar a ser aceitos até expirarem; planeje a troca da chave JWT ou a migração dos registros.
<?php require __DIR__ . '/../vendor/autoload.php'; $app = new Haki\Haki(dirname(__DIR__)); $app->get('/ola/{nome}', function (string $nome) { return ['mensagem' => "Olá, $nome"]; }); $app->get('/perfil', [PerfilController::class, 'show'])->auth(); $app->get('/admin', [AdminController::class, 'index'])->role('admin'); $app->run();
Requisitos
- PHP 8.2+
- Extensões
json,mbstringeopenssl - Extensão
zip, usada pelo Composer para baixar o pacote (sem ela aparece o erro "The zip extension and unzip/7z commands are both missing") - Extensão
pdo_sqlite, apenas se você usar a autenticação JWT
Instalação
composer require shankscode/haki php vendor/bin/haki init
O init cria a estrutura padrão do projeto, com uma rota e um controller de exemplo:
app/Controllers/HomeController.php
app/{Requests,Services,Repositories,Contracts,Models,Middleware}/
bootstrap/app.php
routes/api.php
public/index.php
storage/
.env .env.example .gitignore
As rotas ficam soltas em routes/api.php. O $app vem do bootstrap/app.php, que carrega o arquivo com $app->routes(...):
<?php declare(strict_types=1); use App\Controllers\HomeController; /** @var Haki\Haki $app */ $app->get('/', [HomeController::class, 'index']);
Validação
php vendor/bin/haki make:request CriarClienteRequest
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(), 'cpf' => $rule->cpf(), // formatos prontos: cep, cpf, cnpj, phone, mobile, plate, uf... ]; } } // No controller: se algo estiver inválido, responde 422 antes de chegar aqui. public function store(CriarClienteRequest $request): array { return ['cliente' => $this->clientes->criar($request->validated())]; }
Interfaces sem bind
O bootstrap/app.php gerado pelo init liga as interfaces de app/Contracts às classes de app/Repositories pelo nome:
$app->container()->discover('App\Contracts', 'App\Repositories'); // ProdutoRepositoryInterface → ProdutoRepository ou PdoProdutoRepository
Tipagem obrigatória
O bootstrap/app.php gerado pelo init exige tipos em todo o código do projeto:
$app->requireTypes();
Um parâmetro ou retorno sem tipo faz a API responder com erro, indicando a classe, o método e a linha. O haki check confere todas as classes de app/ antes de publicar.
EloPHP (ORM opcional)
O Haki vem com o EloPHP, um ORM Active Record com nomes em português. Ele é opcional: sem usá-lo, o Haki segue com PDO puro.
use Elo\Modelo; class Usuario extends Modelo { protected array $pertenceA = ['setor' => Setor::class]; protected array $pertenceAMuitos = ['cargos' => Cargo::class]; } $usuario = Usuario::criar(['nome' => 'João', 'email' => 'joao@exemplo.br']); $usuario->cargos()->sincronizar([1, 2]);
Migrações e comandos: php vendor/bin/elo migrar, migrar:reverter, migrar:status. Documentação completa na seção EloPHP da documentação.
Rodando
php -S localhost:8000 -t public
Acesse http://localhost:8000.
Comandos
| Comando | Faz |
|---|---|
php vendor/bin/haki init |
Cria a estrutura padrão do projeto |
php vendor/bin/haki make:request Nome |
Cria uma classe de validação em app/Requests |
php vendor/bin/haki check |
Confere interfaces, controllers e dependências antes de publicar |
php vendor/bin/haki db |
Testa a conexão com o banco configurado no .env (DB_*) |
php vendor/bin/haki key:generate |
Cria JWT_SECRET no .env (--rsa para chaves RS256) |
php vendor/bin/haki auth:install |
Prepara as tabelas de tokens no armazenamento configurado |
php vendor/bin/haki auth:clean |
Remove tokens vencidos |
Desenvolvimento do pacote
composer install
composer test
Licença
MIT