Tyro

Tyro is a very powerful Authentication, Authorization, and Role & Privilege Management solution for Laravel 12 and 13. Think of it as a Swiss Army knife that handles everything from user authentication and role-based access control to user suspension workflows—whether you're building an API, a traditional web application, or both. With Sanctum integration, 40+ powerful CLI commands, 7 Blade directives, and ready-made middleware, Tyro saves you weeks of development time.

Related Resources

• Tyro Labs – Complete Auth & Admin Platform for Laravel.
• tyro-login – A sleek, production-ready login UI component powered by Tyro's authentication system with OTP, TOTP, Multiple Layouts, Magic Login, Authenticator, Social Login, Password Reset, Nice Email Templates.
• tyro-dashboard – A comprehensive admin dashboard (admin/user) for instant crud, managing roles, privileges, users, and permissions with ease.

Why Tyro?

Tyro is the complete auth and access control toolkit that works everywhere in your Laravel application:

• Complete Authentication & Authorization. Out-of-the-box user authentication with Sanctum, role-based access control, fine-grained privilege management, and Laravel Gate integration. Works seamlessly for APIs, web apps, and hybrid applications.
• Powerful Role & Privilege System. Create unlimited roles with granular privileges. Check permissions in controllers, middleware, Blade templates, or anywhere in your code with intuitive helpers like $user->hasRole(), $user->hasRoles(), $user->hasAnyRole(), $user->can(), and $user->hasPrivileges().
• 40+ Artisan Commands. Manage users, roles, privileges, and tokens entirely from the CLI. Seed data, suspend users, rotate tokens, audit permissions—all without touching the database directly. Perfect for automation, CI/CD, and incident response.
• Blade Directives for Views. Use @userCan, @hasRole, @hasPrivilege, @hasAnyRole, @hasAllRoles, @hasAnyPrivilege, and @hasAllPrivileges to conditionally render content based on user permissions. Clean, readable templates without PHP logic clutter.
• User Suspension Workflows. Freeze accounts instantly with optional reasons, automatically revoke all active tokens, and manage suspensions via CLI or REST endpoints.
• Comprehensive Audit Trail. Track every administrative action—who assigned which role, who suspended a user, and what changed in a role's privileges. View logs via CLI or a dedicated API endpoint.
• Optional API Surface. Need REST endpoints? Tyro ships production-ready routes for login, registration, user management, role CRUD, and privilege management. Don't need them? Disable with one config flag.
• Security Hardened. Sanctum tokens automatically include role and privilege abilities, suspension workflows revoke tokens instantly, and protected role slugs prevent accidental deletion.
• Zero Lock-in. Publish config, migrations, and factories to customize everything. Disable CLI commands or API routes per environment. Tyro adapts to your architecture, not the other way around.

Requirements

• PHP ^8.2
• Laravel 12.0 or Laravel 13
• Laravel Sanctum ^4.0

Quick start (TL;DR)

1. composer require hasinhayder/tyro
2. php artisan tyro:sys-install (sets up Sanctum, runs migrations, seeds roles/privileges, and prepares your User model)

That's it! You now have a complete authentication and authorization system. The rest of this document shows how to use Tyro's features in your application.

Step-by-step installation

1. Install the package

composer require hasinhayder/tyro

Tyro's service provider is auto-discovered. Publish its assets if you want to customize them:

php artisan vendor:publish --tag=tyro-config
php artisan vendor:publish --tag=tyro-migrations
php artisan vendor:publish --tag=tyro-database
php artisan tyro:publish-config --force
php artisan tyro:publish-migrations --force

Need the ready-made API client collection? Run php artisan tyro:sys-postman --no-open to print the GitHub URL for the official Postman collection, or omit --no-open to open it directly.

2. Run tyro:sys-install (recommended)

php artisan tyro:sys-install

tyro:sys-install is the one command you need to bootstrap Tyro on a fresh project. Under the hood it:

1. Calls Laravel's install:api so Sanctum's config, migration, and middleware stack are registered.
2. Runs php artisan migrate (respecting --force when you provide it) to apply both Laravel's and Tyro's database tables.
3. Prompts to execute tyro:seed-all --force, inserting the default role/privilege catalog plus the bootstrap admin account.
4. Offers to run tyro:user-prepare immediately if you skip seeding so the correct traits and imports land on your user model.

Skipping tyro:sys-install means you must run each of those commands manually (install:api, migrate, tyro:seed-all, tyro:user-prepare). Most teams never need to—tyro:sys-install keeps the happy path automated and idempotent.

3. Run Tyro's migrations & seeders manually (optional)

php artisan migrate
# or, interactively
php artisan tyro:seed-all

ℹ️ Seeding is technically optional, but highly recommended the first time you install Tyro. TyroSeeder inserts the default role catalogue (Administrator, User, Customer, Editor, All, Super Admin) and creates a ready-to-use admin@tyro.project superuser (password tyro). Skipping the seeder means you'll need to create equivalent roles and an admin account manually before any ability-gated routes will authorize.

4. Prepare your user model

Tyro augments whatever model you mark as tyro.models.user (defaults to App\Models\User). Run the following command to add the required traits:

php artisan tyro:user-prepare

The command above injects the required imports and trait usage automatically. Prefer editing manually? Here is what the class should look like:

<?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;
}

That is the only code change you need. The HasTyroRoles trait gives your User model powerful methods for checking roles, privileges, and managing suspensions. Tyro will automatically attach the default role (slug user) to future registrations.

Using Tyro in Your Application

Tyro works everywhere in your Laravel application—controllers, middleware, Blade templates, jobs, policies, and more. Here's how to leverage its features:

Checking Roles in Code

// In a controller, service, or anywhere you have the user
$user = auth()->user();

// Check single role
if ($user->hasRole('admin')) {
    // User is an admin
}

// Check multiple roles (user must have ALL)
if ($user->hasRoles(['admin', 'super-admin'])) {
    // User has both roles
}

// Get all role slugs
$roles = $user->tyroRoleSlugs(); // ['admin', 'editor']

Checking Privileges in Code

$user = auth()->user();

// Check single privilege (uses Laravel's can() method)
if ($user->can('reports.run')) {
    // User has the reports.run privilege
}

// Check multiple privileges (user must have ALL)
if ($user->hasPrivileges(['reports.run', 'billing.view'])) {
    // User has both privileges
}

// Get all privilege slugs
$privileges = $user->tyroPrivilegeSlugs(); // ['reports.run', 'billing.view']

Managing Roles Programmatically

use HasinHayder\Tyro\Models\Role;

$user = User::find(1);

// Assign a role
$editorRole = Role::where('slug', 'editor')->first();
$user->assignRole($editorRole);

// Remove a role
$user->removeRole($editorRole);

// Get all roles as Eloquent models
$roles = $user->roles;

Managing Privileges Programmatically

use HasinHayder\Tyro\Models\Role;
use HasinHayder\Tyro\Models\Privilege;

$role = Role::where('slug', 'editor')->first();

// Attach privileges to a role
$privilege = Privilege::where('slug', 'reports.run')->first();
$role->privileges()->attach($privilege->id);

// Detach privileges
$role->privileges()->detach($privilege->id);

// Check if role has a privilege
if ($role->hasPrivilege('reports.run')) {
    // Role has this privilege
}

User Suspension

$user = User::find(1);

// Suspend user (revokes all tokens automatically)
$user->suspend('Pending account review');

// Check if suspended
if ($user->isSuspended()) {
    $reason = $user->getSuspensionReason();
}

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

Seeding (optional but recommended)

Tyro's TyroSeeder keeps every environment aligned by inserting the default roles, privileges, and bootstrap admin account. Trigger it manually or rerun it with --force any time you need to refresh local data:

php artisan tyro:seed-all --force

Running the seeder will:

• Insert the Administrator, User, Customer, Editor, All, and Super Admin roles along with their mapped privileges.
• Create the admin@tyro.project superuser (password tyro) so you always have a ready account.
• Reapply protected role/privilege relationships.

Need something narrower? Use tyro:seed-roles or tyro:seed-privileges to refresh a single catalog without touching users.

HasTyroRoles Trait Reference

The HasTyroRoles trait gives your User model a complete API for roles, privileges, and suspensions. These methods are the same ones used by Tyro's routes and CLI commands, so your code stays consistent:

| Method | Category | Description | | ---------------------------------------- | ---------- | ------------