Laravel Breeze - Guia Laravel

Què és Breeze?#

Laravel Breeze és un starter kit d'autenticació minimalista que proporciona una implementació completa de registre, login, restabliment de contrasenya, verificació d'email i confirmació de contrasenya. A diferència d'altres solucions, Breeze publica tot el codi a la teva aplicació: controladors, vistes, rutes i tests. Això significa que tens control total sobre cada aspecte de l'autenticació i pots modificar qualsevol cosa.

Breeze és la opció recomanada per a la majoria de projectes nous. Si necessites funcionalitats més avançades com autenticació de dos factors o gestió d'equips, pots considerar Jetstream.

Instal·lació#

Primer, instal·la el paquet amb Composer en un projecte Laravel nou:

composer require laravel/breeze --dev

Després, executa l'instal·lador que et preguntarà quin stack de frontend vols utilitzar:

php artisan breeze:install

Les opcions disponibles són:

# Blade amb Tailwind CSS (el més senzill)
php artisan breeze:install blade
 
# Livewire amb components Volt
php artisan breeze:install livewire
 
# Inertia amb React
php artisan breeze:install react
 
# Inertia amb Vue
php artisan breeze:install vue
 
# Només API (sense vistes, ideal per SPAs separades)
php artisan breeze:install api

Després de la instal·lació, compila els assets i executa les migracions:

npm install && npm run dev
php artisan migrate

L'opció blade és la més senzilla i directa: genera vistes Blade amb Tailwind CSS. Les opcions React i Vue utilitzen Inertia.js per crear SPAs amb routing del servidor. L'opció api és per quan el frontend està completament separat (per exemple, un projecte Next.js o Nuxt).

Què genera Breeze?#

Breeze crea els fitxers següents a la teva aplicació:

app/Http/Controllers/Auth/
├── AuthenticatedSessionController.php  // Login/Logout
├── ConfirmablePasswordController.php   // Confirmació de contrasenya
├── EmailVerificationNotificationController.php
├── EmailVerificationPromptController.php
├── NewPasswordController.php           // Nova contrasenya
├── PasswordController.php              // Canviar contrasenya
├── PasswordResetLinkController.php     // Enviar link de reset
├── RegisteredUserController.php        // Registre
└── VerifyEmailController.php           // Verificació d'email

resources/views/auth/
├── confirm-password.blade.php
├── forgot-password.blade.php
├── login.blade.php
├── register.blade.php
├── reset-password.blade.php
└── verify-email.blade.php

routes/auth.php                         // Totes les rutes d'autenticació
tests/Feature/Auth/                     // Tests complets per a cada funcionalitat

Les rutes d'autenticació es registren automàticament al fitxer routes/auth.php, que s'inclou des de routes/web.php.

Personalitzar el registre#

Un dels avantatges de Breeze és que pots modificar directament el controlador de registre per afegir camps o canviar la lògica:

// app/Http/Controllers/Auth/RegisteredUserController.php
public function store(Request $request): RedirectResponse
{
    $request->validate([
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'string', 'email', 'max:255', 'unique:users'],
        'password' => ['required', 'confirmed', Rules\Password::defaults()],
        // Afegir camps personalitzats
        'phone' => ['nullable', 'string', 'max:20'],
        'company' => ['nullable', 'string', 'max:255'],
    ]);
 
    $user = User::create([
        'name' => $request->name,
        'email' => $request->email,
        'password' => Hash::make($request->password),
        'phone' => $request->phone,
        'company' => $request->company,
    ]);
 
    event(new Registered($user));
 
    Auth::login($user);
 
    return redirect(route('dashboard', absolute: false));
}

De la mateixa manera, pots modificar les vistes a resources/views/auth/ per afegir els nous camps al formulari, canviar l'estil o afegir informació addicional.

Pots modificar el controlador de login per afegir condicions, lògica addicional o canviar la redirecció:

// app/Http/Controllers/Auth/AuthenticatedSessionController.php
public function store(LoginRequest $request): RedirectResponse
{
    $request->authenticate();
 
    $request->session()->regenerate();
 
    // Redirigir segons el rol
    if ($request->user()->role === 'admin') {
        return redirect()->route('admin.dashboard');
    }
 
    return redirect()->intended(route('dashboard', absolute: false));
}

Personalitzar les vistes#

Les vistes de Breeze utilitzen Tailwind CSS per defecte i tenen un disseny net i responsiu. Pots personalitzar-les completament:

{{-- resources/views/auth/login.blade.php --}}
<x-guest-layout>
    <form method="POST" action="{{ route('login') }}">
        @csrf
 
        <div>
            <x-input-label for="email" :value="__('Correu electrònic')" />
            <x-text-input
                id="email"
                type="email"
                name="email"
                :value="old('email')"
                required
                autofocus
                autocomplete="username"
            />
            <x-input-error :messages="$errors->get('email')" class="mt-2" />
        </div>
 
        <div class="mt-4">
            <x-input-label for="password" :value="__('Contrasenya')" />
            <x-text-input
                id="password"
                type="password"
                name="password"
                required
                autocomplete="current-password"
            />
            <x-input-error :messages="$errors->get('password')" class="mt-2" />
        </div>
 
        <div class="flex items-center justify-between mt-4">
            <label class="flex items-center">
                <input type="checkbox" name="remember" class="rounded">
                <span class="ml-2 text-sm">{{ __('Recorda\'m') }}</span>
            </label>
 
            @if (Route::has('password.request'))
                <a href="{{ route('password.request') }}" class="text-sm hover:underline">
                    {{ __('Has oblidat la contrasenya?') }}
                </a>
            @endif
        </div>
 
        <div class="mt-4">
            <x-primary-button class="w-full justify-center">
                {{ __('Iniciar sessió') }}
            </x-primary-button>
        </div>
    </form>
</x-guest-layout>

Breeze genera components Blade reutilitzables a resources/views/components/ com text-input, input-label, input-error i primary-button que pots modificar per adaptar-los al disseny de la teva aplicació.

Tests inclosos#

Breeze genera tests complets per a totes les funcionalitats d'autenticació a tests/Feature/Auth/. Això inclou tests per al registre, login, logout, restabliment de contrasenya, verificació d'email i confirmació de contrasenya:

php artisan test --filter=Auth
 
# Tests inclosos:
# RegistrationTest
# AuthenticationTest
# PasswordResetTest
# EmailVerificationTest
# PasswordConfirmationTest
# PasswordUpdateTest