| 1: | <?php |
| 2: | |
| 3: | namespace LaravelUi5\Core\Ui5\Contracts; |
| 4: | |
| 5: | /** |
| 6: | * Interface Ui5RegistryInterface |
| 7: | * |
| 8: | * Build-time registry and introspection contract for the LaravelUi5 Core. |
| 9: | * |
| 10: | * The Ui5Registry is the authoritative source of truth for all UI5-related |
| 11: | * artifacts declared in a Laravel application. It is responsible for |
| 12: | * discovering, instantiating, and indexing UI5 modules and artifacts |
| 13: | * based on configuration and PHP attributes. |
| 14: | * |
| 15: | * The registry operates exclusively at build time (or during application |
| 16: | * bootstrapping) and is intentionally reflection-heavy. Its primary purpose |
| 17: | * is to provide normalized, deterministic metadata for: |
| 18: | * |
| 19: | * - runtime cache generation |
| 20: | * - manifest and resource root assembly |
| 21: | * - documentation and inspection tooling |
| 22: | * |
| 23: | * The registry does NOT: |
| 24: | * - perform authorization |
| 25: | * - interpret semantic meaning |
| 26: | * - resolve user intents |
| 27: | * - make runtime decisions |
| 28: | * |
| 29: | * In Core 2.0, the registry is strictly technical and URI-oriented. |
| 30: | * Semantic concerns (navigation meaning, intent declaration, authorization) |
| 31: | * are explicitly handled by the SDK layer. |
| 32: | * |
| 33: | * Responsibilities: |
| 34: | * - Discover UI5 modules from configuration |
| 35: | * - Discover UI5 artifacts via module registration |
| 36: | * - Guarantee uniqueness of module slugs and artifact namespaces |
| 37: | * - Provide deterministic lookup structures for cache generation |
| 38: | * |
| 39: | * System guarantees: |
| 40: | * - Each module has exactly one unique slug |
| 41: | * - Each artifact has a globally unique namespace |
| 42: | * - Artifact type (app, lib, action, report, …) is stable and deterministic |
| 43: | * |
| 44: | * Typical consumers: |
| 45: | * - ui5:cache command |
| 46: | * - build-time manifest generators |
| 47: | * - tooling and diagnostics |
| 48: | * |
| 49: | * @package LaravelUi5\Core\Ui5\Contracts |
| 50: | */ |
| 51: | interface Ui5RegistryInterface |
| 52: | { |
| 53: | /** |
| 54: | * Returns all registered modules. |
| 55: | * |
| 56: | * @return array<string, Ui5ModuleInterface> |
| 57: | */ |
| 58: | public function modules(): array; |
| 59: | |
| 60: | /** |
| 61: | * Checks whether a module with the given slug exists. |
| 62: | * |
| 63: | * @param string $slug The URL slug to identify the module (from `config/ui5.php > modules`) |
| 64: | * @return bool True if module for slug is known |
| 65: | */ |
| 66: | public function hasModule(string $slug): bool; |
| 67: | |
| 68: | /** |
| 69: | * Returns the module instance for the given slug, or null if not found. |
| 70: | * |
| 71: | * @param string $slug The URL slug to identify the module (from `config/ui5.php > modules`) |
| 72: | * @return Ui5ModuleInterface|null The instantiated module, or null if not found |
| 73: | */ |
| 74: | public function getModule(string $slug): ?Ui5ModuleInterface; |
| 75: | |
| 76: | /** |
| 77: | * Returns all registered artifacts across all modules. |
| 78: | * |
| 79: | * @return array<string, Ui5ArtifactInterface> |
| 80: | */ |
| 81: | public function artifacts(): array; |
| 82: | |
| 83: | /** |
| 84: | * Checks whether an artifact with the given namespace is registered. |
| 85: | * |
| 86: | * @param string $namespace The fqn of the UI5 artifact |
| 87: | * @return bool True if namespace for artifact is known |
| 88: | */ |
| 89: | public function has(string $namespace): bool; |
| 90: | |
| 91: | /** |
| 92: | * Returns the artifact instance for the given namespace, or null if not found. |
| 93: | * |
| 94: | * @param string $namespace The fqn of the UI5 artifact |
| 95: | * @return Ui5ArtifactInterface|null The instantiated artifact, or null if not found |
| 96: | */ |
| 97: | public function get(string $namespace): ?Ui5ArtifactInterface; |
| 98: | |
| 99: | /** |
| 100: | * Returns all settings declared via #[Setting] attributes, |
| 101: | * grouped by artifact namespace. |
| 102: | * |
| 103: | * - When `$namespace` is provided, only settings belonging to |
| 104: | * that namespace are returned. |
| 105: | * - When `$namespace` is null, all settings across all registered |
| 106: | * artifacts are returned. |
| 107: | * |
| 108: | * The result reflects the normalized internal structure: |
| 109: | * `$settings[$namespace][$settingName] = Setting`. |
| 110: | * |
| 111: | * Example: |
| 112: | * ```php |
| 113: | * $registry->settings('io.pragmatiqu.dashboard'); |
| 114: | * // → [ 'refreshInterval' => Setting, 'theme' => Setting, ... ] |
| 115: | * ``` |
| 116: | * |
| 117: | * @param string|null $namespace Optional artifact namespace to filter by. |
| 118: | * @return array |
| 119: | */ |
| 120: | public function settings(?string $namespace = null): array; |
| 121: | |
| 122: | /** |
| 123: | * Returns the artifact instance for the given slug (as used in routing or URLs), |
| 124: | * or null if not found. |
| 125: | * |
| 126: | * @param string $slug The URL slug to identify the artifact |
| 127: | * @return Ui5ArtifactInterface|null The instantiated artifact, or null if not found |
| 128: | */ |
| 129: | public function fromSlug(string $slug): ?Ui5ArtifactInterface; |
| 130: | |
| 131: | /** |
| 132: | * Resolves a full public URL path for the given namespace |
| 133: | * (e.g. "/ui5/app/offers/1.0.0"). |
| 134: | * |
| 135: | * @param string $namespace The fqn of the UI5 artifact |
| 136: | * @return string|null The absolute path, or null if not found |
| 137: | */ |
| 138: | public function resolve(string $namespace): ?string; |
| 139: | |
| 140: | /** |
| 141: | * Resolves resource root URLs (namespace => URL) for multiple namespaces. |
| 142: | * |
| 143: | * @param array<int,string> $namespaces The fqn of the UI5 artifact (app or lib!) |
| 144: | * @return array<string,string> |
| 145: | */ |
| 146: | public function resolveRoots(array $namespaces): array; |
| 147: | } |
| 148: |