WIP Added new AbilityType::Access

mgerzabek · mgerzabek · commit 940b93342e4e · 2025-11-08T10:17:49.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.1.1] - 2025-11-08
+- Added new `AbilityType::Access`. Introduces backend-only ability type for controlling access to entry-level artifacts (Apps, Dashboards, Reports, Tiles, KPIs, Resources, Dialogs).
+- Enhanced `Ui5Registry` accessors for abilities and settings
+
 ## [1.1.0] - 2025-11-07
 - Added tests for Ui5Registry
 - Switched to PHP 8.3 language level
diff --git a/src/Enums/AbilityType.php b/src/Enums/AbilityType.php
@@ -4,33 +4,115 @@
 
 use InvalidArgumentException;
 
+/**
+ * Defines the four fundamental categories of Abilities within LaravelUi5.
+ * Each type expresses a distinct semantic permission scope that governs
+ * what a user may see, do, or enter across frontend and backend layers.
+ *
+ * Integer-backed for compact storage and stable comparison.
+ *
+ * ---------------------------------------------------------------------
+ * Use    → Access to frontend views, dialogs, or routes
+ * Act    → Execution of backend operations or actions
+ * See    → Visibility control for UI elements
+ * Access → Permission to enter system-level artifacts (apps, dashboards,
+ *             reports, cards, tiles, KPIs, dialogs, resources)
+ * ---------------------------------------------------------------------
+ *
+ * @example
+ * if ($ability->type === AbilityType::Act) {
+ *     // Perform business logic for action-level permission
+ * }
+ */
 enum AbilityType: int
 {
+    /**
+     * Frontend-level access to views, dialogs, or routes declared in manifest.json
+     */
     case Use = 0;
+
+    /**
+     * Permission to execute a backend operation or service action.
+     *
+     * Implementors that want to secure a frontend operation should
+     * work via the `AbilityType::See` instead.
+     */
     case Act = 1;
+
+    /**
+     * Controls visibility of UI elements such as buttons, dialogs,
+     * or sections. Typically used in the frontend to bind `visible`
+     * or `enabled` states to user abilities.
+     */
     case See = 2;
 
+    /**
+     * Backend-level access to entry-point artifacts without manifest anchors
+     */
+    case Access = 3;
+
+    /**
+     * Returns the canonical lowercase label used in manifests and caches.
+     *
+     * @return string
+     */
     public function label(): string
     {
         return match ($this) {
             self::Use => 'use',
             self::Act => 'act',
             self::See => 'see',
+            self::Access => 'access',
         };
     }
 
-    public function isAct(): bool
-    {
-        return $this === self::Act;
-    }
-
+    /**
+     * Creates an AbilityType from its canonical lowercase label.
+     *
+     * @param string $label
+     * @return self
+     */
     public static function fromLabel(string $label): self
     {
         return match ($label) {
             'use' => self::Use,
             'act' => self::Act,
             'see' => self::See,
+            'access' => self::Access,
             default => throw new InvalidArgumentException("Unknown AbilityType label: $label"),
         };
     }
+
+    /**
+     * Returns true if this AbilityType represents an action-level permission.
+     *
+     * @return bool
+     */
+    public function isAct(): bool
+    {
+        return $this === self::Act;
+    }
+
+    /**
+     * Returns true if this AbilityType represents an access-level permission.
+     *
+     * @return bool
+     */
+    public function isAccess(): bool
+    {
+        return $this === self::Access;
+    }
+
+    /**
+     * Determines whether this AbilityType should be declared
+     * inside the manifest.json (frontend domain) rather than
+     * in backend PHP annotations.
+     */
+    public function shouldBeInManifest(): bool
+    {
+        return match ($this) {
+            self::Use, self::See => true,
+            default => false,
+        };
+    }
 }
diff --git a/src/Ui5/Contracts/Ui5RegistryInterface.php b/src/Ui5/Contracts/Ui5RegistryInterface.php
@@ -2,6 +2,9 @@
 
 namespace LaravelUi5\Core\Ui5\Contracts;
 
+use LaravelUi5\Core\Enums\AbilityType;
+use LaravelUi5\Core\Enums\ArtifactType;
+
 /**
  * The `Ui5Registry` is the central coordination and introspection service
  * of the LaravelUi5 ecosystem. It provides a unified API to discover, inspect,
@@ -72,18 +75,52 @@ public function all(): array;
     public function roles(): array;
 
     /**
-     * Returns all abilities declared across all modules via #[Ability] attributes.
+     * Returns all registered abilities, grouped by namespace and ability type.
      *
-     * @return array<string, array>
+     * The result reflects the normalized internal structure:
+     * `$abilities[$namespace][$type->label()][$abilityName] = Ability`.
+     *
+     * - When `$namespace` is provided, abilities are limited to that artifact
+     *   namespace (e.g. "io.pragmatiqu.offers").
+     * - When `$type` is provided, only abilities of that `AbilityType`
+     *   (e.g. `AbilityType::Act`) are returned.
+     * - When both are null, all abilities across all namespaces and types
+     *   are returned.
+     *
+     * Example:
+     * ```php
+     * $registry->abilities('io.pragmatiqu.reports', AbilityType::Act);
+     * // → [ 'toggleLock' => Ability, 'exportPdf' => Ability, ... ]
+     * ```
+     *
+     * @param string|null $namespace Optional artifact namespace to filter by.
+     * @param ArtifactType|null $type Optional ability type to filter by.
+     * @return array
      */
-    public function abilities(): array;
+    public function abilities(?string $namespace = null, ?ArtifactType $type = null): array;
 
     /**
-     * Returns all settings declared across all artifacts via #[Setting] attributes.
+     * Returns all settings declared via #[Setting] attributes,
+     * grouped by artifact namespace.
      *
-     * @return array<string, array>
+     * - When `$namespace` is provided, only settings belonging to
+     *   that namespace are returned.
+     * - When `$namespace` is null, all settings across all registered
+     *   artifacts are returned.
+     *
+     * The result reflects the normalized internal structure:
+     * `$settings[$namespace][$settingName] = Setting`.
+     *
+     * Example:
+     * ```php
+     * $registry->settings('io.pragmatiqu.dashboard');
+     * // → [ 'refreshInterval' => Setting, 'theme' => Setting, ... ]
+     * ```
+     *
+     * @param string|null $namespace  Optional artifact namespace to filter by.
+     * @return array
      */
-    public function settings(): array;
+    public function settings(?string $namespace = null): array;
 
     /**
      * Returns all semantic objects declared via #[SemanticObject] attributes.
diff --git a/src/Ui5/Ui5Registry.php b/src/Ui5/Ui5Registry.php
@@ -13,10 +13,17 @@
 use LaravelUi5\Core\Ui5\Contracts\ReportActionInterface;
 use LaravelUi5\Core\Ui5\Contracts\SluggableInterface;
 use LaravelUi5\Core\Ui5\Contracts\Ui5ActionInterface;
+use LaravelUi5\Core\Ui5\Contracts\Ui5AppInterface;
 use LaravelUi5\Core\Ui5\Contracts\Ui5ArtifactInterface;
+use LaravelUi5\Core\Ui5\Contracts\Ui5CardInterface;
+use LaravelUi5\Core\Ui5\Contracts\Ui5DashboardInterface;
+use LaravelUi5\Core\Ui5\Contracts\Ui5DialogInterface;
+use LaravelUi5\Core\Ui5\Contracts\Ui5KpiInterface;
 use LaravelUi5\Core\Ui5\Contracts\Ui5ModuleInterface;
 use LaravelUi5\Core\Ui5\Contracts\Ui5RegistryInterface;
 use LaravelUi5\Core\Ui5\Contracts\Ui5ReportInterface;
+use LaravelUi5\Core\Ui5\Contracts\Ui5ResourceInterface;
+use LaravelUi5\Core\Ui5\Contracts\Ui5TileInterface;
 use LogicException;
 use ReflectionClass;
 use ReflectionException;
@@ -183,30 +190,47 @@ protected function discoverAbilities(Ui5ArtifactInterface|ReportActionInterface
             /** @var Ability $ability */
             $ability = $attributes[0]->newInstance();
 
-            if ($ability->type === AbilityType::Use) {
+            if ($ability->type->shouldBeInManifest()) {
                 throw new LogicException(sprintf(
-                    'Invalid ability declaration: [%s] uses type [Use], which is reserved for UI visibility. Move this definition to your manifest.json file.',
-                    $ability->name
+                    'AbilityType::%s for ability %s cannot be declared in backend artifacts (%s). Move this definition to your manifest.json file.',
+                    $ability->name,
+                    $ability->type->name,
+                    get_class($artifact)
                 ));
             }
 
-            if ($ability->type === AbilityType::Act && !($artifact instanceof Ui5ActionInterface || $artifact instanceof ReportActionInterface)) {
+            if ($ability->type->isAct() && !($artifact instanceof Ui5ActionInterface || $artifact instanceof ReportActionInterface)) {
                 throw new LogicException(sprintf(
-                    'Ability [%s] of type [Act] must be declared on an executable artifact, found on [%s].',
+                    'AbilityType::Act for ability %s must be declared on an executable artifact, found on (%s).',
                     $ability->name,
                     get_class($artifact)
                 ));
             }
 
-            if (array_key_exists($ability->name, $this->abilities[$namespace] ?? [])) {
+            if ($ability->type->isAccess() && !(
+                    $artifact instanceof Ui5AppInterface
+                    || $artifact instanceof Ui5CardInterface
+                    || $artifact instanceof Ui5ReportInterface
+                    || $artifact instanceof Ui5TileInterface
+                    || $artifact instanceof Ui5KpiInterface
+                    || $artifact instanceof Ui5DashboardInterface
+                    || $artifact instanceof Ui5ResourceInterface
+                    || $artifact instanceof Ui5DialogInterface
+                )) {
+                throw new LogicException(
+                    sprintf('AbilityType::Access is only valid for entry-level artifacts (%s)', get_class($artifact))
+                );
+            }
+
+            if (array_key_exists($ability->name, $this->abilities[$namespace][$ability->type->label()] ?? [])) {
                 throw new LogicException(sprintf(
                     'Duplicate ability [%s] found on [%s].',
                     $ability->name,
                     get_class($artifact)
                 ));
             }
 
-            $this->abilities[$namespace][$ability->name] = [
+            $this->abilities[$namespace][$ability->type->label()][$ability->name] = [
                 'type' => $ability->type->name,
                 'role' => $ability->role,
                 'note' => $ability->note,
@@ -429,14 +453,37 @@ public function roles(): array
         return $this->roles;
     }
 
-    public function abilities(): array
+    public function abilities(?string $namespace = null, ?ArtifactType $type = null): array
     {
-        return $this->abilities;
+        if ($namespace === null) {
+            if ($type === null) {
+                return $this->abilities;
+            }
+
+            $result = [];
+            foreach ($this->abilities as $ns => $types) {
+                if (isset($types[$type->label()])) {
+                    $result[$ns] = $types[$type->label()];
+                }
+            }
+
+            return $result;
+        }
+
+        if ($type === null) {
+            return $this->abilities[$namespace] ?? [];
+        }
+
+        return $this->abilities[$namespace][$type->label()] ?? [];
     }
 
-    public function settings(): array
+    public function settings(?string $namespace = null): array
     {
-        return $this->settings;
+        if (null === $namespace) {
+            return $this->settings;
+        }
+
+        return $this->settings[$namespace] ?? [];
     }
 
     public function objects(): array
diff --git a/tests/Unit/Ui5Registry/AbilitiesTest.php b/tests/Unit/Ui5Registry/AbilitiesTest.php
@@ -1,5 +1,6 @@
 <?php
 
+use LaravelUi5\Core\Enums\AbilityType;
 use LaravelUi5\Core\Ui5\Ui5Registry;
 use Tests\Fixture\Hello\Hello;
 
@@ -12,8 +13,10 @@
             ->toBeArray()
             ->toHaveKey(Hello::NAMESPACE)
             ->and($abilities[Hello::NAMESPACE])
+            ->toHaveKey(AbilityType::Act->label())
+            ->and($abilities[Hello::NAMESPACE][AbilityType::Act->label()])
             ->toHaveKey(Hello::ACTION_NAME)
-            ->and($abilities[Hello::NAMESPACE][Hello::ACTION_NAME])
+            ->and($abilities[Hello::NAMESPACE][AbilityType::Act->label()][Hello::ACTION_NAME])
             ->toMatchArray([
                 'type' => 'Act',
                 'role' => 'Admin',
@@ -30,7 +33,7 @@
             'modules' => [
                 'foo' => \Tests\Fixture\Hello\Errors\Ability\UseAbility\Module::class,
             ]
-        ]))->toThrow(LogicException::class, 'reserved for UI visibility');
+        ]))->toThrow(LogicException::class, 'cannot be declared in backend artifacts');
     });
 
     it('throws when Ability type ACT declared on non-action artifact', function () {
