Forem: Hossein Hezami

Master Role-Based Access Control with Laravel Permission Manager

Hossein Hezami — Wed, 24 Sep 2025 14:33:20 +0000

Building a secure, scalable Laravel application often requires a robust permission management system. Enter Laravel Permission Manager, a powerful package designed to streamline role-based access control (RBAC) with a flexible, feature-rich API. Whether you're securing routes, managing roles, or integrating permissions into your Blade templates, this package has you covered. In this post, I'll walk you through its installation, configuration, and usage to help you implement a bulletproof RBAC system in your Laravel app.

Why Laravel Permission Manager?

The Laravel Permission Manager package, developed by Hossein Hezami, offers a comprehensive solution for managing roles and permissions in Laravel applications. Here’s what makes it stand out:

Role-Based Access Control (RBAC): Assign multiple roles to users and permissions to roles.
Wildcard Permissions: Support for flexible route matching (e.g., admin.*, *admin*).
Blade Directives: Easily check roles and permissions in templates with @hasRole and @hasPermission.
Artisan Commands: Manage roles and permissions from the command line.
Facade Methods: Programmatically handle roles and permissions with a fluent API.
Middleware Support: Protect routes with role or permission checks.
Caching: Boost performance with permission caching.
Multi-Guard Support: Works seamlessly with Laravel’s authentication guards.
Export/Import: Save and restore roles/permissions as JSON.

Ready to get started? Let’s dive into the setup and usage.

Installation

Installing Laravel Permission Manager is straightforward with Composer. Follow these steps to integrate it into your Laravel project:

Install the Package Run the following command to install the package:

   composer require hosseinhezami/laravel-permission-manager

Register the Service Provider (Optional) If Laravel’s package auto-discovery is disabled, add the service provider and facade to config/app.php:

   'providers' => [
       // ...
       HosseinHezami\PermissionManager\PermissionManagerServiceProvider::class,
   ],
   'aliases' => [
       // ...
       'PermissionManager' => HosseinHezami\PermissionManager\Facades\PermissionManager::class,
   ],

Publish Configuration and Migrations Publish the configuration file and migrations to set up the package:

   php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="config"
   php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"

Run Migrations Create the necessary database tables for roles and permissions:

   php artisan migrate

Add the Permission Trait Add the PermissionTrait to your User model:

   namespace App\Models;

   use HosseinHezami\PermissionManager\Traits\PermissionTrait;
   use Illuminate\Foundation\Auth\User as Authenticatable;

   class User extends Authenticatable
   {
       use PermissionTrait;
   }

Run the Install Command For a streamlined setup, use the Artisan install command. Here are some variations:

   # Basic installation
   php artisan permission-manager:install

   # Install and run migrations
   php artisan permission-manager:install --migrate

   # Install, run migrations, and overwrite existing files
   php artisan permission-manager:install --migrate --force

   # Install with a custom User model path
   php artisan permission-manager:install --user-model=/path/to/User.php

Configuration

After publishing the configuration, you can customize the package in config/permission-manager.php. Here’s a sample configuration:

return [
    'models' => [
        'role' => \HosseinHezami\PermissionManager\Models\Role::class,
        'permission' => \HosseinHezami\PermissionManager\Models\Permission::class,
        'user' => \App\Models\User::class,
    ],
    'tables' => [
        'roles' => 'roles',
        'permissions' => 'permissions',
        'role_permissions' => 'role_permissions',
        'user_roles' => 'user_roles',
    ],
    'cache_duration' => 60, // Cache permissions for 60 minutes
    'log_denials' => false, // Log permission/role denials
    'wildcards' => true, // Enable wildcard support
];

This file lets you tweak model classes, table names, caching duration, and wildcard support to suit your application’s needs.

Database Migrations

The package creates four tables to manage roles and permissions:

roles: Stores role details (name, slug, description).
permissions: Stores permission routes (e.g., users.edit).
role_permissions: Links roles to permissions.
user_roles: Links users to roles.

The migrations are automatically published when you run the vendor:publish command for the migrations tag.

Usage

Let’s explore how to leverage Laravel Permission Manager in your application.

1. Blade Directives

Control access in your Blade templates with intuitive directives:

@hasRole('admin')
    <p>Welcome, Admin!</p>
@endhasRole

@hasPermission('users.edit')
    <a href="/users/edit">Edit User</a>
@endhasPermission

These directives make it easy to show or hide content based on roles or permissions.

2. Middleware

Protect routes with middleware for roles or permissions:

Route::get('/admin', [AdminController::class, 'index'])
    ->middleware('pm:role:admin|manager');

Route::get('/posts', [PostController::class, 'create'])
    ->middleware('pm:permission:posts|post.create');

The pm middleware ensures only users with the specified roles or permissions can access the route.

3. Artisan Commands

Manage roles and permissions directly from the terminal:

# List roles and permissions
php artisan roles:list
php artisan permissions:list

# Create a role
php artisan role:create admin "Administrator" "Has full system access"

# Update a role
php artisan role:update admin --name="Super Admin" --description="Updated description"

# Delete a role
php artisan role:delete admin

# Create permissions
php artisan permission:create "users.*"
php artisan permission:create "users.create,users.edit"

# Sync routes with permissions
php artisan permission:sync-routes

# Assign/revoke permissions to a role
php artisan role:assign-permission admin "users.*"
php artisan role:revoke-permission admin "users.edit"

# Assign/revoke roles to a user
php artisan user:assign-role 1 admin
php artisan user:revoke-role 1 admin

# Export/import roles
php artisan role:export roles.json
php artisan role:import roles.json

These commands make it easy to manage your RBAC system without writing code.

4. Facade Methods

For programmatic control, use the PermissionManager facade:

use HosseinHezami\PermissionManager\Facades\PermissionManager;

// Create a role
PermissionManager::roles()->create([
    'slug' => 'admin',
    'name' => 'Administrator',
    'description' => 'Has full system access'
]);

// Assign permissions to a role
PermissionManager::role('admin')->assignPermission('users.edit');

// Assign a role to a user
PermissionManager::user(1)->assignRole('admin');

// Check permissions
$hasPermission = PermissionManager::user(1)->hasPermission('users.edit');

5. Wildcard Permissions

Wildcard permissions add flexibility to route matching:

// Match all routes starting with 'admin'
PermissionManager::permissions()->create('admin.*');

// Match all routes containing 'admin'
PermissionManager::permissions()->create('*admin*');

6. Trait Methods

The PermissionTrait adds convenient methods to your User model:

$user = User::find(1);

// Assign a role
$user->assignRole('admin');

// Check permissions
if ($user->hasPermission('users.edit')) {
    // Allow edit action
}

Best Practices

Use Descriptive Slugs: Choose clear, meaningful slugs for roles and permissions (e.g., users.edit instead of edit).
Leverage Wildcards: Group related routes with wildcards (e.g., users.* for all user-related actions).
Sync Routes Regularly: Run php artisan permission:sync-routes to keep permissions aligned with your routes.
Enable Caching: Set a reasonable cache_duration in production to improve performance.
Handle Exceptions: Use the package’s custom exceptions (e.g., UnauthorizedException) for robust error handling.

Conclusion

The Laravel Permission Manager package is a game-changer for developers building secure Laravel applications. Its intuitive API, comprehensive Artisan commands, and flexible features like wildcard permissions and Blade directives make it a must-have for implementing RBAC. Whether you’re managing a small app or a large-scale system, this package simplifies access control without compromising on power.

Check out the official documentation for more details, and feel free to contribute via the GitHub repository. Got questions? Reach out to the maintainer at hossein.hezami@gmail.com.

What’s your favorite way to manage permissions in Laravel? Share your thoughts in the comments!

Build Laravel AI Features in Minutes: A Guide to the Gemini Package

Hossein Hezami — Fri, 12 Sep 2025 23:40:51 +0000

Tired of reading docs and just want to see the code? Let's dive straight into how you can use the hosseinhezami/laravel-gemini package to add powerful AI features to your Laravel application. The API is clean, fluent, and incredibly powerful.

Installation & Setup

First, get the package.

composer require hosseinhezami/laravel-gemini

Publish the config file and set your API key.

php artisan vendor:publish --tag=gemini-config

# .env
GEMINI_API_KEY=your_gemini_api_key_here

Code Examples: See It in Action

1. Basic Text Generation & Chat

The TextBuilder makes generating text or creating a chat interface simple.

use HosseinHezami\LaravelGemini\Facades\Gemini;

// Simple prompt
$response = Gemini::text()
    ->prompt('Write a tagline for a developer blog.')
    ->generate();

echo $response->content();

// Chat with history
$history = [
    ['role' => 'user', 'parts' => [['text' => 'Hello!']]],
    ['role' => 'model', 'parts' => [['text' => 'Hi there! How can I help?']]]
];

$response = Gemini::text()
    ->prompt('What’s the weather like?')
    ->history($history)
    ->temperature(0.7)
    ->generate();

echo $response->content();

2. Structured Data Extraction

Need consistent JSON output from a messy prompt? Use structuredSchema.

$response = Gemini::text()
    ->structuredSchema([
        'type' => 'object',
        'properties' => [
            'sentiment' => [
                'type' => 'string',
                'enum' => ['positive', 'negative', 'neutral']
            ],
            'confidence' => ['type' => 'number'],
            'key_points' => {
                'type' => 'array',
                'items' => {'type' => 'string'}
            }
        ],
        'required' => ['sentiment']
    ])
    ->prompt('The product is amazing but the delivery was late. I love the features though.')
    ->generate();

$analysis = json_decode($response->content());
// $analysis->sentiment, $analysis->key_points, etc.

3. Image Generation

Generate images from a text description.

$response = Gemini::image()
    ->prompt('A minimalist logo for a tech startup called "Nexus", using blue and green')
    ->generate();

// Save the generated image directly
$response->save(storage_path('app/logo.png'));

4. Document Understanding

Upload a file (PDF, DOC, image) and ask questions about it.

// First, upload the file to Gemini's servers
$fileUri = Gemini::files()->upload('document', $pathToInvoicePdf);

// Then, use it in a prompt
$response = Gemini::text()
    ->upload('document', $pathToInvoicePdf) // or use the $fileUri
    ->prompt('What is the total amount due on this invoice?')
    ->generate();

echo $response->content();

5. Text-to-Speech (Audio)

Generate spoken audio from text.

$response = Gemini::audio()
    ->prompt('Welcome to our application. We are thrilled to have you on board.')
    ->voiceName('Kore') // Check docs for available voices
    ->generate();

// The package smartly handles the binary response,
// allowing you to save it directly.
$response->save(public_path('audio/welcome.mp3'));

6. Real-Time Streaming

Crucial for building chat interfaces that feel fast and responsive.

// In your controller (e.g., app/Http/Controllers/ChatController.php)
public function stream(Request $request)
{
    return response()->stream(function () use ($request) {
        Gemini::text()
            ->model('gemini-2.5-flash-lite') // Use a fast model for streaming
            ->prompt($request->query('message'))
            ->stream(function ($chunk) {
                $text = $chunk['text'] ?? '';
                if (connection_aborted()) return;
                echo "data: " . json_encode(['text' => $text]) . "\n\n";
                ob_flush();
                flush();
            });
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
        'Connection' => 'keep-alive',
        'X-Accel-Buffering' => 'no',
    ]);
}

Ready to Build?

This is just the surface. The package also handles video generation, embeddings, and full file management.

For complete documentation, check out the official docs:
https://hosseinhezami.github.io/laravel-gemini/

Source:

What will you build first? Let me know in the comments! 👇

TOTP Authenticator: A Lightweight PHP Library for Secure Two-Factor Authentication

Hossein Hezami — Fri, 05 Sep 2025 11:08:13 +0000

Two-Factor Authentication (2FA) has become an essential layer of security for web applications, helping protect user accounts even if passwords are compromised. Among the most widely used 2FA methods is TOTP (Time-based One-Time Password), supported by popular apps like Google Authenticator, Authy, and Microsoft Authenticator.

For PHP developers looking to add TOTP-based authentication to their projects, TOTP Authenticator provides a simple, lightweight, and secure solution.

Key Features

🔐 Secure Secret Generation: Generates cryptographically secure secrets with configurable lengths.

⏱ Time-based OTP Generation: Produces 6-digit one-time passwords compliant with RFC 6238.

✅ Code Verification: Validates user input with support for slight time drift to accommodate clock differences.

📱 QR Code Generation: Creates URLs compatible with Google Authenticator and similar 2FA apps.

🔒 Timing-Safe Comparison: Protects against timing attacks during code verification.

💡 Zero Dependencies: Pure PHP library (requires PHP 7.4 or higher).

Installation
Install the library easily using Composer:

composer require hosseinhezami/totp-authenticator

Getting Started
Here's a quick example demonstrating the core functionality of the library:

use HosseinHezami\TotpAuthenticator\Authenticator;

// Generate a secure secret
$secret = Authenticator::createSecret(16);

// Generate a TOTP code
$code = Authenticator::generateCode($secret);

// Verify the code
$isValid = Authenticator::verifyCode($secret, $code);
echo $isValid ? "Valid code" : "Invalid code";

// Generate a QR code URL for Google Authenticator
$qrCodeUrl = Authenticator::generateQrCodeUrl("user@example.com", $secret, "MyApp");
echo $qrCodeUrl;

The QR code URL can be scanned directly in any TOTP-compatible authenticator app.
Verification uses timing-safe comparison to ensure maximum security.

Laravel Integration Example
Integrating this library into a Laravel project is straightforward. For example, a route can be defined to test all the functionalities:

use HosseinHezami\TotpAuthenticator\Authenticator;
Route::get('/totp-test', function () {
    $secret = Authenticator::createSecret(16);
    $code = Authenticator::generateCode($secret);
    $isValid = Authenticator::verifyCode($code, $secret);
    $qrCodeUrl = Authenticator::generateQrCodeUrl('testuser@example.com', $secret, 'MyApp');

    return response()->json([
        'secret' => $secret,
        'generated_code' => $code,
        'verify_code' => $isValid,
        'qr_code_url' => $qrCodeUrl
    ]);
});

This provides a ready-to-use JSON response for testing secret generation, code verification, and QR code creation.

Why Use TOTP Authenticator?

Lightweight & Minimal Setup: Easy to integrate without heavy dependencies.
Secure & Standards-Compliant: Follows RFC 6238 and implements cryptographically secure operations.
Flexible: Works in both plain PHP and frameworks like Laravel.
Developer-Friendly: Provides all the core TOTP functionality without complexity.

Resources
GitHub: https://github.com/hosseinhezami/totp-authenticator
Packagist: https://packagist.org/packages/hosseinhezami/totp-authenticator