README

🛡️ Hyro

Hyro is a modular Laravel RBAC ecosystem featuring advanced role-permission management, admin panel, CRUD generator, plugin system, and API layer — built for scalable SaaS and enterprise applications

Modular Architecture • Production-Ready • Zero Configuration • Beautiful UI

Features • Installation • Quick Start • Documentation

🎯 Overview

Hyro is a comprehensive, enterprise-grade Role-Based Access Control (RBAC) and authorization system for Laravel 12+. Built with a modular architecture and modern best practices, Hyro provides everything you need to manage users, roles, privileges, and permissions in your Laravel applications.

Why Choose Hyro?

✅ Modular Architecture - 6 independent packages working seamlessly together
✅ Production-Ready - Battle-tested code ready for enterprise deployment
✅ Zero Configuration - Works out of the box with sensible defaults
✅ Beautiful Admin UI - Modern, responsive interface built with Livewire 3 & Tailwind CSS
✅ Powerful CRUD Generator - Generate complete CRUD interfaces in seconds with 12+ templates
✅ RESTful API - Complete API layer with Sanctum authentication
✅ Plugin System - Extensible architecture with hot-loadable plugins
✅ Comprehensive - Auth, RBAC, audit logs, 2FA, notifications, and more
✅ Well-Documented - Extensive documentation and real-world examples

🏗️ Modular Architecture

Hyro v1.0.0 features a modular architecture with 6 independent packages that work together seamlessly:

📦 Core Package (`marufsharia/hyro-core`)

Foundation of the entire system

Multi-resolution authorization engine (Token → Privilege → Wildcard → Role → Gate)
Core models: Role, Privilege, User, AuditLog, UserSuspension, HyroSetting
Events system for all RBAC operations
Middleware for route protection
Contracts and interfaces
Base services and repositories
Helper functions and utilities

Key Features:

Hierarchical RBAC with wildcard support (users.*, posts.*.edit)
Temporal access control with role expiration
User suspension management
Comprehensive audit logging with yearly partitioning
Cache invalidation system

🔐 Auth Package (`marufsharia/hyro-auth`)

Authentication and security layer

Authentication controllers and middleware
Two-Factor Authentication (2FA) with Google Authenticator
Token synchronization service for Sanctum
Emergency access commands
Password reset and recovery
Session management

Key Features:

Google Authenticator 2FA with QR codes
8 recovery codes per user
Token-based authentication
Emergency admin access
Lockdown mode for security incidents

🌐 API Package (`marufsharia/hyro-api`)

RESTful API layer

Complete REST API with RBAC integration
API controllers for users, roles, privileges, suspensions
Request validation and resources
API middleware and rate limiting
Sanctum token authentication

Endpoints:

/api/hyro/auth/* - Authentication
/api/hyro/users/* - User management
/api/hyro/roles/* - Role management
/api/hyro/privileges/* - Privilege management
/api/hyro/suspensions/* - User suspensions

🎨 Admin Panel Package (`marufsharia/hyro-admin-panel`)

Beautiful admin interface

Modern admin UI built with Livewire 3
Dashboard with statistics and charts
User, role, and privilege management interfaces
Settings system with appearance customization
Plugin manager UI
Notification center
Profile management with avatar support
Sidebar with dynamic menu system

Key Features:

Responsive design with dark mode support
Real-time updates with Livewire
Beautiful alerts with Livewire Alert
Modal dialogs with Wire Elements Modal
Customizable branding and appearance

⚡ CRUD Package (`marufsharia/hyro-crud`)

Advanced CRUD generator

Auto-generate complete CRUD interfaces
12+ beautiful templates (2 admin + 10 frontend)
Auto-generate migrations, models, routes, and views
Smart route discovery and backup system
File upload support
Search, filter, pagination, and sorting
Export functionality (CSV, Excel, PDF)
Privilege generation

Templates:

Admin: template1 (full-featured), template2 (compact)
Frontend: blog, ecommerce, portfolio, magazine, landing, news, gallery, directory, dashboard, minimal

🔌 Plugin Package (`marufsharia/hyro-plugin`)

Extensibility system

Plugin system with hot-loading
Remote plugin installation (GitHub, GitLab, Packagist)
Hook system for extensibility
Plugin marketplace integration
Plugin activity logging
Plugin settings management
Plugin permissions and dependencies

Key Features:

Install plugins from remote sources
Activate/deactivate without code changes
Hook into system events
Plugin-specific settings
Version management

✨ Key Features

🔐 Advanced Authorization

Multi-Resolution Authorization: Token → Privilege → Wildcard → Role → Gate
Hierarchical RBAC: Roles with inherited privileges
Wildcard Privileges: users.* matches users.create, users.edit, etc.
Temporal Access: Role expiration and time-based access
User Suspension: Temporary or permanent account suspension
Protected Roles: Prevent deletion of critical roles (super-admin, admin)

📊 Enterprise Audit Logging

Comprehensive audit trail for all actions
Yearly table partitioning for performance
Sensitive data sanitization (passwords, tokens)
Batch tracking with UUID
Tag-based filtering and search
User activity logs

🔔 Notification System

Multi-channel notifications (Email, Database, Push, SMS)
Beautiful notification center UI
Real-time notification bell
User preference management
Queue support for performance
7 built-in notification types

⚡ CRUD Generator

Generate complete CRUD in seconds
12+ beautiful templates
Production-ready code with zero manual fixes
Auto-generate migrations, models, routes, views
File upload support
Search, pagination, sorting
Export to CSV/Excel/PDF
Automatic privilege creation

👤 User Profile Management

Complete profile information management
Avatar management (upload/Gravatar/default)
Password change with strong validation
Two-factor authentication setup
Account deletion with 30-day grace period
User activity logging
Timezone and locale settings

🎨 Beautiful Admin UI

Modern Tailwind CSS interface
Livewire 3.x components
Alpine.js interactivity
Fully responsive design
Dark mode support
Customizable branding
Icon customization (115+ Heroicons)

💻 50+ CLI Commands

User management commands
Role and privilege management
Plugin management
Database backup and restore
Emergency access commands
CRUD generation commands

📋 Requirements

PHP: 8.2 or higher
Laravel: 12.0 or higher
Database: MySQL 8.0+, PostgreSQL 13+, or SQLite 3.35+
Composer: 2.0 or higher
Node.js: 18+ (for asset compilation)
NPM/Yarn: Latest version

Required PHP Extensions

OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath, Fileinfo

🚀 Installation

Step 1: Install via Composer

composer require marufsharia/hyro

Step 2: Publish Configuration and Assets

# Publish configuration
php artisan vendor:publish --tag=hyro-config

# Publish migrations
php artisan vendor:publish --tag=hyro-migrations

# Publish assets (CSS, JS, images)
php artisan vendor:publish --tag=hyro-assets

Step 3: Configure Environment

Add to your .env file:

# Core Settings
HYRO_ENABLED=true
HYRO_ADMIN_PREFIX=admin/hyro

# Features
HYRO_API_ENABLED=true
HYRO_ADMIN_ENABLED=true
HYRO_CLI_ENABLED=true

# Security
HYRO_FAIL_CLOSED=true
HYRO_PROTECTED_ROLES=super-admin,admin
HYRO_PASSWORD_MIN_LENGTH=8

# Cache
HYRO_CACHE_ENABLED=true
HYRO_CACHE_TTL=3600

# Audit Logging
HYRO_AUDIT_ENABLED=true
HYRO_AUDIT_RETENTION_DAYS=365

Step 4: Run Migrations

php artisan migrate

Step 5: Create Admin User

php artisan hyro:user:create --admin

Follow the prompts to create your first admin user.

Step 6: Add Trait to User Model

Edit app/Models/User.php:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Marufsharia\Hyro\Core\Traits\HasHyroFeatures;

class User extends Authenticatable
{
    use HasHyroFeatures;
    
    // ... rest of your User model
}

Step 7: Compile Assets (Optional)

npm install
npm run build

That's it! Visit /admin/hyro to access the admin panel.

🎯 Quick Start

Check Roles and Privileges

// Check if user has a role
if (auth()->user()->hasRole('admin')) {
    // Admin only code
}

// Check if user has a privilege
if (auth()->user()->hasPrivilege('users.create')) {
    // Create user
}

// Check multiple roles (any)
if (auth()->user()->hasAnyRole(['admin', 'moderator'])) {
    // Admin or moderator code
}

// Check multiple privileges (all)
if (auth()->user()->hasAllPrivileges(['users.create', 'users.edit'])) {
    // User can create and edit
}

Use Blade Directives

@hasrole('admin')
    <a href="/admin">Admin Panel</a>
@endhasrole

@hasprivilege('posts.create')
    <button>Create Post</button>
@endhasprivilege

@hasanyrole(['admin', 'moderator'])
    <div>Admin or Moderator Content</div>
@endhasanyrole

@hasallprivileges(['posts.create', 'posts.edit'])
    <button>Manage Posts</button>
@endhasallprivileges

Protect Routes

use Illuminate\Support\Facades\Route;

// Require specific role
Route::middleware(['hyro.role:admin'])->group(function () {
    Route::get('/admin', [AdminController::class, 'index']);
});

// Require specific privilege
Route::middleware(['hyro.privilege:users.create'])->group(function () {
    Route::post('/users', [UserController::class, 'store']);
});

// Require any of multiple roles
Route::middleware(['hyro.role:admin,moderator'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

// Require all privileges
Route::middleware(['hyro.privilege:posts.create,posts.edit'])->group(function () {
    Route::resource('posts', PostController::class);
});

⚡ CRUD Generator

Generate complete CRUD interfaces in seconds with beautiful templates!

Basic Usage

# Generate admin CRUD
php artisan hyro:make-crud Product \
    --fields="name:string,price:decimal,stock:integer" \
    --migration

# Generate frontend CRUD with template
php artisan hyro:make-crud Product \
    --frontend=true \
    --template=frontend.ecommerce \
    --fields="name:string,description:text,image:image,price:decimal" \
    --migration

Available Templates

Admin Templates

admin.template1 - Full-featured dashboard (default)
admin.template2 - Compact data entry

Frontend Templates

frontend.blog - Blog/article layout
frontend.ecommerce - E-commerce product grid
frontend.portfolio - Portfolio/gallery masonry
frontend.magazine - Magazine-style layout
frontend.landing - Landing page cards
frontend.news - News/media layout
frontend.gallery - Photo gallery grid
frontend.directory - Business directory list
frontend.dashboard - Data dashboard table
frontend.minimal - Minimal clean design

Real-World Example: E-commerce Products

php artisan hyro:make-crud Product \
    --frontend=true \
    --template=frontend.ecommerce \
    --fields="name:string:required,description:text,price:decimal:required,stock:integer,image:image,category:string" \
    --searchable="name,description,category" \
    --sortable="name,price,stock" \
    --export \
    --migration

What Gets Generated

✅ Livewire component with full CRUD logic
✅ Beautiful Blade view with chosen template
✅ Database migration
✅ Eloquent model (if doesn't exist)
✅ Routes (admin or frontend)
✅ Automatic route backup
✅ Search, filter, and pagination
✅ File upload support
✅ Export functionality (optional)
✅ Privilege creation (optional)

Supported Field Types

string - Text input
text - Textarea
email - Email input
number / integer - Number input
decimal - Decimal number
boolean / checkbox - Checkbox
date - Date picker
datetime - DateTime picker
image - Image upload
file - File upload
select - Dropdown select

⚙️ Configuration

Environment Variables

# Core Features
HYRO_ENABLED=true
HYRO_API_ENABLED=true
HYRO_ADMIN_ENABLED=true
HYRO_CLI_ENABLED=true

# Admin Panel
HYRO_ADMIN_PREFIX=admin/hyro

# Security
HYRO_FAIL_CLOSED=true
HYRO_PROTECTED_ROLES=super-admin,admin
HYRO_PASSWORD_MIN_LENGTH=8
HYRO_MAX_LOGIN_ATTEMPTS=5

# Cache
HYRO_CACHE_ENABLED=true
HYRO_CACHE_TTL=3600

# Audit Logging
HYRO_AUDIT_ENABLED=true
HYRO_AUDIT_RETENTION_DAYS=365

# Database Backup
HYRO_DB_BACKUP_ENABLED=true
HYRO_DB_BACKUP_DISK=local
HYRO_DB_BACKUP_COMPRESS=true
HYRO_DB_BACKUP_RETENTION=30

Publish Configuration Files

# Publish main config
php artisan vendor:publish --tag=hyro-config

# Publish views (for customization)
php artisan vendor:publish --tag=hyro-views

# Publish translations
php artisan vendor:publish --tag=hyro-translations

# Publish CRUD templates
php artisan vendor:publish --tag=hyro-templates

💡 Usage Examples

User Management

use Marufsharia\Hyro\Models\Role;
use Marufsharia\Hyro\Models\Privilege;

// Create a role
$role = Role::create([
    'name' => 'Editor',
    'slug' => 'editor',
    'description' => 'Content editor role'
]);

// Create a privilege
$privilege = Privilege::create([
    'name' => 'Edit Posts',
    'slug' => 'posts.edit',
    'description' => 'Can edit blog posts'
]);

// Assign privilege to role
$role->grantPrivilege($privilege);

// Assign role to user
$user->assignRole($role);

// Check permissions
if ($user->hasRole('editor')) {
    // User is an editor
}

if ($user->hasPrivilege('posts.edit')) {
    // User can edit posts
}

Wildcard Privileges

// Grant wildcard privilege
$privilege = Privilege::create([
    'slug' => 'posts.*',  // Matches posts.create, posts.edit, posts.delete, etc.
]);

$role->grantPrivilege($privilege);

// Now user with this role can do anything with posts
$user->hasPrivilege('posts.create');  // true
$user->hasPrivilege('posts.edit');    // true
$user->hasPrivilege('posts.delete');  // true

Suspend Users

use Carbon\Carbon;

// Suspend user for 7 days
$user->suspend(
    reason: 'Violation of terms',
    until: Carbon::now()->addDays(7)
);

// Check if suspended
if ($user->isSuspended()) {
    // User is suspended
}

// Unsuspend user
$user->unsuspend();

Audit Logging

use Marufsharia\Hyro\Core\Facades\Hyro;

// Log an action
Hyro::audit()
    ->log('user.login')
    ->on($user)
    ->withProperties(['ip' => request()->ip()])
    ->save();

// Query audit logs
$logs = Hyro::audit()
    ->forUser($user)
    ->forAction('user.login')
    ->inDateRange($startDate, $endDate)
    ->get();

🔧 CLI Commands

User Management

php artisan hyro:user:create              # Create new user
php artisan hyro:user:create --admin      # Create admin user
php artisan hyro:user:list                # List all users
php artisan hyro:user:suspend             # Suspend user
php artisan hyro:user:unsuspend           # Unsuspend user

Role Management

php artisan hyro:role:create              # Create new role
php artisan hyro:role:list                # List all roles
php artisan hyro:role:assign              # Assign role to user
php artisan hyro:role:revoke              # Revoke role from user

Privilege Management

php artisan hyro:privilege:create         # Create privilege
php artisan hyro:privilege:list           # List privileges
php artisan hyro:privilege:grant          # Grant privilege to role
php artisan hyro:privilege:revoke         # Revoke privilege from role

CRUD Generator

php artisan hyro:make-crud                # Generate CRUD components
php artisan hyro:discover-routes          # Auto-discover routes

Plugin Management

php artisan hyro:plugin:list              # List installed plugins
php artisan hyro:plugin:make              # Create new plugin
php artisan hyro:plugin:install           # Install plugin
php artisan hyro:plugin:activate          # Activate plugin
php artisan hyro:plugin:deactivate        # Deactivate plugin

Emergency Access

php artisan hyro:emergency:create-admin   # Create emergency admin
php artisan hyro:emergency:grant-access   # Grant emergency access

🔌 API Documentation

Authentication Endpoints

POST   /api/hyro/auth/login       # Login and get token
POST   /api/hyro/auth/register    # Register new user
POST   /api/hyro/auth/logout      # Logout and revoke token
POST   /api/hyro/auth/refresh     # Refresh token
GET    /api/hyro/auth/user        # Get authenticated user

User Management Endpoints

GET    /api/hyro/users            # List all users
POST   /api/hyro/users            # Create new user
GET    /api/hyro/users/{id}       # Get user details
PUT    /api/hyro/users/{id}       # Update user
DELETE /api/hyro/users/{id}       # Delete user

Example API Usage

# Login
curl -X POST http://your-app.com/api/hyro/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}'

# Response
{
  "token": "1|abc123...",
  "user": {
    "id": 1,
    "name": "Admin User",
    "email": "admin@example.com"
  }
}

# Use token for authenticated requests
curl -X GET http://your-app.com/api/hyro/users \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Accept: application/json"

🛡️ Security

Security Features

✅ Fail-Closed Authorization - Deny by default
✅ Protected Roles - Prevent deletion of critical roles
✅ Comprehensive Audit Logging - Complete audit trail
✅ Sensitive Data Sanitization - Automatic password/token redaction
✅ Rate Limiting - API rate limiting
✅ Token Management - Sanctum integration with auto-sync
✅ Suspension System - Temporal access control
✅ CSRF Protection - Laravel CSRF protection
✅ SQL Injection Prevention - Eloquent ORM
✅ XSS Prevention - Blade templating

Reporting Security Issues

Please report security vulnerabilities to: marufsharia@gmail.com

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

Hyro is open-sourced software licensed under the MIT license.

👨‍💻 Author

Maruf Sharia

Email: marufsharia@gmail.com
GitHub: @marufsharia

🙏 Acknowledgments

Laravel Framework
Livewire
Tailwind CSS
Alpine.js
All contributors and supporters

Made with ❤️ by Maruf Sharia

⬆ Back to Top

marufsharia / hyro

Maintainers

Details

README

🛡️ Hyro

Hyro is a modular Laravel RBAC ecosystem featuring advanced role-permission management, admin panel, CRUD generator, plugin system, and API layer — built for scalable SaaS and enterprise applications

📋 Table of Contents

🎯 Overview

Why Choose Hyro?

🏗️ Modular Architecture

📦 Core Package (marufsharia/hyro-core)

🔐 Auth Package (marufsharia/hyro-auth)

🌐 API Package (marufsharia/hyro-api)

🎨 Admin Panel Package (marufsharia/hyro-admin-panel)

⚡ CRUD Package (marufsharia/hyro-crud)

🔌 Plugin Package (marufsharia/hyro-plugin)

✨ Key Features

🔐 Advanced Authorization

📊 Enterprise Audit Logging

🔔 Notification System

⚡ CRUD Generator

👤 User Profile Management

🎨 Beautiful Admin UI

💻 50+ CLI Commands

📋 Requirements

Required PHP Extensions

🚀 Installation

Step 1: Install via Composer

Step 2: Publish Configuration and Assets

Step 3: Configure Environment

Step 4: Run Migrations

Step 5: Create Admin User

Step 6: Add Trait to User Model

Step 7: Compile Assets (Optional)

🎯 Quick Start

Check Roles and Privileges

Use Blade Directives

Protect Routes

⚡ CRUD Generator

Basic Usage

Available Templates

Admin Templates

Frontend Templates

Real-World Example: E-commerce Products

What Gets Generated

Supported Field Types

⚙️ Configuration

Environment Variables

Publish Configuration Files

💡 Usage Examples

User Management

Wildcard Privileges

Suspend Users

Audit Logging

🔧 CLI Commands

User Management

Role Management

Privilege Management

CRUD Generator

Plugin Management

Emergency Access

🔌 API Documentation

Authentication Endpoints

User Management Endpoints

Example API Usage

🛡️ Security

Security Features

Reporting Security Issues

🤝 Contributing

📄 License

👨‍💻 Author

🙏 Acknowledgments

📦 Core Package (`marufsharia/hyro-core`)

🔐 Auth Package (`marufsharia/hyro-auth`)

🌐 API Package (`marufsharia/hyro-api`)

🎨 Admin Panel Package (`marufsharia/hyro-admin-panel`)

⚡ CRUD Package (`marufsharia/hyro-crud`)

🔌 Plugin Package (`marufsharia/hyro-plugin`)