| 1: | <?php |
| 2: | |
| 3: | namespace LaravelUi5\Core\Attributes; |
| 4: | |
| 5: | use Attribute; |
| 6: | |
| 7: | /** |
| 8: | * Declares a semantic role within the LaravelUi5 domain model. |
| 9: | * |
| 10: | * A Role groups Abilities into a *conceptual responsibility*, |
| 11: | * such as "Accountant" or "Project Manager". Roles are global |
| 12: | * and context-independent — they describe *what* a user represents, |
| 13: | * not *where* the role applies. |
| 14: | * |
| 15: | * Contextual assignments (e.g. "Anna is Project Manager in Project A") |
| 16: | * are handled at the group or policy layer, not by the role itself. |
| 17: | * |
| 18: | * Example: |
| 19: | * ```php |
| 20: | * #[Role('Accountant', 'Responsible for financial postings and reporting.')] |
| 21: | * class AccountingModule {} |
| 22: | * ``` |
| 23: | * |
| 24: | * Roles are typically referenced by `Ability` or `Group` assignments |
| 25: | * but do not directly enforce access restrictions. They serve as |
| 26: | * descriptive metadata to organize responsibilities across modules. |
| 27: | * |
| 28: | * @see \LaravelUi5\Core\Attributes\Ability |
| 29: | */ |
| 30: | #[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)] |
| 31: | class Role |
| 32: | { |
| 33: | /** |
| 34: | * Create a new role definition. |
| 35: | * |
| 36: | * @param string $role Technical identifier (e.g. "Accountant"), unique per installation. |
| 37: | * @param string $note Human-readable description of the role’s purpose or scope. |
| 38: | * @param string|null $scope Optional fully-qualified class name that defines |
| 39: | * the *semantic domain scope* of this role, |
| 40: | * e.g. `Pragmatiqu\Projects\Models\Project` |
| 41: | * for the role "Project Manager". |
| 42: | */ |
| 43: | public function __construct( |
| 44: | public string $role, |
| 45: | public string $note, |
| 46: | public ?string $scope = null, |
| 47: | ) {} |
| 48: | } |
| 49: |