Guía Completa: Laravel 11 con Registro/Login y MongoDB 6.0 LTS

En esta guía aprenderás a crear un proyecto en *Laravel 11 con autenticación básica personalizada y MongoDB 6.0 LTS como base de datos. El objetivo es registrar usuarios, iniciar sesión y mostrar mensajes personalizados, utilizando Blade como motor de vistas y sin paquetes de autenticación preconfigurados como Breeze, Jetstream o Sanctum.

Se incluyen instrucciones paso a paso, comandos exactos, fragmentos de código, advertencias de errores comunes y verificaciones para asegurar que cada paso funcione antes de avanzar.

Paso 1: Preparar el entorno PHP, Composer y XAMPP

• Instala PHP 8.2 o superior. Laravel 11 requiere esta versión mínima. La forma más sencilla en Windows es usar XAMPP o WAMP, que incluyen PHP, Apache y MySQL (aunque no usaremos MySQL en este proyecto).
• Descarga e instala Composer desde https://getcomposer.org/.
• Durante la instalación de Composer, selecciona el ejecutable de PHP ubicado en la carpeta de XAMPP, por ejemplo: C:\xampp\php\php.exe

Verifica la instalación:

php --version 

composer --version 

Paso 2: Crear un proyecto Laravel 11

Navega a la carpeta donde quieras crear tu proyecto por ejemplo C:\xampp\htdocs y ejecuta:

composer create-project --prefer-dist laravel/laravel nombre-proyecto "11.*" 

Reemplaza nombre-proyecto por el nombre que desees. Una vez finalizada la instalación, entra a la carpeta del proyecto:

cd nombre-proyecto 

php artisan serve

Esto levantará el servidor en http://localhost:8000

Paso 3: Instalar y configurar MongoDB 6.0 LTS

1. Descarga MongoDB Community Server 6.0 LTS desde https://www.mongodb.com/try/download/community.
2. Durante la instalación, selecciona la opción para instalar MongoDB como servicio.
3. (Opcional) Instala MongoDB Compass para gestionar bases de datos visualmente.
4. Verifica la conexión local desde MongoDB Compass con: mongodb://localhost:27017

Paso 4: Instalar la extensión MongoDB para PHP

En Windows:

• Ingresa a https://github.com/mongodb/mongo-php-driver/releases
• En este caso, si tienes instalado PHP 8.2, descarga el archivo:

php_mongodb-2.1.1-8.2-ts-vs16-x86_64.zip

• Extrae el contenido del .zip y localiza el archivo .dll.
• Cambia el nombre de ese archivo .dll a:

php_mongodb.dll

• para que pueda ser detectado por PHP.
• Copia el archivo .dll a la carpeta:

C:\xampp\php\ext

Abre php.ini y añade la línea:

extension=mongodb

Guarda y reinicia Apache.

Verifica ejecutando: php -m y busca mongodb en la lista.

Paso 5: Instalar el paquete Laravel-MongoDB

Ejecuta en la raíz del proyecto:

composer require mongodb/laravel-mongodb 

Paso 6: Configurar la conexión MongoDB en Laravel

En el archivo .env agrega:

MONGODB_HOST=127.0.0.1 
MONGODB_PORT=27017 
MONGODB_DATABASE=auth_user 
MONGODB_USERNAME= 
MONGODB_PASSWORD= 
DB_AUTHENTICATION_DATABASE=admin 

En config/database.php agrega en connections:

'mongodb' => [ 
    'driver'   => 'mongodb', 
    'host'     => env('MONGODB_HOST', '127.0.0.1'), 
    'port'     => env('MONGODB_PORT', 27017), 
    'database' => env('MONGODB_DATABASE'), 
    'username' => env('MONGODB_USERNAME'), 
    'password' => env('MONGODB_PASSWORD'), 
    'options'  => [ 'database' => env('DB_AUTHENTICATION_DATABASE', 'admin') ], 
] 

Configurar MongoDB como conexión predeterminada

En el archivo config/database.php, ubica la clave default (al inicio del archivo) y reemplaza mysql por mongodb. Otra opción es modificar el archivo .env y cambiar el valor de DB_CONNECTION a:

DB_CONNECTION=mongodb 

Con este cambio, Laravel usará MongoDB como conexión por defecto para Eloquent. Si prefieres no modificar la conexión predeterminada, puedes especificar manualmente la conexión en cada modelo.

En este proyecto trabajaremos únicamente con MongoDB, por lo que establecerlo como predeterminado es lo más práctico.

(Recomendado) Deshabilitar migraciones SQL por defecto

Laravel incluye migraciones pensadas para bases de datos SQL como users, password_resets, etc..

Dado que MongoDB utiliza un esquema flexible, esas migraciones no son necesarias y pueden generar errores si intentan ejecutarse.

Para evitarlo, comenta o elimina los archivos de migración ubicados en database/migrations que estén relacionados con tablas SQL predeterminadas, como usuarios y restablecimiento de contraseñas.

MongoDB creará automáticamente la colección la primera vez que insertes un documento, así que no necesitas definir un esquema previo para la colección de usuarios.

Paso 7: Ajustar el modelo User para MongoDB

Laravel incluye un modelo User por defecto en app/Models/User.php. Debemos adaptarlo para que utilice la clase Authenticatable de MongoDB. Código modificado:

namespace App\Models; 
 
use MongoDB\Laravel\Auth\User as Authenticatable; 
use Illuminate\Notifications\Notifiable; 
 
class User extends Authenticatable 
{ 
    use Notifiable; 
    protected $connection = 'mongodb'; 
    protected $collection = 'users'; 
    protected $fillable = ['name', 'email', 'password']; 
    protected $hidden = ['password', 'remember_token']; 
} 

En config/auth.php, verifica que el provider users use el modelo App\Models\User::class

'model' => App\Models\User::class, 

Paso 8: Crear el servicio de autenticación (AuthService)

Centralizar la lógica de registro y login en un servicio permite reutilizar el código tanto para vistas web como para APIs.

namespace App\Services; 
use App\Models\User; 
use Illuminate\Support\Facades\Hash; 
use Illuminate\Support\Facades\Validator; 
use Illuminate\Validation\ValidationException; 
 
class AuthService { 
    public function register(array $data) { 
        $validator = Validator::make($data, [ 
            'name' => 'required|string|max:255', 
            'email' => 'required|email|unique:users,email', 
            'password' => 'required|string|min:6|confirmed', 
        ]); 
        if ($validator->fails()) throw new ValidationException($validator); 
        return User::create([ 
            'name' => $data['name'], 
            'email' => $data['email'], 
            'password' => Hash::make($data['password']), 
        ]); 
    } 
 
    public function login(array $data) { 
        $validator = Validator::make($data, [ 
            'email' => 'required|email', 
            'password' => 'required|string', 
        ]); 
        if ($validator->fails()) throw new ValidationException($validator); 
        $user = User::where('email', $data['email'])->first(); 
        if (! $user || ! Hash::check($data['password'], $user->password)) { 
            throw ValidationException::withMessages(['email' => ['Credenciales incorrectas.']]); 
        } 
        return $user; 
    } 
} 

Paso 9: Crear el controlador web de autenticación

Este controlador maneja el registro e inicio de sesión desde formularios Blade.

namespace App\Http\Controllers; 
use App\Services\AuthService; 
use Illuminate\Http\Request; 
use Illuminate\Support\Facades\Auth; 
use Illuminate\Validation\ValidationException; 
 
class AuthWebController extends Controller { 
    protected $authService; 
    public function __construct(AuthService $authService) { $this->authService = $authService; } 
 
    public function showRegisterForm() { return view('auth.register'); } 
    public function submitRegister(Request $request) { 
        try { 
            $user = $this->authService->register($request->all()); 
            Auth::login($user); 
            return redirect('/')->with('status', 'Registro exitoso. ¡Bienvenido!'); 
        } catch (ValidationException $e) { 
            return redirect()->back()->withErrors($e->errors())->withInput($request->except('password')); 
        } 
    } 
 
    public function showLoginForm() { return view('auth.login'); } 
    public function submitLogin(Request $request) { 
        try { 
            $user = $this->authService->login($request->all()); 
            Auth::login($user); 
            return redirect('/')->with('status', 'Has iniciado sesión correctamente.'); 
        } catch (ValidationException $e) { 
            return redirect()->back()->withErrors($e->errors())->withInput($request->except('password')); 
        } 
    } 
} 

Paso 10: Definir rutas web

En routes/web.php agrega:

use App\Http\Controllers\AuthWebController; 
 
Route::get('/register', [AuthWebController::class, 'showRegisterForm']); 
Route::post('/register', [AuthWebController::class, 'submitRegister']); 
Route::get('/login', [AuthWebController::class, 'showLoginForm']); 
Route::post('/login', [AuthWebController::class, 'submitLogin'])

Paso 11: Crear vistas Blade para registro y login

En resources/views/auth/register.blade.php crea el formulario de registro con campos name, email, password y password_confirmation.

En resources/views/auth/login.blade.php crea el formulario de login con campos email y password.

<h1>Registro de Usuario</h1> 
@if ($errors->any()) 
    <div class="alert alert-danger"> 
        <ul> 
            @foreach ($errors->all() as $error) 
                <li>{{ $error }}</li> 
            @endforeach 
        </ul> 
    </div> 
@endif 
 
<form method="POST" action="{{ url('/register') }}"> 
    @csrf 
    <div> 
        <label>Nombre:</label><br> 
        <input type="text" name="name" value="{{ old('name') }}"> 
        @error('name') <small class="text-danger">{{ $message }}</small> @enderror 
    </div> 
    <div> 
        <label>Email:</label><br> 
        <input type="email" name="email" value="{{ old('email') }}">  
        @error('email') <small class="text-danger">{{ $message }}</small> @enderror 
    </div> 
    <div> 
        <label>Contraseña:</label><br> 
        <input type="password" name="password"> 
        @error('password') <small class="text-danger">{{ $message }}</small> @enderror 
    </div> 
    <div> 
        <label>Confirmar Contraseña:</label><br> 
        <input type="password" name="password_confirmation"> 
        @error('password_confirmation') <small class="text-danger">{{ $message }}</small> @enderror 
    </div> 
    <button type="submit">Registrar</button> 
</form> 

Archivo: resources/views/auth/login.blade.php

<h1>Iniciar Sesión</h1> 
@if ($errors->any()) 
    <div class="alert alert-danger"> 
        <ul> 
            @foreach ($errors->all() as $error) 
                <li>{{ $error }}</li> 
            @endforeach 
        </ul> 
    </div> 
@endif 
 
<form method="POST" action="{{ url('/login') }}"> 
    @csrf 
    <div> 
        <label>Email:</label><br> 
        <input type="email" name="email" value="{{ old('email') }}"> 
        @error('email') <small class="text-danger">{{ $message }}</small> @enderror 
    </div> 
    <div> 
        <label>Contraseña:</label><br> 
        <input type="password" name="password"> 
        @error('password') <small class="text-danger">{{ $message }}</small> @enderror 
    </div> 
    <button type="submit">Ingresar</button> 
</form> 

Paso 12: Endpoints API para uso externo

Archivo: routes/api.php

use App\Http\Controllers\Api\AuthController; 
 
Route::post('/register', [AuthController::class, 'register']); 
Route::post('/login', [AuthController::class, 'login']); 

Archivo: app/Http/Controllers/Api/AuthController.php

namespace App\Http\Controllers\Api; 
 
use App\Http\Controllers\Controller; 
use App\Services\AuthService; 
use Illuminate\Http\Request; 
 
class AuthController extends Controller 
{ 
    protected $authService; 
 
    public function __construct(AuthService $authService) 
    { 
        $this->authService = $authService; 
    } 
 
    public function register(Request $request) 
    { 
        $user = $this->authService->register($request->all()); 
        return response()->json([ 
            'message' => 'Usuario registrado correctamente', 
            'user'    => $user, 
        ], 201); 
    } 
 
    public function login(Request $request) 
    { 
        $user = $this->authService->login($request->all()); 
        return response()->json([ 
            'message' => 'Login exitoso', 
            'user'    => $user, 
        ]); 
    } 
}