Laravel + React (Inertia) – Roles & Permissions Starter

https://github.com/zanwaar/laravel12-react-roles-permissions
Admin
A Laravel + React (Inertia) starter kit featuring Spatie Roles & Permissions management, designed...
Tokens:12,578
Snippets:69
Trust Score:6.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Initial Project Setup Commands (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

These commands cover the initial setup of the project, including copying the environment file, installing Composer dependencies, installing Node.js dependencies, generating the application key, and running database migrations with seeding.

```bash
cp .env.example .env
composer install
npm install
php artisan key:generate
php artisan migrate --seed
```

--------------------------------

### Start Development Server (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

This command starts all necessary services concurrently for development. It's a convenient way to run the backend development server and any other required processes simultaneously.

```bash
composer dev
```

--------------------------------

### List Products with Search and Pagination (Bash)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Demonstrates how to list products using a GET request, including search parameters and pagination. It shows the cURL command for the request and an example JSON response structure.

```bash
# GET /products?search=laptop&perPage=10
curl -X GET "http://localhost:8000/products?search=laptop&perPage=10" \
  -H "Cookie: laravel_session=..."

# Response (Inertia):
{
  "products": {
    "data": [
      {
        "id": 1,
        "name": "Gaming Laptop",
        "description": "High performance laptop",
        "price": 1299.99,
        "featured_image": "products/abc123.jpg",
        "featured_image_original_name": "laptop.jpg",
        "created_at": "17 Oct 2025"
      }
    ],
    "links": [
      {"url": null, "label": "&laquo; Previous", "active": false},
      {"url": "http://localhost:8000/products?page=1", "label": "1", "active": true}
    ],
    "from": 1,
    "to": 10,
    "total": 25
  },
  "filters": {"search": "laptop", "perPage": "10"}
}
```

--------------------------------

### Run Development Servers (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

Commands to start development servers for Laravel, Vite, queue workers, and log viewers. These are essential for local development and hot-reloading.

```bash
# Run all dev servers concurrently (Laravel, Queue, Pail logs, Vite)
composer dev

# Or run individually:
php artisan serve              # Laravel dev server
npm run dev                    # Vite dev server for hot reload
php artisan queue:listen       # Queue worker
php artisan pail               # Log viewer
```

--------------------------------

### View Single Product (Bash)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Details how to retrieve a single product's information using a GET request. The example cURL command demonstrates the request, and the response indicates it renders a product form.

```bash
# GET /products/{product}
curl -X GET http://localhost:8000/products/1 \
  -H "Cookie: laravel_session=..."

# Response: Renders products/product-form with isView=true
```

--------------------------------

### Delete Product (Bash)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Illustrates how to delete a product using a DELETE request. The example cURL command includes the necessary headers, and the response indicates a redirect upon successful deletion.

```bash
# DELETE /products/{product}
curl -X DELETE http://localhost:8000/products/1 \
  -H "Cookie: laravel_session=..." \
  -H "X-CSRF-TOKEN: ..."

# Response: 302 redirect back with success message
```

--------------------------------

### Create Product with File Upload (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Provides a PHP code snippet for creating a new product, including handling file uploads for a featured image. It also includes an example cURL command to demonstrate the API request.

```php
// POST /products
use App\Http\Controllers\ProductController;
use App\Http\Requests\ProductFormRequest;

public function store(ProductFormRequest $request)
{
    try {
        $featuredImage             = null;
        $featuredImageOriginalName = null;

        if ($request->file('featured_image')) {
            $featuredImage             = $request->file('featured_image');
            $featuredImageOriginalName = $featuredImage->getClientOriginalName();
            $featuredImage             = $featuredImage->store('products', 'public');
        }

        $product = Product::create([
            'name'                         => $request->name,
            'description'                  => $request->description,
            'price'                        => $request->price,
            'featured_image'               => $featuredImage,
            'featured_image_original_name' => $featuredImageOriginalName,
        ]);

        if ($product) {
            return redirect()->route('products.index')
                ->with('success', 'Product created successfully.');
        }
    } catch (Exception $e) {
        Log::error('Product creation failed: ' . $e->getMessage());
    }
}

// Example cURL with file upload:
curl -X POST http://localhost:8000/products \
  -H "Cookie: laravel_session=..." \
  -F "name=Wireless Mouse" \
  -F "description=Ergonomic wireless mouse" \
  -F "price=29.99" \
  -F "featured_image=@/path/to/image.jpg"
```

--------------------------------

### Share Auth Data in Inertia (PHP)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

Example of how authentication data, including user, roles, and permissions, is shared with the frontend via Inertia.js. This is handled in the HandleInertiaRequests middleware.

```php
/*
 * HandleInertiaRequests.php
 */
'auth' => [
    'user'        => $request->user(),
    'roles'       => fn() => $request->user()?->roles->pluck('name'),
    'permissions' => fn() => $request->user()?->getAllPermissions()->pluck('name'),
]
```

--------------------------------

### GET /permissions

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Retrieves a list of all permissions, with support for searching and pagination.

```APIDOC
## GET /permissions

### Description
Fetches a paginated list of permissions. Supports filtering by a search term and specifying the number of items per page.

### Method
GET

### Endpoint
/permissions

#### Query Parameters
- **search** (string) - Optional - Filters permissions by name or label.
- **perPage** (integer) - Optional - Specifies the number of permissions to return per page. Defaults to a system-defined value.

### Response
#### Success Response (200)
- **permissions** (object) - Contains a list of permission data.
  - **data** (array) - Array of permission objects.
    - **id** (integer) - The unique identifier for the permission.
    - **name** (string) - The system name of the permission.
    - **label** (string) - The display label for the permission.
    - **module** (string) - The module the permission belongs to.
    - **created_at** (string) - The timestamp when the permission was created.
  - **per_page** (integer) - The number of items per page.
  - **total** (integer) - The total number of permissions matching the search criteria.
- **filters** (object) - Contains the applied filters.
  - **search** (string) - The search term used.
  - **perPage** (string) - The items per page value.
- **totalCount** (integer) - The total number of permissions in the system.
- **filteredCount** (integer) - The total number of permissions after applying filters.

#### Example Response
```json
{
  "permissions": {
    "data": [
      {"id": 10, "name": "access-products-module", "label": "access-products-module", "module": "products", "created_at": "17 Oct 2025"},
      {"id": 11, "name": "view-product", "label": "view-product", "module": "products", "created_at": "17 Oct 2025"}
    ],
    "per_page": 10,
    "total": 5
  },
  "filters": {"search": "product", "perPage": "10"},
  "totalCount": 30,
  "filteredCount": 5
}
```
```

--------------------------------

### List Permissions with Search and Pagination (cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This cURL command illustrates how to fetch a list of permissions with support for searching and pagination. It demonstrates a GET request to the permissions endpoint, including query parameters for `search` and `perPage`. The response includes paginated data, filters applied, and counts.

```bash
# GET /permissions?search=product&perPage=10
curl -X GET "http://localhost:8000/permissions?search=product&perPage=10" \
  -H "Cookie: laravel_session=..."
```

--------------------------------

### Create User with Role Assignment (PHP & cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Creates a new user and assigns roles to them using the `store` method in `UserController`. It leverages `UserRequest` for validation and `syncRoles` to manage role associations. An example cURL request demonstrates how to create a user with specified roles.

```php
// POST /users
use App\Http\Controllers\UserController;

public function store(UserRequest $request)
{
    $user = User::create([
        'name'     => $request->name,
        'email'    => $request->email,
        'password' => Hash::make($request->password),
    ]);

    if ($user) {
        $user->syncRoles($request->roles); // ['admin', 'editor']
        return redirect()->route('users.index')
            ->with('success', 'User created with roles');
    }
}

// Example cURL:
curl -X POST http://localhost:8000/users \
  -H "Cookie: laravel_session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "password": "password123",
    "roles": ["editor"]
  }'
```

--------------------------------

### Filter Sidebar Menu by Permissions (TypeScript)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This TypeScript code snippet shows how to filter sidebar menu items in a React application based on user permissions. It uses Inertia.js to get user permissions and conditionally includes menu items that require specific permissions.

```typescript
// resources/js/components/app-sidebar.tsx
import { usePage } from '@inertiajs/react';

const mainNavItems: NavItem[] = [
    {
        title: 'Dashboard',
        href: '/dashboard',
        icon: LayoutGrid,
    },
    {
        title: 'Permissions',
        href: '/permissions',
        icon: Lock,
        permission: 'access-permissions-module',
    },
    {
        title: 'Manage Products',
        href: '/products',
        icon: ShoppingBag,
        permission: 'access-products-module',
    },
];

export function AppSidebar() {
    const { auth } = usePage().props as any;
    const permissions = auth.permissions;

    // Filter menu items based on user permissions
    const filteredNavItems = mainNavItems.filter(
        (item) => !item.permission || permissions.includes(item.permission)
    );

    return (
        <Sidebar>
            <NavMain items={filteredNavItems} />
        </Sidebar>
    );
}
```

--------------------------------

### Update User Roles (PHP & cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Updates an existing user's details and assigns new roles using the `update` method in `UserController`. It saves changes to the user and then uses `syncRoles` to replace all existing roles with the new set. Example cURL shows how to update a user's roles.

```php
// PATCH /users/{user}
public function update(UserRequest $request, User $user)
{
    if ($user) {
        $user->name  = $request->name;
        $user->email = $request->email;
        $user->save();

        $user->syncRoles($request->roles); // Replaces all existing roles
        return redirect()->route('users.index')
            ->with('success', 'User updated with roles');
    }
}

// Example cURL:
curl -X PATCH http://localhost:8000/users/2 \
  -H "Cookie: laravel_session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith Updated",
    "email": "jane@example.com",
    "roles": ["admin", "editor"]
  }'
```

--------------------------------

### Build Production Application (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

Commands for building the application for production. Supports both Single Page Application (SPA) mode and Server-Side Rendering (SSR) builds, as well as development mode with SSR.

```bash
npm run build                  # Production build (SPA mode)
npm run build:ssr              # Production build with SSR
composer dev:ssr               # Dev mode with SSR
```

--------------------------------

### Database Migrations and Seeding (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

Commands for managing the application's database, including running migrations, seeding default data, and re-seeding specific components. Ensures the database schema and initial data are up-to-date.

```bash
php artisan migrate --seed     # Run migrations and seed default data
php artisan db:seed            # Re-run all seeders
php artisan db:seed --class=RolesAndPermissionsSeeder  # Seed specific seeder
```

--------------------------------

### Run Tests (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

Commands for executing tests using the Pest PHP testing framework. Allows running all tests or filtering to specific test cases for focused testing.

```bash
php artisan test               # Run all Pest tests
php artisan test --filter=TestName  # Run specific test
```

--------------------------------

### Code Quality Tools (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

Commands for maintaining code quality, including linting, formatting, and type checking for both frontend (npm) and backend (PHP Pint). Ensures code consistency and adherence to standards.

```bash
npm run lint                   # ESLint with auto-fix
npm run format                 # Prettier format
npm run format:check           # Check formatting
npm run types                  # TypeScript type checking
./vendor/bin/pint              # Laravel Pint (PHP formatting)
```

--------------------------------

### Seed Database with Roles and Permissions (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

This command executes the RolesAndPermissionsSeeder class, which is responsible for populating the database with predefined roles and permissions. This is typically run after making changes to the seeder file.

```bash
php artisan db:seed --class=RolesAndPermissionsSeeder
```

--------------------------------

### Run PHP Code Style Checker (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

This command executes Laravel Pint, a tool for automatically formatting PHP code according to the PSR-12 standard. It ensures code consistency across the project.

```bash
./vendor/bin/pint
```

--------------------------------

### Create Resource Controller (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

This command generates a new resource controller for a module using the Artisan CLI. The `--resource` flag creates all the standard CRUD methods (index, create, store, show, edit, update, destroy).

```bash
php artisan make:controller NewsController --resource
```

--------------------------------

### Run TypeScript/React Linting and Formatting (Bash)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

These commands run ESLint for code quality checks and Prettier for code formatting on TypeScript and React files. The `lint` command checks for errors and style issues, while `format` automatically corrects them.

```bash
npm run lint && npm run format
```

--------------------------------

### Run Seeder (Bash)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This bash command executes the `RolesAndPermissionsSeeder` to populate the database with roles and permissions. It shows the expected output indicating the seeding process.

```bash
# Seed all roles and permissions
php artisan db:seed --class=RolesAndPermissionsSeeder

# Output:
# Seeding: Database\Seeders\RolesAndPermissionsSeeder
# Cache cleared, permissions created, roles assigned
```

--------------------------------

### Run All Seeders (Bash)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This bash command performs a fresh migration (dropping existing tables) and then runs all database seeders, including the `RolesAndPermissionsSeeder` and `DatabaseSeeder`. The output confirms the migration and seeding process, including the creation of the default admin user.

```bash
# Run all seeders
php artisan migrate:fresh --seed

# Output:
# Dropped all tables successfully.
# Migration table created successfully.
# Migrating: ...
# Seeding: RolesAndPermissionsSeeder
# Seeding: DatabaseSeeder
# Default admin user created: admin@example.com / 12345678
```

--------------------------------

### Create Product

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Creates a new product, supporting file uploads for featured images.

```APIDOC
## POST /products

### Description
Creates a new product. Allows uploading a featured image.

### Method
POST

### Endpoint
`/products`

#### Request Body
- **name** (string) - Required - The name of the product.
- **description** (string) - Optional - The description of the product.
- **price** (float) - Required - The price of the product.
- **featured_image** (file) - Optional - The featured image file for the product.

### Request Example
```bash
curl -X POST http://localhost:8000/products \
  -H "Cookie: laravel_session=..." \
  -F "name=Wireless Mouse" \
  -F "description=Ergonomic wireless mouse" \
  -F "price=29.99" \
  -F "featured_image=@/path/to/image.jpg"
```

### Response
#### Success Response (302 Redirect)
Redirects to the products index page with a success message upon successful creation.

#### Error Response
- **500 Internal Server Error** - If the product creation fails.
```

--------------------------------

### Resource Route with Permission Middleware (PHP)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

Demonstrates how to protect resource routes in Laravel using the `permission` middleware from Spatie Laravel Permission. This ensures only authenticated users with the required permissions can access certain modules.

```php
// routes/web.php
Route::middleware(['auth', 'verified'])->group(function () {
    Route::resource('products', ProductController::class)
        ->middleware('permission:access-products-module');
});
```

--------------------------------

### List Products

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Retrieves a list of products with support for search and pagination.

```APIDOC
## GET /products

### Description
Retrieves a list of products. Supports searching by name and paginating results.

### Method
GET

### Endpoint
`/products`

#### Query Parameters
- **search** (string) - Optional - The search term to filter products by name.
- **perPage** (integer) - Optional - The number of products to display per page.

### Response
#### Success Response (200)
- **products** (object) - Contains product data and pagination information.
  - **data** (array) - Array of product objects.
    - **id** (integer) - Unique identifier for the product.
    - **name** (string) - Name of the product.
    - **description** (string) - Description of the product.
    - **price** (float) - Price of the product.
    - **featured_image** (string) - Path to the featured image.
    - **featured_image_original_name** (string) - Original name of the featured image file.
    - **created_at** (string) - Date and time the product was created.
  - **links** (array) - Pagination links.
  - **from** (integer) - The starting item number of the current page.
  - **to** (integer) - The ending item number of the current page.
  - **total** (integer) - The total number of products available.
- **filters** (object) - Contains the applied filters.
  - **search** (string) - The search term used.
  - **perPage** (string) - The number of items per page.

### Response Example
```json
{
  "products": {
    "data": [
      {
        "id": 1,
        "name": "Gaming Laptop",
        "description": "High performance laptop",
        "price": 1299.99,
        "featured_image": "products/abc123.jpg",
        "featured_image_original_name": "laptop.jpg",
        "created_at": "17 Oct 2025"
      }
    ],
    "links": [
      {"url": null, "label": "&laquo; Previous", "active": false},
      {"url": "http://localhost:8000/products?page=1", "label": "1", "active": true}
    ],
    "from": 1,
    "to": 10,
    "total": 25
  },
  "filters": {"search": "laptop", "perPage": "10"}
}
```
```

--------------------------------

### Define Module Permissions in Seeder (PHP)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

This snippet demonstrates how to define access permissions for a new module, such as 'News', within the RolesAndPermissionsSeeder.php file. It lists specific actions like view, create, edit, and delete, along with general module access.

```php
    'news' => [
        'access-news-module',
        'view-news',
        'create-news',
        'edit-news',
        'delete-news',
    ]
```

--------------------------------

### View Single Product

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Retrieves details for a specific product.

```APIDOC
## GET /products/{product}

### Description
Retrieves the details of a specific product.

### Method
GET

### Endpoint
`/products/{product}`

#### Path Parameters
- **product** (integer) - Required - The ID of the product to retrieve.

### Response
#### Success Response (200)
- Renders the product form view with `isView=true`.

### Response Example
(This endpoint typically returns a view, not JSON. The response would be the rendered HTML of the product form.)
```

--------------------------------

### Update Product (Bash)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Shows how to update an existing product using a PATCH request, including modifying fields and optionally uploading a new featured image. It provides the cURL command for the update operation.

```bash
# PATCH /products/{product}
curl -X PATCH http://localhost:8000/products/1 \
  -H "Cookie: laravel_session=..." \
  -F "name=Gaming Laptop Pro" \
  -F "description=Updated high performance laptop" \
  -F "price=1499.99" \
  -F "featured_image=@/path/to/new-image.jpg"

# Response: 302 redirect to /products with success message
```

--------------------------------

### Create Role with Permissions (cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This cURL command shows how to make a POST request to create a role with specified permissions. It demonstrates the required headers and JSON payload structure for the API endpoint. The created role name is automatically slugified from the provided label.

```bash
curl -X POST http://localhost:8000/roles \
  -H "Cookie: laravel_session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Content Manager",
    "description": "Manages products and categories",
    "permissions": ["access-products-module", "view-product", "edit-product", "access-categories-module"]
  }'
```

--------------------------------

### Add Module to Sidebar Navigation (TypeScript/React)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

This code illustrates how to add a new item to the application's sidebar navigation menu. It includes the item's title, URL, an optional icon component, and the required permission string to control its visibility based on user roles.

```tsx
{
  title: 'News',
  href: '/news',
  icon: FileText,
  permission: 'access-news-module'
}
```

--------------------------------

### Create Role with Permissions (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This PHP code snippet demonstrates how to create a new role and associate permissions with it using Laravel's Eloquent ORM and controller logic. It handles incoming requests, slugs the role name, and syncs permissions. Dependencies include `IlluminateSupportStr` and the `Role` and `RoleRequest` models.

```php
use App\Http\Controllers\RoleController;
use Illuminate\Support\Str;

public function store(RoleRequest $request)
{
    $role = Role::create([
        'label'       => $request->label,
        'name'        => Str::slug($request->label),
        'description' => $request->description,
    ]);

    if ($role) {
        $role->syncPermissions($request->permissions);
        return redirect()->route('roles.index')
            ->with('success', 'Role created successfully with Permissions!');
    }
}
```

--------------------------------

### Update Product

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Updates an existing product. Can include a new featured image.

```APIDOC
## PATCH /products/{product}

### Description
Updates an existing product. You can update product details and replace the featured image.

### Method
PATCH

### Endpoint
`/products/{product}`

#### Path Parameters
- **product** (integer) - Required - The ID of the product to update.

#### Request Body
- **name** (string) - Optional - The updated name of the product.
- **description** (string) - Optional - The updated description of the product.
- **price** (float) - Optional - The updated price of the product.
- **featured_image** (file) - Optional - A new featured image file to replace the existing one.

### Request Example
```bash
curl -X PATCH http://localhost:8000/products/1 \
  -H "Cookie: laravel_session=..." \
  -F "name=Gaming Laptop Pro" \
  -F "description=Updated high performance laptop" \
  -F "price=1499.99" \
  -F "featured_image=@/path/to/new-image.jpg"
```

### Response
#### Success Response (302 Redirect)
Redirects to the products index page with a success message upon successful update.

#### Error Response
- **500 Internal Server Error** - If the product update fails.
```

--------------------------------

### Create Custom Permission (cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This cURL command demonstrates how to create a custom permission via a POST request. It shows the necessary headers and the JSON payload structure, including the module, label, and description for the new permission. The permission name will be auto-slugified from the label.

```bash
curl -X POST http://localhost:8000/permissions \
  -H "Cookie: laravel_session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "module": "reports",
    "label": "Export Report",
    "description": "Allow exporting reports to PDF"
  }'
```

--------------------------------

### Custom Role Model with Metadata (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Extends Spatie's default Role model to include custom fields like 'label', 'description', and 'is_active'. Allows for richer role definitions and custom methods, such as checking activity status. Dependencies: Spatie Laravel Permission package.

```php
// app/Models/Role.php
namespace App\Models;

use Spatie\Permission\Models\Role as SpatieRole;

class Role extends SpatieRole
{
    protected $fillable = [
        'name',
        'label',
        'description',
        'is_active',
        'guard_name',
    ];

    // Custom methods
    public function isActive(): bool
    {
        return (bool) $this->is_active;
    }
}
```

--------------------------------

### Authentication API

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Endpoints for user authentication, including login, logout, and registration.

```APIDOC
## POST /login

### Description
Logs in a user with provided credentials.

### Method
POST

### Endpoint
/login

### Request Body
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password.

### Request Example
```json
{
  "email": "admin@example.com",
  "password": "12345678"
}
```

### Response
#### Success Response (200)
Redirects to /dashboard with session cookie. Session includes: user object, roles array, permissions array.

## POST /logout

### Description
Logs out the current user and invalidates the session.

### Method
POST

### Endpoint
/logout

### Request Example
```bash
curl -X POST http://localhost:8000/logout \
  -H "Cookie: laravel_session=..." \
  -H "X-CSRF-TOKEN: ..."
```

### Response
#### Success Response (302)
Redirects to /. Session invalidated and token regenerated.

## POST /register

### Description
Registers a new user in the system.

### Method
POST

### Endpoint
/register

### Request Body
- **name** (string) - Required - User's full name.
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password.
- **password_confirmation** (string) - Required - User's password confirmation.

### Request Example
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123",
  "password_confirmation": "password123"
}
```

### Response
#### Success Response (302)
Redirects to /dashboard. New user created without roles (must be assigned by admin).
```

--------------------------------

### Login with Credentials (cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Authenticates a user by sending their email and password to the /login endpoint. Requires JSON content type. Upon successful login, it redirects to the dashboard and establishes a session including user, roles, and permissions.

```bash
# POST /login
curl -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "12345678"
  }'

# Response: Redirects to /dashboard with session cookie
# Session includes: user object, roles array, permissions array
```

--------------------------------

### Role Management API

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Endpoints for managing roles and their associated permissions.

```APIDOC
## GET /roles

### Description
Retrieves a list of all roles along with their associated permissions.

### Method
GET

### Endpoint
/roles

### Response
#### Success Response (200)
Returns a JSON object containing roles and their permissions.
```

--------------------------------

### User Management API

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Endpoints for managing users, including listing, creating, updating, and deleting users.

```APIDOC
## GET /users

### Description
Retrieves a list of all users with filtering options.

### Method
GET

### Endpoint
/users

### Response
#### Success Response (200)
Returns a JSON object containing user data and available roles.
```json
{
  "users": {
    "data": [
      {
        "id": 1,
        "name": "Test User",
        "email": "admin@example.com",
        "roles": [
          {"id": 1, "name": "super-admin", "label": "Super Admin"}
        ]
      }
    ],
    "current_page": 1,
    "per_page": 10,
    "total": 1
  },
  "roles": [
    {"id": 1, "name": "super-admin", "label": "Super Admin"},
    {"id": 2, "name": "admin", "label": "Admin"}
  ]
}
```

## POST /users

### Description
Creates a new user and assigns roles to them.

### Method
POST

### Endpoint
/users

### Request Body
- **name** (string) - Required - User's full name.
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password.
- **roles** (array) - Optional - An array of role names to assign to the user.

### Request Example
```json
{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "password": "password123",
  "roles": ["editor"]
}
```

### Response
#### Success Response (302)
Redirects back with a success message.

## PATCH /users/{user}

### Description
Updates an existing user's information and their assigned roles.

### Method
PATCH

### Endpoint
/users/{user}

### Path Parameters
- **user** (integer) - Required - The ID of the user to update.

### Request Body
- **name** (string) - Required - User's full name.
- **email** (string) - Required - User's email address.
- **roles** (array) - Required - An array of role names to assign to the user (replaces all existing roles).

### Request Example
```json
{
  "name": "Jane Smith Updated",
  "email": "jane@example.com",
  "roles": ["admin", "editor"]
}
```

### Response
#### Success Response (302)
Redirects back with a success message.

## DELETE /users/{user}

### Description
Deletes a user from the system.

### Method
DELETE

### Endpoint
/users/{user}

### Path Parameters
- **user** (integer) - Required - The ID of the user to delete.

### Response
#### Success Response (302)
Redirects back with a success message.
```

--------------------------------

### Inertia Middleware Shared Auth Data (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Configures the Inertia middleware to share authentication-related data globally with React components. Includes user information, roles, and permissions, making them accessible via `usePage().props` without extra API calls. Dependencies: Laravel, Inertia, Spatie Laravel Permission package.

```php
// app/Http/Middleware/HandleInertiaRequests.php
namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    protected $rootView = 'app';

    public function share(Request $request): array
    {
        return [
            ...parent::share($request),
            'name'  => config('app.name'),
            'auth'  => [
                'user'        => $request->user(),
                'roles'       => fn() => $request->user()?->roles->pluck('name'),
                'permissions' => fn() => $request->user()?->getAllPermissions()->pluck('name'),
            ],
            'ziggy' => fn(): array => [
                ...(new Ziggy)->toArray(),
                'location' => $request->url(),
            ],
            'flash' => [
                'success' => $request->session()->get('success'),
                'error'   => $request->session()->get('error'),
            ],
        ];
    }
}

// Now available in all React components via usePage().props
```

--------------------------------

### List All Roles with Permissions (cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Retrieves a list of all roles and their associated permissions from the /roles endpoint. This endpoint is useful for understanding the permission structure within the application. Requires the session cookie for authentication.

```bash
# GET /roles
curl -X GET http://localhost:8000/roles \
  -H "Cookie: laravel_session=..."
```

--------------------------------

### Create Default Admin User Seeder (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This PHP seeder first calls the `RolesAndPermissionsSeeder` to ensure roles and permissions are set up, then creates a default admin user if one doesn't exist and assigns the 'super-admin' role. It also refreshes the permission cache.

```php
// database/seeders/DatabaseSeeder.php
public function run(): void
{
    // Seed roles & permissions first
    $this->call(RolesAndPermissionsSeeder::class);

    $user = User::first() ?? User::factory()->create([
        'name' => 'Test User',
        'email' => 'admin@example.com',
        'password' => bcrypt('12345678'),
    ]);

    if ($user && ! $user->hasRole('super-admin')) {
        $user->assignRole('super-admin');
    }

    app(PermissionRegistrar::class)->forgetCachedPermissions();
}
```

--------------------------------

### Register New User (cURL)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Registers a new user by sending their name, email, password, and password confirmation to the /register endpoint. Requires JSON content type. Upon successful registration, it redirects to the dashboard and creates a new user record without initial roles.

```bash
# POST /register
curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password123",
    "password_confirmation": "password123"
  }'

# Response: 302 redirect to /dashboard
# New user created without roles (must be assigned by admin)
```

--------------------------------

### Add Middleware Protected Resource Route (PHP)

Source: https://github.com/zanwaar/laravel12-react-roles-permissions/blob/main/CLAUDE.md

This snippet shows how to define a resource route for a controller and protect it with middleware. The 'permission:access-news-module' middleware ensures that only users with the specified permission can access the routes defined by the resource.

```php
Route::resource('news', NewsController::class)
    ->middleware('permission:access-news-module');
```

--------------------------------

### POST /permissions

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Creates a new custom permission.

```APIDOC
## POST /permissions

### Description
Creates a new custom permission with the specified module, label, and description. The permission name is automatically generated by slugifying the label.

### Method
POST

### Endpoint
/permissions

#### Request Body
- **module** (string) - Required - The module this permission belongs to.
- **label** (string) - Required - The display name of the permission.
- **description** (string) - Optional - A detailed description of what the permission allows.

### Request Example
```json
{
  "module": "reports",
  "label": "Export Report",
  "description": "Allow exporting reports to PDF"
}
```

### Response
#### Success Response (Redirect)
Redirects to the permissions index page with a success message.

#### Error Response
Handles validation errors from PermissionRequest.
```

--------------------------------

### TypeScript: Authorization Helper Functions

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Provides utility functions for checking user roles and permissions in the frontend. It takes user roles and permissions as input and returns a boolean indicating access. These functions are crucial for implementing granular access control in the UI.

```typescript
// resources/js/utils/authorization.ts
export const hasRole = (role: string, userRoles: string[] = []) =>
    userRoles.includes(role);

export const hasPermission = (permission: string[], userPermissions: string) =>
    permission.includes(userPermissions);

// Usage:
import { hasRole, hasPermission } from '@/utils/authorization';

const { auth } = usePage().props as any;

if (hasRole('super-admin', auth.roles)) {
    console.log('User is super admin');
}

if (hasPermission(['edit-product'], 'edit-product')) {
    console.log('User can edit products');
}
```

--------------------------------

### POST /roles

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Creates a new role with associated permissions.

```APIDOC
## POST /roles

### Description
Creates a new role with the provided label, description, and a list of permissions. The role name is automatically generated by slugifying the label.

### Method
POST

### Endpoint
/roles

#### Request Body
- **label** (string) - Required - The display name of the role.
- **description** (string) - Optional - A detailed description of the role's purpose.
- **permissions** (array of strings) - Required - A list of permission names to associate with the role.

### Request Example
```json
{
  "label": "Content Manager",
  "description": "Manages products and categories",
  "permissions": ["access-products-module", "view-product", "edit-product", "access-categories-module"]
}
```

### Response
#### Success Response (Redirect)
Redirects to the roles index page with a success message.

#### Error Response
Handles validation errors from RoleRequest.
```

--------------------------------

### PATCH /permissions/{permission}

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Updates an existing permission's module, label, and description.

```APIDOC
## PATCH /permissions/{permission}

### Description
Updates the module, label, and description of an existing permission. The permission name is automatically regenerated by slugifying the updated label.

### Method
PATCH

### Endpoint
/permissions/{permission}

#### Path Parameters
- **permission** (integer) - Required - The ID of the permission to update.

#### Request Body
- **module** (string) - Required - The updated module this permission belongs to.
- **label** (string) - Required - The updated display name of the permission.
- **description** (string) - Optional - The updated description of what the permission allows.

### Request Example
```json
{
  "module": "reports",
  "label": "Export All Reports",
  "description": "Updated description"
}
```

### Response
#### Success Response (Redirect)
Redirects to the permissions index page with a success message.

#### Error Response
Handles validation errors from PermissionRequest or if the permission is not found.
```

--------------------------------

### Delete Product

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Deletes a specific product.

```APIDOC
## DELETE /products/{product}

### Description
Deletes a specific product from the system.

### Method
DELETE

### Endpoint
`/products/{product}`

#### Path Parameters
- **product** (integer) - Required - The ID of the product to delete.

### Request Example
```bash
curl -X DELETE http://localhost:8000/products/1 \
  -H "Cookie: laravel_session=..." \
  -H "X-CSRF-TOKEN: ..."
```

### Response
#### Success Response (302 Redirect)
Redirects back with a success message upon successful deletion.

#### Error Response
- **500 Internal Server Error** - If the product deletion fails.
```

--------------------------------

### Define Module Permissions in Seeder (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This PHP seeder defines modules and their associated permissions, creates them in the database using Spatie's Permission package, and assigns them to predefined roles like 'super-admin' and 'editor'. It also handles resetting the permission cache.

```php
// database/seeders/RolesAndPermissionsSeeder.php
use Spatie\Permission\PermissionRegistrar;

public function run(): void
{
    // Reset permission cache
    app(PermissionRegistrar::class)->forgetCachedPermissions();

    // Define modules and permissions
    $modules = [
        'permissions' => [
            'access-permissions-module',
            'view-permission',
            'create-permission',
            'edit-permission',
            'delete-permission',
        ],
        'products' => [
            'access-products-module',
            'view-product',
            'create-product',
            'edit-product',
            'delete-product',
        ],
        'news' => [
            'access-news-module',
            'view-news',
            'create-news',
            'edit-news',
            'delete-news',
        ],
    ];

    // Create permissions
    foreach ($modules as $module => $permissions) {
        foreach ($permissions as $permissionName) {
            Permission::firstOrCreate(
                ['name' => $permissionName, 'guard_name' => 'web'],
                [
                    'module' => $module,
                    'label' => $permissionName,
                    'description' => null,
                    'is_active' => true,
                ]
            );
        }
    }

    // Assign permissions to roles
    $allPermissions = Permission::pluck('name')->toArray();

    Role::findByName('super-admin')->syncPermissions($allPermissions);

    $editorPermissions = [
        'access-products-module', 'view-product', 'edit-product',
        'access-news-module', 'view-news', 'create-news', 'edit-news',
    ];
    Role::findByName('editor')->syncPermissions($editorPermissions);

    // Refresh cache
    app(PermissionRegistrar::class)->forgetCachedPermissions();
}
```

--------------------------------

### Create Custom Permission (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

This PHP code snippet outlines the process for creating a new custom permission in Laravel. It handles POST requests, validates input using `PermissionRequest`, creates a new `Permission` record with module, label, slugified name, and description, and redirects with a success message. Dependencies include `IlluminateSupportStr` and the `Permission` model.

```php
use App\Http\Controllers\PermissionController;

public function store(PermissionRequest $request)
{
    $permission = Permission::create([
        'module'      => $request->module,
        'label'       => $request->label,
        'name'        => Str::slug($request->label),
        'description' => $request->description,
    ]);

    if ($permission) {
        return redirect()->route('permissions.index')
            ->with('success', 'Permission created successfully!');
    }
}
```

--------------------------------

### TypeScript: Conditional Rendering with Permissions

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Demonstrates how to conditionally render UI elements based on user permissions. It fetches user authentication data and uses permission checks to show or hide buttons and links, ensuring users only see actions they are authorized to perform. This enhances user experience by preventing the display of irrelevant options.

```typescript
// resources/js/pages/products/index.tsx
import { usePage } from '@inertiajs/react';

export default function ProductsIndex() {
    const { auth } = usePage().props as any;
    const canCreate = auth.permissions.includes('create-product');
    const canEdit = auth.permissions.includes('edit-product');
    const canDelete = auth.permissions.includes('delete-product');

    return (
        <div>
            {canCreate && (
                <Link href="/products/create">
                    <Button>Add Product</Button>
                </Link>
            )}

            <table>
                {products.map(product => (
                    <tr key={product.id}>
                        <td>{product.name}</td>
                        <td>
                            {canEdit && (
                                <Link href={`/products/${product.id}/edit`}>Edit</Link>
                            )}
                            {canDelete && (
                                <Button onClick={() => handleDelete(product.id)}>Delete</Button>
                            )}
                        </td>
                    </tr>
                ))}
            </table>
        </div>
    );
}
```

--------------------------------

### User Model with Spatie HasRoles Trait (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Extends the base User model to include Spatie's HasRoles trait, enabling direct role and permission management on user instances. Supports assigning, syncing, and checking roles and permissions. Dependencies: Spatie Laravel Permission package.

```php
// app/Models/User.php
namespace App\Models;

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

class User extends Authenticatable
{
    use HasRoles, HasFactory, Notifiable;

    protected $fillable = ['name', 'email', 'password'];

    protected $hidden = ['password', 'remember_token'];

    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }
}

// Usage examples:
$user = User::find(1);

// Assign roles
$user->assignRole('admin');
$user->assignRole(['editor', 'user']);

// Sync roles (replace all)
$user->syncRoles(['admin']);

// Check roles
$user->hasRole('admin');           // true
$user->hasAnyRole(['admin', 'editor']); // true
$user->roles->pluck('name');       // Collection(['admin'])

// Assign permissions directly (bypass roles)
$user->givePermissionTo('edit-product');

// Check permissions
$user->can('edit-product');        // true
$user->hasPermissionTo('edit-product'); // true
$user->getAllPermissions();        // Collection of all permissions
```

--------------------------------

### Custom Permission Model with Module Grouping (PHP)

Source: https://context7.com/zanwaar/laravel12-react-roles-permissions/llms.txt

Extends Spatie's default Permission model to add a 'module' attribute for grouping permissions and a scope for filtering by module. This enhances organization and makes it easier to manage permissions related to specific application features. Dependencies: Spatie Laravel Permission package.

```php
// app/Models/Permission.php
namespace App\Models;

use Spatie\Permission\Models\Permission as SpatiePermission;

class Permission extends SpatiePermission
{
    protected $fillable = [
        'name',
        'label',
        'module',
        'description',
        'is_active',
        'guard_name',
    ];

    // Scope by module
    public function scopeModule($query, string $module)
    {
        return $query->where('module', $module);
    }
}

// Usage:
$productPermissions = Permission::module('products')->get();
// Returns: access-products-module, view-product, create-product, etc.
```
Tokens:
Raw