Horus Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hans-thomas/horus
   php artisan vendor:publish --tag horus-config
   

   Verify config/horus.php exists and is configured (default settings are fine for most cases).

2. First Use Case: Generate a role-permission structure for a model (e.g., Post) using its policy:

   php artisan horus:generate Post
   

   This creates:

   • A post role (e.g., editor, admin).
   • Permissions derived from PostPolicy (e.g., edit-post, delete-post).

3. Key Files to Review:

   • config/horus.php: Global settings (e.g., default role/permission naming).
   • app/Policies/PostPolicy.php: Example policy for permission generation.
   • database/seeds/RolesAndPermissionsSeeder.php: Seed file for initial data (if using).

Implementation Patterns

1. Batch Role/Permission Creation

Use the Horus facade to register roles and permissions programmatically:

use HansThomas\Horus\Facades\Horus;

// Register a role with permissions
Horus::role('admin')
     ->permission('create-post')
     ->permission('edit-post')
     ->save();

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

Workflow:

• Define roles in a seeder (e.g., RolesAndPermissionsSeeder).
• Use Horus::role()->permission()->save() for bulk operations.
• Trigger via php artisan db:seed.

2. Policy-Driven Permission Generation

Horus auto-generates permissions from model policies. Example:

// app/Policies/PostPolicy.php
public function edit(User $user, Post $post) { ... }
public function delete(User $user, Post $post) { ... }

Run:

php artisan horus:generate Post

This creates permissions like:

• edit-post (from edit() method).
• delete-post (from delete() method).

Tip: Use @method annotations in policies for clarity:

/**
 * @method bool view(User $user, Post $post)
 */

3. Integration with Spatie Permissions

Horus extends spatie/laravel-permission. Leverage existing Spatie methods:

// Check if a user has a permission
if ($user->can('edit-post')) { ... }

// Sync permissions for a role
$role->syncPermissions(['edit-post', 'delete-post']);

Pattern: Use Horus for initial setup and Spatie for runtime checks.

4. Customizing Permission Names

Override default naming conventions in config/horus.php:

'permissions' => [
    'name' => 'custom-{method}-{model}', // e.g., "custom-edit-post"
],

Or use closures for dynamic naming:

'permissions' => [
    'name' => fn($method, $model) => strtolower("{$model}.{$method}"),
],

5. Seeding Data

Create a seeder to populate roles/permissions:

// database/seeds/RolesAndPermissionsSeeder.php
public function run()
{
    Horus::role('editor')
         ->permission('create-post')
         ->permission('publish-post')
         ->save();

    Horus::role('admin')
         ->permission('manage-users')
         ->permission('edit-post')
         ->save();
}

Run:

php artisan db:seed --class=RolesAndPermissionsSeeder

Gotchas and Tips

Pitfalls

1. Policy Method Naming:

   • Horus only picks up public methods in policies. Private methods are ignored.
   • Fix: Ensure policy methods are public and follow Laravel’s authorization conventions (e.g., edit(), not canEdit()).

2. Permission Name Collisions:

   • If two models have policies with the same method (e.g., edit() in PostPolicy and UserPolicy), permissions may clash.
   • Fix: Use custom naming conventions (see above) or prefix permissions with the model name.

3. Seeder Order:

   • If you seed roles after assigning them to users, the assignments will fail.
   • Fix: Seed roles/permissions first, then assign to users.

4. Caching Issues:

   • Spatie’s permission cache may cause stale data after generating new permissions.
   • Fix: Clear the cache after generating permissions:

     php artisan cache:clear
     php artisan horus:generate Post
     

Debugging Tips

1. Verify Generated Permissions: Check the permissions table after running horus:generate:

   SELECT * FROM permissions WHERE name LIKE '%post%';
   

2. Log Permission Generation: Enable Horus logging in config/horus.php:

   'logging' => true,
   

   Check storage/logs/laravel.log for generation details.

3. Check Policy Coverage: Run:

   php artisan horus:check Post
   

   This lists all methods in PostPolicy and whether they were converted to permissions.

Extension Points

1. Custom Permission Logic: Extend the HorusServiceProvider to add logic before/after permission generation:

   // app/Providers/HorusServiceProvider.php
   public function boot()
   {
       Horus::extend(function ($role) {
           // Add custom permissions dynamically
           $role->permission('custom-permission');
           return $role;
       });
   }
   

2. GUI Integration: Pair with Sphinx (mentioned in the README) for a visual role/permission manager:

   composer require hans-thomas/sphinx
   php artisan sphinx:install
   

3. API Rate Limiting: Use Horus to create a bypass-rate-limit permission for API endpoints:

   Horus::role('api-admin')
        ->permission('bypass-rate-limit')
        ->save();
   

   Then gate your middleware:

   if (!$user->can('bypass-rate-limit')) {
       // Apply rate limiting
   }
   

Performance Quirks

• Batch Inserts: Horus uses batch inserts for roles/permissions. For large datasets, ensure your database supports batch operations (e.g., PostgreSQL with ON CONFLICT).
• Policy Scanning: Generating permissions for many models can be slow. Limit usage to critical models (e.g., Post, User, Product).