| 1: | <?php |
| 2: | |
| 3: | namespace LaravelUi5\Core\Attributes; |
| 4: | |
| 5: | use Attribute; |
| 6: | use LaravelUi5\Core\Enums\AbilityType; |
| 7: | |
| 8: | /** |
| 9: | * Declares an ability (permission concept) that a Ui5 artifact or module |
| 10: | * exposes. This is purely metadata discovered by reflection; Core does not |
| 11: | * enforce any authorization. |
| 12: | * |
| 13: | * Each ability is defined by a unique name and a {@see AbilityType}. The |
| 14: | * resulting i18n keys for UI labels are composed automatically as: |
| 15: | * |
| 16: | * • "<type>.<name>.title" |
| 17: | * • "<type>.<name>.description" |
| 18: | * |
| 19: | * Example: |
| 20: | * ```php |
| 21: | * use LaravelUi5\Core\Attributes\Ability; |
| 22: | * use LaravelUi5\Core\Enums\AbilityType; |
| 23: | * |
| 24: | * #[Ability( |
| 25: | * name: 'exportContacts', |
| 26: | * role: 'Supervisor', |
| 27: | * type: AbilityType::Act, |
| 28: | * note: 'Allows exporting contact data to CSV or Excel.' |
| 29: | * )] |
| 30: | * class ExportContactsAction extends Ui5Action |
| 31: | * { |
| 32: | * // ... |
| 33: | * } |
| 34: | * ``` |
| 35: | * |
| 36: | * ### Reflection & SDK usage |
| 37: | * During cache build the SDK records: |
| 38: | * - ability name |
| 39: | * - ability role |
| 40: | * - ability type (enum label or int) |
| 41: | * - optional developer note |
| 42: | * |
| 43: | * The SDK or higher layers may later map these abilities to Laravel |
| 44: | * authorization gates or policy methods and resolve the derived i18n keys |
| 45: | * for display. |
| 46: | */ |
| 47: | #[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)] |
| 48: | class Ability |
| 49: | { |
| 50: | /** |
| 51: | * @param string $ability Technical identifier, e.g. "exportContacts". |
| 52: | * @param string $role $role semantic bag for the ability |
| 53: | * @param AbilityType $type Ability classification (Use, Act, See). |
| 54: | * @param string $note Description of the ability's purpose or scope. |
| 55: | */ |
| 56: | public function __construct( |
| 57: | public string $ability, |
| 58: | public string $role, |
| 59: | public AbilityType $type = AbilityType::Act, |
| 60: | public string $note, |
| 61: | ) {} |
| 62: | } |
| 63: |