Static Roles Bundle Laravel Package

Product Decisions This Supports

• Role-Based Access Control (RBAC) Simplification: Enables a declarative, configuration-driven approach to defining roles and hierarchies, reducing hardcoded logic in application code. Ideal for projects where roles are static (e.g., admin, editor, user) and managed via version control (not dynamic DB entries).
• Decoupling Security Logic from Business Logic: Aligns with clean architecture principles by externalizing role definitions to security.yml, making them easier to audit, modify, and test.
• Form Integration for User Management: Provides a reusable form type for role assignment, accelerating development of admin panels or user self-service portals (e.g., "Upgrade to Premium" workflows).
• Validation and Hierarchy Enforcement: Automatically validates role configurations (e.g., circular dependencies) and enforces hierarchies (e.g., ROLE_ADMIN inherits ROLE_USER), reducing runtime errors.
• Roadmap for Scalable Permissions: Foundation for future expansion (e.g., integrating with Symfony’s voter system or adding dynamic role tags for granular access control).
• Build vs. Buy: Justifies buying this lightweight package over building a custom solution for static role systems, saving ~10–20 dev hours for setup, validation, and form integration.

When to Consider This Package

• Adopt if:

  • Roles are static (predefined, not user-generated) and managed via VCS (e.g., Git).
  • You need role hierarchies (e.g., ROLE_SUPER_ADMIN > ROLE_ADMIN > ROLE_USER) with validation.
  • Your team prioritizes configuration over code for security definitions.
  • You’re using Symfony and want to avoid reinventing role management wheels.
  • Roles require human-readable labels/descriptions (e.g., for admin UIs or documentation).

• Look elsewhere if:

  • Roles are dynamic (created at runtime, e.g., per-tenant or per-project roles).
  • You need fine-grained permissions (e.g., "Can edit posts but not delete") beyond simple role inheritance.
  • Your stack isn’t Symfony/Laravel (or you’re using a different security system like Casbin).
  • You require database-backed roles with frequent updates (consider Symfony’s RoleHierarchyVoter or Doctrine extensions).
  • The bundle’s maturity (last release 2023-01-12) is a concern for long-term projects (evaluate maintenance risk).

How to Pitch It (Stakeholders)

For Executives: "This package lets us define user roles (e.g., Admin, User) in a simple config file—like a spreadsheet for permissions—rather than hardcoding them in the app. It’s a 10-minute setup that saves dev time, reduces bugs from manual role management, and makes it easier to update permissions later. Think of it as ‘Git for your user access rules.’ Ideal for projects where roles don’t change often, like admin panels or membership sites."

For Engineers: *"BecklynStaticRolesBundle gives us:

• Declarative role hierarchies in security.yml (no more if ($user->hasRole('ROLE_ADMIN')) spaghetti).
• Automatic validation of role structures (e.g., catches circular dependencies).
• A ready-made form type for role assignment in user profiles/admin panels (no custom Twig/JS work).
• Lightweight (~500 LOC) and Symfony-native—just drop it in and configure.

Tradeoff: Not for dynamic roles or complex permissions, but perfect for static RBAC. Example use case: A SaaS admin dashboard where we need ‘Super Admin’ > ‘Team Lead’ > ‘User’ with clear labels for the UI."*

For Developers: *"If you’re tired of:

• Debugging role inheritance bugs.
• Writing custom form types for role selection.
• Managing role strings (ROLE_ADMIN) vs. human-readable names (‘Admin’).

This bundle handles it all. Just:

1. composer require becklyn/static-roles-bundle
2. Define roles in security.yml (with titles, descriptions, and hierarchy).
3. Use the static_role form field in your user entity forms.

Pro tip: Pair it with Symfony’s Voter system for action-level permissions (e.g., canEditPost)."*