Entendendo Laravel Breeze e Sanctum
Laravel Breeze é um kit de autenticação minimalista que fornece uma implementação rápida de login, registro e recuperação de senha. Sanctum, por sua vez, é um sistema de autenticação de API que permite criar tokens pessoais ou usar autenticação baseada em sessão para SPAs (Single Page Applications). Embora sejam ferramentas diferentes, frequentemente trabalham juntas: Breeze para a interface web tradicional e Sanctum para proteger APIs.
A principal diferença entre eles é que Breeze usa sessões HTTP (padrão web), enquanto Sanctum usa tokens Bearer para autenticação de API. Para um novo desenvolvedor, compreender quando usar cada uma é fundamental. Se você constrói um Laravel tradicional com Blade, Breeze é suficiente. Se precisa de uma API RESTful ou uma SPA desacoplada, Sanctum entra em cena.
Instalação e Setup Inicial
Para instalar o Breeze, execute o comando abaixo em um projeto Laravel 10+:
composer require laravel/breeze --dev
php artisan breeze:install
Escolha a stack desejada (Blade, React, Vue ou Inertia). Após isso, instale as dependências e execute as migrations:
npm install
npm run dev
php artisan migrate
Para Sanctum, a instalação é igualmente simples:
composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate
Autenticação com Breeze: Fluxo Completo
Breeze oferece um fluxo completo de autenticação pronto para produção. Ao instalar, você recebe rotas de login, registro e confirmação de email já configuradas. O Breeze usa o guard padrão do Laravel com sessões, armazenando a identidade do usuário em cookies seguros.
Quando um usuário faz login, o Laravel cria uma sessão autenticada. Nas requisições subsequentes, o middleware auth valida automaticamente se o usuário possui uma sessão válida. Para proteger rotas, use o middleware:
// routes/web.php
Route::middleware('auth')->group(function () {
Route::get('/dashboard', function () {
return view('dashboard');
})->name('dashboard');
Route::post('/logout', [AuthenticatedSessionController::class, 'destroy'])->name('logout');
});
O controller de login já vem implementado. Você pode personalizá-lo conforme necessário, mas a configuração padrão funciona sem modificações. Breeze também inclui autenticação de dois fatores (2FA) se você instalá-lo com a opção correspondente durante o setup.
Protegendo APIs com Sanctum
Sanctum permite criar APIs seguras usando tokens Bearer. Diferente de sessões, tokens são stateless e ideais para aplicações distribuídas ou SPAs. Cada usuário pode ter múltiplos tokens, útil para diferentes clientes (web, mobile, desktop).
Criando Tokens Pessoais
A maneira mais simples de usar Sanctum é criar tokens pessoais. O usuário gera um token única vez e o utiliza em subsequentes requisições:
// Criar token para um usuário
$user = User::find(1);
$token = $user->createToken('API Token')->plainTextToken;
// Retornar token ao cliente
return response()->json(['token' => $token]);
O cliente armazena esse token e o envia em cada requisição:
// JavaScript / Axios
axios.defaults.headers.common['Authorization'] = `Bearer ${token}`;
axios.get('/api/user').then(response => {
console.log(response.data);
});
Protegendo Rotas de API
Configure suas rotas de API para usar o guard sanctum:
// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user', function (Request $request) {
return $request->user();
});
Route::post('/logout', function (Request $request) {
$request->user()->currentAccessToken()->delete();
return response()->json(['message' => 'Logged out']);
});
});
O middleware auth:sanctum valida o token Bearer enviado na requisição. Se inválido ou expirado, retorna erro 401.
Usando Breeze com Sanctum em uma SPA
Para uma Single Page Application com Sanctum, o Breeze pode ser configurado com Inertia.js, fornecendo autenticação web com suporte a token. Neste cenário, a SPA roda no mesmo domínio do Laravel, permitindo usar tanto sessões quanto tokens.
// User.php - Model com método para criar API tokens
namespace App\Models;
use Laravel\Sanctum\HasApiTokens;
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable {
use HasApiTokens;
protected $fillable = ['name', 'email', 'password'];
}
No frontend (React/Vue), após autenticação via Breeze, solicite um token Sanctum:
// Após login bem-sucedido
const response = await fetch('/api/tokens/create', {
method: 'POST',
credentials: 'include'
});
const { token } = await response.json();
localStorage.setItem('api_token', token);
Isso permite que sua SPA consuma a própria API com segurança, combinando o melhor dos dois mundos: autenticação web tradicional e APIs robustas.
Conclusão
Você aprendeu que Breeze é ideal para autenticação web tradicional com sessões, fornecendo um ponto de partida rápido e seguro. Sanctum complementa o ecossistema permitindo proteger APIs com tokens Bearer, sendo essencial para arquiteturas modernas com SPAs ou aplicações mobile. Por fim, ambas as ferramentas podem trabalhar juntas em um único projeto, oferecendo flexibilidade para diferentes tipos de cliente e requisição. Comece com Breeze se for apenas web, adicione Sanctum quando precisar de uma API.