Laravel Tyro

Default seeded roles:

• super-admin - Full system access
• administrator - Administrative access
• editor - Content management
• user - Standard registered user
• customer - Customer account
• all - Universal access (wildcard)

Default credentials (after seeding):

• Email: [email protected]
• Password: tyro

Installation & Setup

One-Command Installation

composer require hasinhayder/tyro
php artisan tyro:sys-install

This single command:

1. Installs and configures Sanctum
2. Runs migrations
3. Prompts to seed roles/privileges/admin user
4. Prepares your User model

Manual Installation Steps

If you need more control:

# Install package
composer require hasinhayder/tyro

# Publish assets (optional)
php artisan vendor:publish --tag=tyro-config
php artisan vendor:publish --tag=tyro-migrations

# Run migrations
php artisan migrate

# Seed roles and privileges
php artisan tyro:seed-all --force

# Prepare User model
php artisan tyro:user-prepare

User Model Requirements

Your User model (default: App\Models\User) must use the HasTyroRoles trait:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;
use HasinHayder\Tyro\Concerns\HasTyroRoles;

class User extends Authenticatable
{
    use HasApiTokens, HasTyroRoles;
}

The trait provides ALL role/privilege methods. No other code changes needed.

CLI Commands Reference

System Commands

# Full installation
php artisan tyro:sys-install

# Prepare User model with trait
php artisan tyro:user-prepare

# Show version
php artisan tyro:sys-version

# Show package info
php artisan tyro:sys-about

# Open documentation
php artisan tyro:sys-doc

# Open GitHub repo
php artisan tyro:sys-star

# Get Postman collection
php artisan tyro:sys-postman

User Management

# Create user with default role
php artisan tyro:user-create

# List all users
php artisan tyro:user-list

# List users with roles
php artisan tyro:user-list-with-roles

# Update user
php artisan tyro:user-update --user=1 --name="New Name"

# Delete user (prevents deleting last admin)
php artisan tyro:user-delete --user=1

# Suspend user (revokes all tokens)
php artisan tyro:user-suspend [email protected] --reason="Policy violation"

# Unsuspend user
php artisan tyro:user-unsuspend [email protected]

# List suspended users
php artisan tyro:user-suspended

# Show user's roles and privileges
php artisan tyro:user-roles --user=1

Role Management

# List all roles
php artisan tyro:role-list

# List roles with privileges
php artisan tyro:role-list-with-privileges

# Create new role
php artisan tyro:role-create --name="Content Manager" --slug="content-manager"

# Update role
php artisan tyro:role-update --role="content-manager" --name="Content Editor"

# Delete role (protected roles cannot be deleted)
php artisan tyro:role-delete --role="content-manager"

# Assign role to user
php artisan tyro:role-assign --user=5 --role="editor"

# Remove role from user
php artisan tyro:role-remove --user=5 --role="editor"

# List users with specific role
php artisan tyro:role-users --role="editor"

Privilege Management

# List all privileges
php artisan tyro:privilege-list

# Create privilege
php artisan tyro:privilege-create --name="Delete Articles" --slug="articles.delete"

# Update privilege
php artisan tyro:privilege-update --privilege="articles.delete" --name="Remove Articles"

# Delete privilege
php artisan tyro:privilege-delete --privilege="articles.delete"

# Attach privilege to role
php artisan tyro:privilege-attach --role="editor" --privilege="articles.publish"

# Detach privilege from role
php artisan tyro:privilege-detach --role="editor" --privilege="articles.publish"

# Show user's privileges
php artisan tyro:user-privileges --user=1

Authentication & Token Management

# Login (mint token)
php artisan tyro:auth-login [email protected]

# Create token without password
php artisan tyro:user-token --user=1

# Revoke specific token
php artisan tyro:auth-logout --token=xyz

# Revoke all user tokens
php artisan tyro:auth-logout-all --user=1

# Emergency: revoke ALL tokens
php artisan tyro:auth-logout-all-users --force

# Inspect token
php artisan tyro:auth-me --token=xyz

Seeding Commands

# Seed everything (roles, privileges, admin user)
php artisan tyro:seed-all --force

# Seed only roles
php artisan tyro:seed-roles --force

# Seed only privileges
php artisan tyro:seed-privileges --force

# Purge all roles
php artisan tyro:role-purge --force

# Purge all privileges
php artisan tyro:privilege-purge --force

Audit Commands

# List audit logs
php artisan tyro:audit-list --limit=50

# Filter by event type
php artisan tyro:audit-list --event=role.assigned

# Purge old logs (respects retention_days config)
php artisan tyro:audit-purge --days=30

Middleware Reference

Available Middleware

Route Protection Examples

use Illuminate\Support\Facades\Route;

// Require admin role only
Route::middleware(['auth:sanctum', 'role:admin'])
    ->get('admin/dashboard', [AdminDashboardController::class, 'index']);

// Require both admin AND super-admin
Route::middleware(['auth:sanctum', 'role:admin,super-admin'])
    ->delete('users/{user}', [UserController::class, 'destroy']);

// Allow editor OR admin
Route::middleware(['auth:sanctum', 'roles:editor,admin'])
    ->post('articles/publish', [ArticleController::class, 'publish']);

// Require specific privilege
Route::middleware(['auth:sanctum', 'privilege:reports.run'])
    ->get('reports', [ReportController::class, 'index']);

// Allow any of multiple privileges
Route::middleware(['auth:sanctum', 'privileges:billing.view,reports.run'])
    ->get('dashboard', [DashboardController::class, 'index']);

// Combine multiple middleware
Route::middleware(['auth:sanctum', 'role:admin', 'privilege:users.delete'])
    ->delete('users/{user}', [UserController::class, 'destroy']);

// Audit sensitive routes
Route::middleware(['auth:sanctum', 'role:admin', 'tyro.log'])
    ->post('roles', [RoleController::class, 'store']);

Blade Directives Reference

All Directives

All directives return false if no user is authenticated.

Usage Examples

@hasRole('admin')
    <div class="admin-panel">
        <h2>Admin Dashboard</h2>
    </div>
@endhasRole

@hasAnyRole('editor', 'author')
    <div class="content-tools">
        <a href="/articles/create">New Article</a>
    </div>
@endhasAnyRole

@hasAllRoles('admin', 'super-admin')
    <button class="btn-danger">Delete User</button>
@endhasAllRoles

@hasPrivilege('articles.publish')
    <button class="btn-success">Publish</button>
@endhasPrivilege

@hasAnyPrivilege('articles.edit', 'articles.delete')
    <div class="article-actions">
        @hasPrivilege('articles.edit')
            <button>Edit</button>
        @endhasPrivilege
        @hasPrivilege('articles.delete')
            <button>Delete</button>
        @endhasPrivilege
    </div>
@endhasAnyPrivilege

@userCan('admin')
    <!-- Checks both role 'admin' and privilege 'admin' -->
    <div>Admin content</div>
@enduserCan

@hasRole('subscriber')
    <div class="premium-content">
        {{ $article->premium_content }}
    </div>
@else
    <p>This is premium content. <a href="/subscribe">Subscribe now</a></p>
@endhasRole

REST API Reference

Base URL

All routes are prefixed by config('tyro.route_prefix') (default: api)

Authentication

Include Bearer token in headers:

Authorization: Bearer {token}

Public Endpoints

GET    /api/tyro              # Package information
GET    /api/tyro/version      # Version number
POST   /api/login             # Authenticate, receive token
POST   /api/users             # Register new user

Authenticated Endpoints

GET    /api/me                # Current user info
PUT    /api/users/{user}      # Update self
POST   /api/users/{user}      # Update self
DELETE /api/users/{user}      # Delete own account

Admin Endpoints (require admin role)

User Management:

GET    /api/users             # List all users
GET    /api/users/{user}      # Get user details
DELETE /api/users/{user}      # Delete user (admin)
POST   /api/users/{user}/roles        # Assign role
DELETE /api/users/{user}/roles/{role} # Remove role
POST   /api/users/{user}/suspend      # Suspend user
DELETE /api/users/{user}/suspend      # Unsuspend user

Role Management:

GET    /api/roles             # List roles
POST   /api/roles             # Create role
GET    /api/roles/{role}      # Get role details
PUT    /api/roles/{role}      # Update role
DELETE /api/roles/{role}      # Delete role
GET    /api/roles/{role}/users      # Users with role
GET    /api/roles/{role}/privileges  # Role privileges
POST   /api/roles/{role}/privileges  # Attach privilege
DELETE /api/roles/{role}/privileges/{privilege} # Detach

Privilege Management:

GET    /api/privileges        # List privileges
POST   /api/privileges        # Create privilege
GET    /api/privileges/{privilege} # Get details
PUT    /api/privileges/{privilege} # Update
DELETE /api/privileges/{privilege} # Delete

Audit Logs:

GET    /api/audit-logs        # List audit logs

API Usage Examples

# Login
curl -X POST http://localhost/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"tyro"}'

# Register
curl -X POST http://localhost/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"[email protected]","password":"password123","password_confirmation":"password123"}'

# Get roles (authenticated)
curl http://localhost/api/roles \
  -H "Authorization: Bearer YOUR_TOKEN"

# Assign role to user
curl -X POST http://localhost/api/users/5/roles \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role_id":4}'

HasTyroRoles Trait API

Role Methods

$user->roles(): BelongsToMany
// Eloquent relationship to roles

$user->assignRole(Role $role): void
// Attach a role to user

$user->removeRole(Role $role): void
// Detach a role from user

$user->hasRole(string $role): bool
// Check if user has role (supports wildcard '*')

$user->hasRoles(array $roles): bool
// Check if user has ALL roles

$user->tyroRoleSlugs(): array
// Get all role slugs as array (cached)
// Returns: ['admin', 'editor']

Privilege Methods

$user->privileges(): Collection
// Get all unique privileges from user's roles

$user->hasPrivilege(string $privilege): bool
// Check if user has specific privilege

$user->hasPrivileges(array $privileges): bool
// Check if user has ALL privileges

$user->tyroPrivilegeSlugs(): array
// Get all privilege slugs as array (cached)
// Returns: ['articles.create', 'articles.publish']

Authorization

$user->can($ability, $arguments = []): bool
// Unified permission check:
// 1. Checks privileges first (exact match)
// 2. Then checks roles
// 3. Falls back to Laravel Gate

Suspension Methods

$user->suspend(?string $reason = null): void
// Suspend user, store reason, revoke all tokens

$user->unsuspend(): void
// Remove suspension

$user->isSuspended(): bool
// Check if user is suspended

$user->getSuspensionReason(): ?string
// Get suspension reason

Configuration

Publishing Config

php artisan tyro:publish-config --force

Key Config Options

Edit config/tyro.php:

return [
    // Models
    'models' => [
        'user' => App\Models\User::class,
        'privilege' => HasinHayder\Tyro\Models\Privilege::class,
    ],

    // Table names
    'tables' => [
        'users' => 'users',
        'roles' => 'roles',
        'pivot' => 'user_roles',
        'privileges' => 'privileges',
        'role_privilege' => 'privilege_role',
    ],

    // Route configuration
    'route_prefix' => 'api',
    'guard' => 'sanctum',
    'disable_api' => env('TYRO_DISABLE_API', false),

    // Default role for new users
    'default_user_role_slug' => 'user',

    // Protected roles (cannot be deleted)
    'protected_role_slugs' => ['super-admin', 'administrator', 'all'],

    // Single session login
    'delete_previous_access_tokens_on_login' => false,

    // Cache configuration
    'cache' => [
        'enabled' => true,
        'store' => null, // null = default cache store
        'ttl' => 300,    // seconds, null = indefinite
    ],

    // Audit trail
    'audit' => [
        'enabled' => true,
        'retention_days' => 30,
    ],
];

Environment Variables

# Disable CLI commands
TYRO_DISABLE_COMMANDS=true

# Disable REST API
TYRO_DISABLE_API=true

# Password validation
TYRO_PASSWORD_MIN_LENGTH=8
TYRO_PASSWORD_MAX_LENGTH=64
TYRO_PASSWORD_REQUIRE_NUMBERS=true
TYRO_PASSWORD_REQUIRE_UPPERCASE=true
TYRO_PASSWORD_REQUIRE_LOWERCASE=true
TYRO_PASSWORD_REQUIRE_SPECIAL_CHARS=true
TYRO_PASSWORD_REQUIRE_CONFIRMATION=true
TYRO_PASSWORD_CHECK_COMMON=true
TYRO_PASSWORD_DISALLOW_USER_INFO=true

Database Schema

Tables

roles:

• id - Primary key
• name - Display name
• slug - Unique identifier
• created_at, updated_at

privileges:

• id - Primary key
• name - Display name
• slug - Unique identifier
• description - Optional description
• created_at, updated_at

user_roles (pivot):

• id - Primary key
• user_id - Foreign key to users
• role_id - Foreign key to roles
• unique(user_id, role_id)
• created_at, updated_at

privilege_role (pivot):

• id - Primary key
• privilege_id - Foreign key to privileges
• role_id - Foreign key to roles
• unique(privilege_id, role_id)
• created_at, updated_at

tyro_audit_logs:

• id - Primary key
• user_id - Actor (nullable)
• event - Event name
• auditable_type - Target model type
• auditable_id - Target model ID
• old_values - JSON (before state)
• new_values - JSON (after state)
• metadata - JSON (context)
• created_at

users (extended):

• suspended_at - Timestamp or null
• suspension_reason - VARCHAR or null

Caching System

Tyro uses a two-tier caching system:

1. Persistent Cache

• Uses Laravel's cache store (Redis, Memcached, File)
• Key patterns:
  • tyro:user:{user_id}:roles
  • tyro:user:{user_id}:privileges
• Configurable TTL (default: 5 minutes)

2. Runtime Cache

• In-memory cache per request
• Version-based invalidation
• Prevents repeated database queries

Cache Invalidation

Automatic on:

• Role assigned/removed from user
• Privilege attached/detached from role
• Role deleted

Manual:

$user->clearTyroCache(); // Clear for specific user

Audit Trail

Tracked Events

Viewing Audit Logs

# CLI
php artisan tyro:audit-list --limit=100 --event=role.assigned

# API
GET /api/audit-logs?limit=100&event=role.assigned

Common Workflows

Setting Up a Blog with Roles

# Create blog-specific roles
php artisan tyro:role-create --name="Author" --slug="author"
php artisan tyro:role-create --name="Reviewer" --slug="reviewer"

# Create privileges
php artisan tyro:privilege-create --name="Create Articles" --slug="articles.create"
php artisan tyro:privilege-create --name="Edit Own Articles" --slug="articles.edit.own"
php artisan tyro:privilege-create --name="Edit Any Article" --slug="articles.edit.any"
php artisan tyro:privilege-create --name="Publish Articles" --slug="articles.publish"
php artisan tyro:privilege-create --name="Delete Articles" --slug="articles.delete"

# Attach to author
php artisan tyro:privilege-attach --role="author" --privilege="articles.create"
php artisan tyro:privilege-attach --role="author" --privilege="articles.edit.own"

# Attach to reviewer
php artisan tyro:privilege-attach --role="reviewer" --privilege="articles.edit.any"
php artisan tyro:privilege-attach --role="reviewer" --privilege="articles.publish"

Protecting Blog Routes

// Authors can create
Route::post('articles', [ArticleController::class, 'store'])
    ->middleware(['auth:sanctum', 'privilege:articles.create']);

// Reviewers can publish
Route::post('articles/{article}/publish', [ArticleController::class, 'publish'])
    ->middleware(['auth:sanctum', 'privilege:articles.publish']);

Troubleshooting

Commands Not Found

# Check if commands are disabled
grep TYRO_DISABLE_COMMANDS .env

# Re-enable by removing or setting to false
TYRO_DISABLE_COMMANDS=false

API Routes Not Working

# Check if API is disabled
grep TYRO_DISABLE_API .env

# Re-enable
TYRO_DISABLE_API=false

# Check route list
php artisan route:list --path=tyro

Cache Issues

# Clear application cache
php artisan cache:clear

# Clear specific Tyro cache
php artisan tyro:cache-clear

User Can't Login

# Check if suspended
php artisan tyro:user-suspended

# Unsuspend if needed
php artisan tyro:user-unsuspend [email protected]

Migration Issues

# Re-run migrations
php artisan migrate:fresh --seed

# Or just Tyro migrations
php artisan migrate --path=vendor/hasinhayder/tyro/database/migrations

Key Gotchas

1. Protected Roles - super-admin, administrator, all cannot be deleted
2. Last Admin - Cannot delete the last admin user
3. Suspension Revokes Tokens - Suspending a user immediately revokes all their tokens
4. Wildcard Role - Role slug * grants universal access
5. Cache Invalidation - Changes to roles/privileges automatically invalidate cache for affected users
6. Seeding is Optional - But highly recommended for first-time setup

For More Information

• GitHub: https://github.com/hasinhayder/tyro
• Tyro Labs: https://tyrolabs.dev/
• Related: tyro-login, tyro-dashboard