Search by

Miniframework PHP simples para APIs REST, com rotas, injeção de dependências, middleware e autenticação JWT própria.

Package info

github.com/Joaocstt/haki

pkg:composer/shankscode/haki

Statistics

Installs: 57

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v2.0.0 2026-11-15 20:50 UTC

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, mbstring e openssl
  • 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