| 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: | * Returns the module instance for the given slug, or null if not found. |
| 62: | * |
| 63: | * @param string $namespace The URL slug to identify the module (from `config/ui5.php > modules`) |
| 64: | * @return Ui5ModuleInterface|null The instantiated module, or null if not found |
| 65: | */ |
| 66: | public function getModule(string $namespace): ?Ui5ModuleInterface; |
| 67: | |
| 68: | /** |
| 69: | * Returns all registered artifacts across all modules. |
| 70: | * |
| 71: | * @return array<string, Ui5ArtifactInterface> |
| 72: | */ |
| 73: | public function artifacts(): array; |
| 74: | |
| 75: | /** |
| 76: | * Returns the artifact instance for the given namespace, or null if not found. |
| 77: | * |
| 78: | * @param string $namespace The fqn of the UI5 artifact |
| 79: | * @return Ui5ArtifactInterface|null The instantiated artifact, or null if not found |
| 80: | */ |
| 81: | public function get(string $namespace): ?Ui5ArtifactInterface; |
| 82: | |
| 83: | /** |
| 84: | * Returns all settings declared via #[Setting] attributes, |
| 85: | * grouped by artifact namespace. |
| 86: | * |
| 87: | * - When `$namespace` is provided, only settings belonging to |
| 88: | * that namespace are returned. |
| 89: | * - When `$namespace` is null, all settings across all registered |
| 90: | * artifacts are returned. |
| 91: | * |
| 92: | * The result reflects the normalized internal structure: |
| 93: | * `$settings[$namespace][$settingName] = Setting`. |
| 94: | * |
| 95: | * Example: |
| 96: | * ```php |
| 97: | * $registry->settings('io.pragmatiqu.dashboard'); |
| 98: | * // → [ 'refreshInterval' => Setting, 'theme' => Setting, ... ] |
| 99: | * ``` |
| 100: | * |
| 101: | * @param string|null $namespace Optional artifact namespace to filter by. |
| 102: | * @return array |
| 103: | */ |
| 104: | public function settings(?string $namespace = null): array; |
| 105: | |
| 106: | /** |
| 107: | * Converts external URI path segments to canonical registry namespace. |
| 108: | * |
| 109: | * Example: |
| 110: | * - "io/pragmatiqu/partners" → "io.pragmatiqu.partners" |
| 111: | * |
| 112: | * This method centralizes URI-to-registry normalization logic and |
| 113: | * avoids scattering string transformation rules across the codebase. |
| 114: | * |
| 115: | * @param string $namespace |
| 116: | * @return string |
| 117: | */ |
| 118: | public function pathToNamespace(string $namespace): string; |
| 119: | |
| 120: | /** |
| 121: | * Converts canonical registry namespace to external URI path segments. |
| 122: | * |
| 123: | * Example: |
| 124: | * - "io.pragmatiqu.partners" → "io/pragmatiqu/partners" |
| 125: | * |
| 126: | * This method centralizes registry-to-URI normalization logic and |
| 127: | * avoids scattering string transformation rules across the codebase. |
| 128: | * |
| 129: | * @param string $namespace |
| 130: | * @return string |
| 131: | */ |
| 132: | public function namespaceToPath(string $namespace): string; |
| 133: | |
| 134: | /** |
| 135: | * Resolves a full public URL path for the given namespace |
| 136: | * (e.g. "/ui5/app/offers/1.0.0"). |
| 137: | * |
| 138: | * @param string $namespace The fqn of the UI5 artifact |
| 139: | * @return string|null The absolute path, or null if not found |
| 140: | */ |
| 141: | public function resolve(string $namespace): ?string; |
| 142: | |
| 143: | /** |
| 144: | * Resolves resource root URLs (namespace => URL) for multiple namespaces. |
| 145: | * |
| 146: | * @param array<int,string> $namespaces The fqn of the UI5 artifact (app or lib!) |
| 147: | * @return array<string,string> |
| 148: | */ |
| 149: | public function resolveRoots(array $namespaces): array; |
| 150: | } |
| 151: |