Rotas e Proteção
Como definir rotas públicas e protegidas no seu módulo.
Arquivo de rotas
As rotas são definidas em Routes/web.php. O framework injeta a variável $router automaticamente:
<?php
use Src\Modules\Task\Controllers\TaskController;
use Src\Kernel\Middlewares\AuthHybridMiddleware;
use Src\Kernel\Middlewares\AdminOnlyMiddleware;
/** @var \Src\Kernel\Contracts\RouterInterface $router */
// Middlewares reutilizáveis
$auth = [AuthHybridMiddleware::class];
$admin = [AuthHybridMiddleware::class, AdminOnlyMiddleware::class];
// Rotas de leitura (autenticado)
$router->get('/api/task', [TaskController::class, 'listar'], $auth);
$router->get('/api/task/{id}', [TaskController::class, 'buscar'], $auth);
// Rotas de escrita (autenticado)
$router->post('/api/task', [TaskController::class, 'criar'], $auth);
$router->put('/api/task/{id}', [TaskController::class, 'atualizar'], $auth);
// Rota de exclusão (apenas admin)
$router->delete('/api/task/{id}', [TaskController::class, 'deletar'], $admin);Tipos de proteção
| Middleware | Quem acessa | Uso |
|---|---|---|
AuthHybridMiddleware | Qualquer usuário autenticado | Rotas de leitura e escrita |
AdminOnlyMiddleware | Apenas admin_system | Rotas administrativas |
RateLimitMiddleware | Todos (com limite) | Proteção contra abuso |
| Sem middleware | Qualquer pessoa | Rotas públicas (cuidado!) |
Defina arrays de middlewares no início do arquivo para reutilizar em múltiplas rotas. Isso mantém o código limpo e facilita manutenção.
Métodos HTTP Suportados
O router suporta todos os métodos HTTP padrão:
<?php
$router->get('/api/task', [TaskController::class, 'listar']); // Listar recursos
$router->post('/api/task', [TaskController::class, 'criar']); // Criar recurso
$router->put('/api/task/{id}', [TaskController::class, 'atualizar']); // Atualizar completo
$router->patch('/api/task/{id}', [TaskController::class, 'parcial']); // Atualizar parcial
$router->delete('/api/task/{id}', [TaskController::class, 'deletar']); // Deletar recurso| Método | Uso | Idempotente |
|---|---|---|
GET | Buscar/listar recursos (não modifica dados) | ✅ Sim |
POST | Criar novo recurso | ❌ Não |
PUT | Atualizar recurso completo (substitui todos os campos) | ✅ Sim |
PATCH | Atualizar recurso parcial (apenas campos enviados) | ❌ Não |
DELETE | Deletar recurso | ✅ Sim |
PUT substitui o recurso completo (todos os campos devem ser enviados). PATCH atualiza apenas os campos enviados, mantendo os demais inalterados.
Middleware próprio do módulo
Você pode criar middlewares específicos para o seu módulo em Middlewares/:
<?php
namespace Src\Modules\Task\Middlewares;
use Src\Kernel\Contracts\MiddlewareInterface;
use Src\Kernel\Http\Request\Request;
use Src\Kernel\Http\Response\Response;
final class TaskMiddleware implements MiddlewareInterface
{
public function handle(Request $request, callable $next): Response
{
// Lógica antes da requisição
$response = $next($request);
// Lógica depois da requisição
return $response;
}
}Rate Limiting Avançado
O RateLimitMiddleware aceita parâmetros personalizados para controlar limites por rota:
<?php
use Src\Kernel\Middlewares\RateLimitMiddleware;
// Rate limit personalizado: 5 requisições por minuto
$createProtected = [
AuthHybridMiddleware::class,
[RateLimitMiddleware::class, ['limit' => 5, 'window' => 60, 'key' => 'task.create']]
];
$router->post('/api/task', [TaskController::class, 'criar'], $createProtected);| Parâmetro | Tipo | Descrição |
|---|---|---|
limit | int | Número máximo de requisições (padrão: 60) |
window | int | Janela de tempo em segundos (padrão: 60) |
key | string | Identificador único para a rota (ex: 'task.create') |
user_limit | int | Limite para usuários autenticados (-1 = mesmo do IP, 0 = sem limite) |
Por padrão, usuários autenticados não têm rate limit global (apenas por rota específica). Isso evita bloqueios desnecessários para usuários legítimos. Use user_limit para definir limites específicos quando necessário.
Parâmetros de Rota
Capture parâmetros dinâmicos na URL usando {nome}:
<?php
// Rota com parâmetro
$router->get('/api/task/{id}', [TaskController::class, 'buscar'], $auth);
// No controller, acesse via Request
public function buscar(Request $request): Response
{
$id = $request->param('id'); // Captura o valor de {id}
$task = $this->service->buscar($id);
return Response::json(['task' => $task]);
}Combinando Múltiplos Middlewares
Middlewares são executados na ordem em que são declarados no array:
<?php
// Ordem: Auth → Admin → RateLimit
$adminWithLimit = [
AuthHybridMiddleware::class,
AdminOnlyMiddleware::class,
[RateLimitMiddleware::class, ['limit' => 10, 'window' => 60]]
];
$router->delete('/api/task/{id}', [TaskController::class, 'deletar'], $adminWithLimit);AdminOnlyMiddleware deve sempre vir depois de AuthHybridMiddleware, pois ele depende da autenticação para verificar permissões.
Rotas Públicas vs Protegidas
Rotas sem middleware são públicas e acessíveis por qualquer pessoa:
<?php
// ✅ Rota pública (leitura) - OK
$router->get('/api/task/public', [TaskController::class, 'listarPublicas']);
// ⚠️ Rota pública (escrita) - EVITE!
$router->post('/api/task', [TaskController::class, 'criar']); // SEM PROTEÇÃO!
// ✅ Rota protegida (escrita) - RECOMENDADO
$router->post('/api/task', [TaskController::class, 'criar'], $auth);A IDE detecta automaticamente rotas POST, PUT, PATCH e DELETE sem middleware e emite um aviso de segurança. Sempre proteja rotas que modificam dados.