Do zero ao módulo em 5 minutos

Clone → configure → crie um módulo → teste. Sem enrolação.

Pré-requisito

PHP 8.2+, Composer e Docker instalados. Veja a seção Instalação se precisar.

Passo 1 — Clonar e instalar

bash

git clone https://github.com/vupi.us/api_vupi.us_php.git minha-api
cd minha-api
composer install

Passo 2 — Configurar o ambiente

bash

cp EXEMPLO.env .env

Edite o .env e preencha no mínimo:

env

DB_CONEXAO=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NOME=minha_api_db
DB_USUARIO=admin
DB_SENHA=senha123

JWT_SECRET=gere_com_openssl_rand_hex_32_aqui
JWT_API_SECRET=outro_secret_diferente_aqui

Passo 3 — Subir o banco e rodar migrations

bash

docker compose up -d postgres
php vupi migrate --seed

O seeder cria o usuário admin padrão. Credenciais definidas em ADMIN_EMAIL e ADMIN_PASSWORD no .env.

Passo 4 — Subir o servidor

bash

php -S localhost:3005 index.php

Acesse http://localhost:3005 — o dashboard deve aparecer.

Passo 5 — Criar seu primeiro módulo

bash

php vupi make:module Produto

Isso cria a estrutura completa em src/Modules/Produto/. Abra o arquivo de rotas:

php

<?php
// src/Modules/Produto/Routes/web.php

use Src\Kernel\Auth;
use Src\Modules\Produto\Controllers\ProdutoController;

/** @var \Src\Kernel\Contracts\RouterInterface $router */

$router->get('/api/produtos',       [ProdutoController::class, 'listar']);
$router->get('/api/produtos/{id}',  [ProdutoController::class, 'buscar'], Auth::limit(60));
$router->post('/api/produtos',      [ProdutoController::class, 'criar'],  Auth::user());
$router->delete('/api/produtos/{id}', [ProdutoController::class, 'deletar'], Auth::admin());

Passo 6 — Criar a migration

php

<?php
// src/Modules/Produto/Database/Migrations/001_create_produtos.php

return [
    'up' => function (PDO $pdo): void {
        $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
        if ($driver === 'pgsql') {
            $pdo->exec("CREATE TABLE IF NOT EXISTS produtos (
                id        UUID          PRIMARY KEY DEFAULT gen_random_uuid(),
                nome      VARCHAR(255)  NOT NULL,
                preco     NUMERIC(10,2) NOT NULL DEFAULT 0,
                ativo     BOOLEAN       NOT NULL DEFAULT TRUE,
                criado_em TIMESTAMPTZ   NOT NULL DEFAULT NOW()
            )");
        } else {
            $pdo->exec("CREATE TABLE IF NOT EXISTS produtos (
                id        CHAR(36)      PRIMARY KEY,
                nome      VARCHAR(255)  NOT NULL,
                preco     DECIMAL(10,2) NOT NULL DEFAULT 0,
                ativo     TINYINT(1)    NOT NULL DEFAULT 1,
                criado_em DATETIME      NOT NULL DEFAULT CURRENT_TIMESTAMP
            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4");
        }
    },
    'down' => function (PDO $pdo): void {
        $pdo->exec("DROP TABLE IF EXISTS produtos");
    },
];

Passo 7 — Rodar a migration e testar

bash

php vupi migrate

# Testar a rota pública
curl http://localhost:3005/api/produtos

# Fazer login para obter token
curl -X POST http://localhost:3005/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login": "[email protected]", "senha": "Admin@123456"}'

# Criar produto (com token)
curl -X POST http://localhost:3005/api/produtos \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nome": "Produto Teste", "preco": 49.90}'

Pronto.

Você tem uma API REST funcionando com autenticação JWT, rate limiting e banco de dados — em menos de 5 minutos. Agora implemente o ProdutoController, ProdutoService e ProdutoRepository seguindo os exemplos na seção Módulos.