Bouncer Laravel Package

Technical Evaluation

Architecture Fit

• Role-Based Access Control (RBAC) + Attribute-Based Access Control (ABAC) Hybrid: Bouncer provides a robust, Eloquent-based implementation for defining roles, abilities, and permissions, aligning well with Laravel’s ecosystem. It integrates seamlessly with Laravel’s built-in Gate and Policy systems, offering a flexible approach to authorization.
• Multi-Tenancy Support: The package excels in multi-tenant environments, allowing scoped permissions per tenant without global leakage. This is critical for SaaS platforms or applications with isolated data silos.
• Extensibility: Supports custom models, table names, and even non-standard auth configurations (e.g., non-default guard names). The ability to override default behavior (e.g., Bouncer::runBeforePolicies()) adds granularity.

Integration Feasibility

• Laravel 11+ Focus: The package is now optimized for Laravel 11/12/13, with a clear migration path for older versions (v1.0.1 for Laravel <11). If your stack is on Laravel 10 or below, integration is still viable but may require additional testing.
• Database Agnostic: Works with MySQL, PostgreSQL, Oracle, and SQLite, with explicit fixes for edge cases (e.g., JSON columns in MySQL). Schema migrations are well-documented, though some manual adjustments may be needed for custom setups.
• IDE/Tooling Support: PHPDoc annotations and return types improve developer experience, especially for tools like Lighthouse (GraphQL) or static analyzers.

Technical Risk

• Breaking Changes in v1.0.0:
  • Removal of Levels (niche feature) and default policy execution order (now runs after policies by default). These are low-risk if your codebase doesn’t rely on undocumented features or assumes Bouncer runs before policies.
  • Morph Map Migration: If using custom models/table names, existing data may require migration to align with Laravel’s morph map (see RC5 breaking changes). This is a one-time effort but could be complex for large datasets.
• Performance: Early versions had caching issues (fixed in RC4), but the package now emphasizes leaner caching strategies. Benchmarking is recommended for high-traffic applications.
• Dependency Bloat: No direct dependents, but the package pulls in Laravel’s core auth system. Ensure your composer.json constraints align with Bouncer’s supported versions.

Key Questions

1. Laravel Version Compatibility:
   • Are you on Laravel 11+? If not, will you upgrade, or will you pin to v1.0.1?
   • Does your application use non-standard auth guards (e.g., api, sanctum)? Bouncer supports this, but test thoroughly.
2. Multi-Tenancy Requirements:
   • Do you need tenant-scoped permissions? If so, test the scope() and allowEveryone() features.
   • Are you using polymorphic relationships? Ensure your custom models are registered with the morph map.
3. Policy vs. Bouncer Precedence:
   • Does your app rely on Bouncer running before policies (e.g., for fallback permissions)? If so, explicitly call Bouncer::runBeforePolicies().
4. Legacy Data:
   • If upgrading from v1.0.1 or earlier, check for schema changes (e.g., nullable entity_id/entity_type for allowEveryone()).
5. Performance:
   • For high-scale apps, profile can()/cannot() calls under load. Consider caching strategies (e.g., Bouncer::refresh() for cross-request caching).

Integration Approach

Stack Fit

• Laravel-Centric: Bouncer is a first-class citizen in Laravel’s auth ecosystem. It plays well with:
  • Policies/Gates: Extends Laravel’s native Gate facade with role/ability checks.
  • Middleware: Integrate with auth or custom middleware for route-level permissions.
  • GraphQL (Lighthouse): Return types are explicitly supported for nested mutations.
  • Testing: Works with Laravel’s testing helpers (e.g., actingAs() + can() assertions).
• Non-Laravel PHP: The package can run outside Laravel (e.g., in Lumen or standalone PHP), but some features (e.g., service container integration) may require manual setup.

Migration Path

1. Assess Current Auth System:
   • Audit existing policies/gates. Identify permissions that can be migrated to roles/abilities.
   • Example: Replace Gate::define('delete_post', ...) with Bouncer::allow($user)->to('delete', Post::class).
2. Schema Migration:
   • Run Bouncer’s migrations (php artisan vendor:publish --provider="Bouncer\BouncerServiceProvider").
   • For custom models/table names, update the morph map and data as needed (see RC5).
3. Feature Adoption:
   • Start with core features (roles, abilities) before exploring advanced use cases (e.g., allowEveryone(), multi-tenancy).
   • Use the Bouncer facade or HasAbilities trait for models.
4. Testing:
   • Write integration tests for critical paths (e.g., role assignment, permission checks).
   • Test edge cases: soft deletes, polymorphic relationships, and custom guards.

Compatibility

• Laravel Versions:
  • Laravel 11/12/13: Full support (v1.0.2+). Use latest stable release.
  • Laravel 10: Supported via v1.0.1 (pin josephsilber/bouncer:1.0.1).
  • Laravel <10: Use v1.0.1, but expect no new features or bug fixes.
• PHP Versions:
  • v1.0.2+ requires PHP 8.1+. Older versions may need v1.0.1.
• Database:
  • All major DBs are supported, but test JSON/PostgreSQL/Oracle-specific features.

Sequencing

1. Phase 1: Core Integration
   • Replace simple gates with Bouncer’s can()/cannot() methods.
   • Migrate roles/abilities to the database.
2. Phase 2: Advanced Features
   • Implement multi-tenancy scopes if needed.
   • Use allowEveryone() for global permissions.
3. Phase 3: Optimization
   • Profile and adjust caching (e.g., Bouncer::refresh()).
   • Fine-tune policy precedence with runBeforePolicies()/runAfterPolicies().

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor Bouncer’s releases for Laravel/PHP version support. The package now follows a "one version behind" policy (e.g., supports Laravel 13 while testing 14).
  • Use composer require josephsilber/bouncer:^1.0 for auto-updates.
• Schema Changes:
  • Future versions may introduce migrations. Keep a backup of your permissions table.
  • For custom setups, document morph map registrations and data migrations.
• Deprecations:
  • Watch for undocumented features (e.g., Levels were removed in v1.0.0). Avoid relying on non-public APIs.

Support

• Troubleshooting:
  • Use Bouncer::debug() to inspect role/ability assignments.
  • Leverage the bouncer:clean Artisan command to reset test data.
  • Check the GitHub issues for common pitfalls (e.g., multi-tenancy scope leaks).
• Community:
  • Active maintainer (Joseph Silber) with responsive issue resolution.
  • 3.5K+ stars indicate strong adoption; Stack Overflow/Laracasts have many Q&A threads.

Scaling

• Performance:
  • Caching: Bouncer caches role/ability checks by default. For high-traffic apps, consider:
    • Disabling caching (Bouncer::disableCache()) if permissions change frequently.
    • Using Bouncer::refresh() to clear cross-request cache.
  • Database Load:
    • Avoid canAny() in loops; it queries all abilities for a user.
    • Preload permissions with Bouncer::getAbilities($user).
  • Multi-Tenancy:
    • Scoped queries add overhead. Test with your tenant isolation strategy.
• Horizontal Scaling:
  • Stateless checks (e.g., Bouncer::can($user, 'edit', Post::class)) scale well.
  • Stateful operations (e.g., role assignments) may need transaction management in distributed systems.

Failure Modes