Roles y Permisos en Laravel con Spatie: Guía Paso a Paso

Los roles y permisos son fundamentales en cualquier aplicación web que maneje distintos tipos de usuarios y niveles de acceso. Controlar lo que cada usuario puede (o no) hacer es esencial para la seguridad y la organización de tu aplicación.

En este artículo, aprenderás a configurar y utilizar el paquete laravel-permission de Spatie para gestionar roles y permisos de manera rápida y efectiva. Veremos un paso a paso completo, con ejemplos y consejos avanzados, para que puedas integrar esta funcionalidad sin complicaciones en tus proyectos Laravel.

Más adelante, prepararé un curso sobre la implementación de roles y permisos sin dependencias, creado totalmente desde cero. Mientras tanto, laravel-permission es una herramienta sólida y fiable para ahorrar tiempo de desarrollo.

---

Tabla de compatibilidad con Laravel

Es importante verificar qué versión de laravel-permission usar en relación con tu versión de Laravel. La tabla de compatibilidad oficial (tomada de la documentación de Spatie) es la siguiente:

Versión del paquete	Versiones de Laravel compatibles
^6.0	8, 9, 10, 11 (PHP 8.0+)
^5.8	7, 8, 9, 10
^5.7	7, 8, 9
^5.4-^5.6	7, 8
5.0-5.3	6, 7, 8
^4	6, 7, 8
^3	5.8

Asegúrate de instalar la versión correcta del paquete, acorde a la versión de Laravel que uses.

---

¿Para qué sirve laravel-permission?

El paquete laravel-permission facilita la implementación de un sistema de roles y permisos en Laravel. Con él podrás:

• Crear y gestionar roles (admin, editor, usuario, etc.).

• Asignar permisos específicos a cada rol (crear publicaciones, editar comentarios, etc.).

• Asignar roles y permisos directamente a usuarios.

• Restringir el acceso a rutas, controladores o vistas con middlewares y directivas de Blade.

• Consultar fácilmente si un usuario tiene un rol o un permiso específico.

Con esto, tu aplicación quedará bien estructurada a nivel de seguridad y niveles de acceso.

---

Requisitos previos

1. Un proyecto de Laravel compatible (ver la tabla de compatibilidad).

2. Composer instalado en tu entorno de desarrollo.

3. Conexión a una base de datos (MySQL, PostgreSQL, etc.) configurada en tu archivo .env.

---

Paso 1: Instalación

Para instalar laravel-permission, ejecuta:

composer require spatie/laravel-permission

El instalador actualizará tu composer.json y descargará los archivos necesarios.

---

Paso 2: Publicar migraciones y archivo de configuración

Publica las migraciones y el archivo de configuración mediante:

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

Esto creará:

• Las migraciones necesarias en database/migrations.

• El archivo de configuración permission.php en config/permission.php.

---

Paso 3: Ejecutar las migraciones

Ejecuta las migraciones para crear las tablas:

php artisan migrate

Se crearán varias tablas: roles, permissions, model_has_roles, model_has_permissions y role_has_permissions.

---

Paso 4: Configuración básica

En el archivo config/permission.php, puedes personalizar aspectos adicionales, como el modelo de usuario o la configuración de la caché. Por defecto, se asume que tu modelo de usuario está en App\Models\User (en Laravel 8+). Ajusta los valores en caso de que tu estructura difiera.

---

Paso 5: Modelos y uso básico

Añadir el trait HasRoles a tu modelo User

Para que tu modelo de usuario pueda trabajar con roles y permisos, agrega el trait HasRoles:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

    // ...
}

Ahora tu usuario tendrá acceso a métodos como assignRole(), hasRole(), givePermissionTo(), entre otros.

---

Paso 6: Crear y asignar roles y permisos

Puedes crear roles y permisos en un seeder, en un controlador o directamente con Tinker. Aquí unos ejemplos:

<?php

use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;
use App\Models\User;

// 1. Crear un rol
$role = Role::create(['name' => 'admin']);

// 2. Crear un permiso
$permission = Permission::create(['name' => 'crear posts']);

// 3. Asignar permiso a un rol
$role->givePermissionTo($permission);

// 4. Asignar rol a un usuario
$user = User::find(1);
$user->assignRole('admin');

// 5. Otorgar un permiso directo a un usuario
$user->givePermissionTo('crear posts');

Comprobar roles y permisos

Para validar roles y permisos:

<?php

if ($user->hasRole('admin')) {
    // El usuario tiene el rol "admin"
}

if ($user->can('crear posts')) {
    // El usuario tiene el permiso para crear posts
}

También hay métodos como hasAnyRole() o hasAllRoles().

---

Paso 7: Protegiendo rutas y controladores con middlewares

Cómo registrar y utilizar los middlewares depende de tu versión de Laravel.

Laravel 9 y 10

En app/Http/Kernel.php, en la sección $middlewareAliases, registra los middlewares:

<?php

protected $middlewareAliases = [
    // ...
    'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
    'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
    'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
];

Luego, para proteger rutas:

<?php

Route::group(['middleware' => ['role:admin']], function () {
    Route::get('/admin/dashboard', 'AdminController@index');
});

Route::group(['middleware' => ['permission:crear posts']], function () {
    Route::post('/posts', 'PostController@store');
});

Laravel 11

En Laravel 11, la forma de registrar middlewares puede variar según la estructura de tu proyecto. Un ejemplo (si usas la estructura por defecto con bootstrap/app.php) es:

<?php

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
        'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
        'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
    ]);
})

Una vez registrados, los utilizas de la misma forma en tus rutas:

<?php

Route::group(['middleware' => ['role:admin']], function () {
    Route::get('/admin/dashboard', 'AdminController@index');
});

---

Paso 8: Verificación en Blade

Para controlar la visibilidad de elementos en tus vistas, puedes usar directivas de Blade personalizadas:

@role('admin')
    <a href="{{ route('admin.dashboard') }}">Ir al panel de administración</a>
@endrole

@can('crear posts')
    <a href="{{ route('posts.create') }}">Crear un nuevo post</a>
@endcan

---

Tip avanzado 1: Optimización de consultas con caché

laravel-permission implementa caché para no consultar la base de datos en cada verificación de roles/permisos. Si necesitas personalizar este comportamiento:

• Borrar la caché manualmente usando:

  php artisan permission:cache-reset

• En config/permission.php, modifica cache.expiration_time para ajustar la duración de la caché.

---

Tip avanzado 2: Sincronizar múltiples permisos a la vez

Si deseas asignar varios permisos a un rol o a un usuario en una sola operación, puedes usar el método syncPermissions:

<?php

// Asignar varios permisos a un rol
$adminRole = Role::findByName('admin');
$adminRole->syncPermissions(['crear posts', 'editar posts', 'eliminar posts']);

// Asignar varios permisos a un usuario
$user->syncPermissions(['crear posts', 'publicar comentarios']);

Este método elimina cualquier permiso que no esté en la lista, lo que es útil para asignaciones masivas.

---

Tip avanzado 3: Seeding avanzado y gestión de caché

En proyectos grandes, seguramente quieras crear roles y permisos mediante seeders. Para evitar conflictos con la caché de permisos, Spatie recomienda:

1. Vaciar la caché antes de crear o asignar permisos (especialmente si vas a crear roles/permissions desde cero).

2. Vaciarla de nuevo si usas el trait WithoutModelEvents en tus seeders y vas a asignar roles/permisos después de crearlos.

El método que permite vaciar esa caché es:

<?php

app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();

Ejemplo de Seeder

<?php

use Illuminate\Database\Seeder;
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;
use Spatie\Permission\PermissionRegistrar;

class RolesAndPermissionsSeeder extends Seeder
{
    public function run()
    {
        // 1. Resetear la caché de roles y permisos
        app()[PermissionRegistrar::class]->forgetCachedPermissions();

        // 2. Crear permisos
        Permission::create(['name' => 'edit articles']);
        Permission::create(['name' => 'delete articles']);
        Permission::create(['name' => 'publish articles']);
        Permission::create(['name' => 'unpublish articles']);

        // (Opcional) Volver a resetear si usas WithoutModelEvents en seeders
        app()[PermissionRegistrar::class]->forgetCachedPermissions();

        // 3. Crear rol admin y asignar permisos
        $adminRole = Role::create(['name' => 'admin']);
        $adminRole->givePermissionTo(Permission::all());

        // 4. Crear rol editor y asignar permisos específicos
        $editorRole = Role::create(['name' => 'editor']);
        $editorRole->givePermissionTo(['edit articles', 'publish articles']);
    }
}

Luego, desde la terminal:

php artisan db:seed --class=RolesAndPermissionsSeeder

De esta forma, tendrás un entorno inicial de roles y permisos ya configurado, y sin problemas de caché.

---

Conclusión

La librería laravel-permission de Spatie ofrece una solución rápida y potente para manejar roles y permisos en tus proyectos Laravel. Siguiendo este tutorial, podrás configurar, crear, asignar y verificar roles y permisos. Además, la integración con Blade, la caché incorporada y las herramientas para seeding hacen que la gestión de acceso sea sencilla y escalable.

Si en el futuro buscas un enfoque más personalizado o educacional, pronto ofreceré un curso desde cero, sin dependencias. Por ahora, laravel-permission es un gran aliado para desarrollar aplicaciones seguras y bien estructuradas.

¡Espero que este tutorial te haya sido de utilidad y te ayude a implementar roles y permisos de manera rápida y efectiva en tus proyectos!

¿Quieres seguir profundizando en las últimas novedades de Laravel?

No te pierdas nuestra ruta de Laravel 11, donde exploramos las funciones más recientes del framework, prácticas avanzadas y consejos para optimizar tus proyectos. ¡Te esperamos allí para que lleves tus aplicaciones al siguiente nivel!