Download the PHP package hasinhayder/tyro without Composer

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

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

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)

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)

ℹ️ 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 [email protected] 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:

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

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

Checking Privileges in Code

Managing Roles Programmatically

Managing Privileges Programmatically

User Suspension

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:

Running the seeder will:

• Insert the Administrator, User, Customer, Editor, All, and Super Admin roles along with their mapped privileges.
• Create the [email protected] 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:

Tyro caches role and privilege slugs per user so authorization checks never hit the database on every request. The cache respects your config/tyro.php settings and is automatically invalidated when you modify roles, privileges, or assignments.

Updating Tyro

When updating Tyro from an older version using composer update, you must run migrations to apply any new database changes (such as audit trail tables):

⚠️ Important: Always run migrations after updating Tyro. Skipping this step may result in missing database tables and unexpected behavior.

5. Optional configuration

Override defaults in config/tyro.php to align with your app:

Set load_default_routes to false if you prefer to include routes/api.php manually and merge Tyro endpoints into your own files.

Disable Tyro commands or API via .env

Tyro registers a sizable CLI toolbox. If you would rather keep production shells lean (or limit what teammates can run), drop the following snippet into .env on the environments you wish to lock down:

With the variable set to true, Tyro skips registering every tyro:* artisan command while continuing to expose routes, middleware, and config overrides as usual. Remove the line (or set it to false) locally to regain the commands for development.

Need to turn off the bundled API endpoints entirely? Set:

When TYRO_DISABLE_API is true, Tyro skips loading its routes/api.php file so you can provide a fully custom HTTP surface (or disable it in worker contexts).

Need an emergency token rotation? Run php artisan tyro:auth-logout-all-users --force to revoke every Sanctum token the package has issued.

Password Security

Tyro includes robust password validation that you can configure via your .env file. These settings apply to user registration, password updates, and the tyro:user-create command.

Example .env configuration for high security:

Blade Directives

Tyro provides custom Blade directives for checking user roles and privileges directly in your views. All directives automatically return false if no user is authenticated.

@userCan

Checks if the current user has a specific role or privilege (uses the can() method):

@hasRole

Checks if the current user has a specific role:

@hasAnyRole

Checks if the current user has any of the provided roles:

@hasAllRoles

Checks if the current user has all of the provided roles:

@hasPrivilege

Checks if the current user has a specific privilege:

@hasAnyPrivilege

Checks if the current user has any of the provided privileges:

@hasAllPrivileges

Checks if the current user has all of the provided privileges:

Combining Directives

You can nest and combine directives for complex authorization logic:

All directives leverage the methods from the HasTyroRoles trait and are automatically registered when the Tyro package is loaded. They provide a clean, readable way to conditionally display content based on user permissions without cluttering your Blade templates with PHP logic.

Middleware for Route Protection

Tyro ships with a complete set of middleware aliases for protecting your routes—whether you're building an API, web app, or both. These are registered automatically when you install the package.

Available Middleware

Protecting Routes (Examples)

Using Abilities in Policies

Audit Trail

Tyro includes a database-backed audit trail to track administrative actions. This is essential for security auditing and compliance.

Recorded Events

• User Actions: Role assignment, role removal, user suspension, and unsuspension.
• Role Actions: Role creation, updates, and deletion.
• Privilege Actions: Privilege creation, updates, and deletion.

CLI Management

Configuration

Customize retention and toggle the feature in config/tyro.php:

For more details, see the Detailed Audit Trail Documentation.

CLI Commands (40+ Tools)

Tyro ships with a powerful CLI toolbox for managing users, roles, privileges, and tokens—perfect for automation, CI/CD pipelines, and incident response.

User Management Commands

Role Management Commands

Privilege Management Commands

Authentication & Token Commands

Audit Management Commands

Setup & Maintenance Commands

All commands accept non-interactive --option flags, making them perfect for scripts and automation.

User Suspension

Tyro includes first-class user suspension support to freeze accounts without deleting them:

CLI workflow:

Suspended users cannot log in, and all their existing tokens are immediately revoked.

Optional: REST API Endpoints

If you need REST endpoints for managing users, roles, and privileges (useful for admin panels, mobile apps, etc.), Tyro includes a complete API surface. These are enabled by default but can be disabled if you don't need them.

Available Endpoints

Tyro registers the following endpoints (prefixed by tyro.route_prefix, default api):

• Public: GET /tyro, GET /tyro/version, POST /login, POST /users (registration)
• Authenticated: GET /me, PUT|PATCH|POST /users/{user}
• Admin-only: User CRUD, Role CRUD, Privilege CRUD, Audit Log CRUD, user-role assignments, role-privilege assignments, user suspension

Disabling the API

If you only need Tyro's code-level features (roles, privileges, CLI commands), disable the API:

API Usage Examples

Authentication

Role Management (Admin)

Privilege Management (Admin)

AI Agent Integration

Tyro ships a built-in AI skill that helps AI coding assistants understand your authorization system and write correct Tyro code. Install it for your preferred agent:

The command prompts you to choose from supported agents:

Choosing all installs to every agent directory. A universal copy is also placed at .agents/skills/tyro/ for any agent that follows the agents.md convention.

The skill includes 27 rule files covering architecture, authorization, permissions, roles, privileges, suspensions, inheritance, caching, security, middleware, Blade directives, testing, and more — all grounded in Tyro's actual codebase patterns.

FAQ

How do I get the authenticated user's roles inside a controller?

How do I get the authenticated user's privileges?

How do I assign or remove roles to a user from code?

How do I assign or remove privileges to a role?

How do I get the list of privileges in a role?

How do I check if a role has specific privileges?

The Role model includes hasPrivilege() and hasPrivileges() methods for checking privileges:

How do I check if the authenticated user has particular roles?

How do I check if the authenticated user has specific privileges?

How do I check if a user is suspended and inspect the reason?

Database assets

• database/migrations/* creates the roles, user_roles, privileges, and privilege_role tables (configurable via config/tyro.php).
• database/seeders/TyroSeeder seeds the core roles, default privileges, and creates the admin bootstrap user.
• database/factories/UserFactory targets whichever user model you configure, and PrivilegeFactory speeds up testing custom privileges.

Development

• src/Providers/TyroServiceProvider.php handles route loading, publishing, and middleware aliases.
• Controllers live under src/Http/Controllers/* and operate against the configurable user model.
• routes/api.php declares all endpoints and ability middleware in one place.

Contributions are welcome! Please open an issue or pull request with improvements, bug fixes, or new ideas.

License

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