| 1: | <?php |
| 2: | |
| 3: | namespace LaravelUi5\Core\Ui5\Contracts; |
| 4: | |
| 5: | use LaravelUi5\Core\Enums\ArtifactType; |
| 6: | |
| 7: | /** |
| 8: | * Interface Ui5RegistryInterface |
| 9: | * |
| 10: | * Defines the build-time introspection and coordination contract of the |
| 11: | * LaravelUi5 ecosystem. The registry exposes a unified API to discover, |
| 12: | * inspect, and reflect upon all UI5-related modules, artifacts, roles, |
| 13: | * abilities, settings, and semantic objects declared in a Laravel application. |
| 14: | * |
| 15: | * The registry operates at development or build time and performs reflection |
| 16: | * across modules and PHP attributes. It is the authoritative source for |
| 17: | * generating cache files, documentation, and metadata used at runtime |
| 18: | * by the {@see Ui5RuntimeInterface}. |
| 19: | * |
| 20: | * Responsibilities: |
| 21: | * - Discover modules and artifacts from configuration and attributes |
| 22: | * - Collect and normalize metadata (roles, abilities, settings, semantic objects) |
| 23: | * - Provide build-time data for the runtime cache generator (`ui5:cache`) |
| 24: | * |
| 25: | * System guarantees: |
| 26: | * - Every module has a unique slug |
| 27: | * - Every artifact has a globally unique namespace |
| 28: | * - Artifacts are addressable either through their module or namespace |
| 29: | * |
| 30: | * Example use cases: |
| 31: | * - Generate the runtime cache file via `php artisan ui5:cache` |
| 32: | * - Produce manifest.json files or capability maps for modules |
| 33: | * - Inspect declared roles, settings, or abilities for validation or documentation |
| 34: | * |
| 35: | * @package LaravelUi5\Core\Ui5\Contracts |
| 36: | */ |
| 37: | interface Ui5RegistryInterface extends Ui5RuntimeInterface |
| 38: | { |
| 39: | /** |
| 40: | * Returns all registered modules. |
| 41: | * |
| 42: | * @return Ui5ModuleInterface[] |
| 43: | */ |
| 44: | public function modules(): array; |
| 45: | |
| 46: | /** |
| 47: | * Returns all registered artifacts across all modules. |
| 48: | * |
| 49: | * @return Ui5ArtifactInterface[] |
| 50: | */ |
| 51: | public function artifacts(): array; |
| 52: | |
| 53: | /** |
| 54: | * Returns all roles declared across all modules via #[Role] attributes. |
| 55: | * |
| 56: | * @return array<string, array> |
| 57: | */ |
| 58: | public function roles(): array; |
| 59: | |
| 60: | /** |
| 61: | * Returns all registered abilities, grouped by namespace and ability type. |
| 62: | * |
| 63: | * The result reflects the normalized internal structure: |
| 64: | * `$abilities[$namespace][$type->label()][$abilityName] = Ability`. |
| 65: | * |
| 66: | * - When `$namespace` is provided, abilities are limited to that artifact |
| 67: | * namespace (e.g. "io.pragmatiqu.offers"). |
| 68: | * - When `$type` is provided, only abilities of that `AbilityType` |
| 69: | * (e.g. `AbilityType::Act`) are returned. |
| 70: | * - When both are null, all abilities across all namespaces and types |
| 71: | * are returned. |
| 72: | * |
| 73: | * Example: |
| 74: | * ```php |
| 75: | * $registry->abilities('io.pragmatiqu.reports', AbilityType::Act); |
| 76: | * // → [ 'toggleLock' => Ability, 'exportPdf' => Ability, ... ] |
| 77: | * ``` |
| 78: | * |
| 79: | * @param string|null $namespace Optional artifact namespace to filter by. |
| 80: | * @param ArtifactType|null $type Optional ability type to filter by. |
| 81: | * @return array |
| 82: | */ |
| 83: | public function abilities(?string $namespace = null, ?ArtifactType $type = null): array; |
| 84: | |
| 85: | /** |
| 86: | * Returns all settings declared via #[Setting] attributes, |
| 87: | * grouped by artifact namespace. |
| 88: | * |
| 89: | * - When `$namespace` is provided, only settings belonging to |
| 90: | * that namespace are returned. |
| 91: | * - When `$namespace` is null, all settings across all registered |
| 92: | * artifacts are returned. |
| 93: | * |
| 94: | * The result reflects the normalized internal structure: |
| 95: | * `$settings[$namespace][$settingName] = Setting`. |
| 96: | * |
| 97: | * Example: |
| 98: | * ```php |
| 99: | * $registry->settings('io.pragmatiqu.dashboard'); |
| 100: | * // → [ 'refreshInterval' => Setting, 'theme' => Setting, ... ] |
| 101: | * ``` |
| 102: | * |
| 103: | * @param string|null $namespace Optional artifact namespace to filter by. |
| 104: | * @return array |
| 105: | */ |
| 106: | public function settings(?string $namespace = null): array; |
| 107: | |
| 108: | /** |
| 109: | * Returns all semantic objects declared via #[SemanticObject] attributes. |
| 110: | * |
| 111: | * Each object entry describes a business entity and its |
| 112: | * available routes or actions as defined in PHP attributes. |
| 113: | * |
| 114: | * Example structure: |
| 115: | * [ |
| 116: | * "User" => [ |
| 117: | * "name" => "User", |
| 118: | * "module" => "users", |
| 119: | * "routes" => [ |
| 120: | * "display" => ["label" => "Show", "icon" => "sap-icon://display"], |
| 121: | * "edit" => ["label" => "Edit", "icon" => "sap-icon://edit"] |
| 122: | * ] |
| 123: | * ] |
| 124: | * ] |
| 125: | * |
| 126: | * @return array<string, array> |
| 127: | */ |
| 128: | public function objects(): array; |
| 129: | } |
| 130: |