| 1: | <?php |
| 2: | |
| 3: | namespace LaravelUi5\Core\Ui5\Contracts; |
| 4: | |
| 5: | /** |
| 6: | * Interface Ui5RuntimeInterface |
| 7: | * |
| 8: | * Defines the runtime lookup contract for the LaravelUi5 ecosystem. |
| 9: | * This interface provides a minimal, read-only API to efficiently |
| 10: | * resolve modules, artifacts, and semantic navigation data. |
| 11: | * |
| 12: | * The runtime interface is designed for performance and determinism: |
| 13: | * it supposes no reflection, scanning, or configuration merges. |
| 14: | * Instead, it exposes lightweight lookups for runtime use cases such as |
| 15: | * request routing, resource resolution, and intent navigation. |
| 16: | * |
| 17: | * Example use cases: |
| 18: | * - Resolve a module instance for an incoming route (e.g. `/ui5/app/users/...`) |
| 19: | * - Instantiate a UI5 artifact based on its namespace or slug |
| 20: | * - Generate runtime resource roots for a set of modules |
| 21: | * - Resolve cross-module navigation intents for deep links |
| 22: | * |
| 23: | * @package LaravelUi5\Core\Ui5\Contracts |
| 24: | */ |
| 25: | interface Ui5RuntimeInterface |
| 26: | { |
| 27: | /** |
| 28: | * Checks whether a module with the given slug exists. |
| 29: | * |
| 30: | * @param string $slug The URL slug to identify the module (from `config/ui5.php > modules`) |
| 31: | * @return bool True if module for slug is known |
| 32: | */ |
| 33: | public function hasModule(string $slug): bool; |
| 34: | |
| 35: | /** |
| 36: | * Returns the module instance for the given slug, or null if not found. |
| 37: | * |
| 38: | * @param string $slug The URL slug to identify the module (from `config/ui5.php > modules`) |
| 39: | * @return Ui5ModuleInterface|null The instantiated module, or null if not found |
| 40: | */ |
| 41: | public function getModule(string $slug): ?Ui5ModuleInterface; |
| 42: | |
| 43: | /** |
| 44: | * Checks whether an artifact with the given namespace is registered. |
| 45: | * |
| 46: | * @param string $namespace The fqn of the UI5 artifact |
| 47: | * @return bool True if namespace for artifact is known |
| 48: | */ |
| 49: | public function has(string $namespace): bool; |
| 50: | |
| 51: | /** |
| 52: | * Returns the artifact instance for the given namespace, or null if not found. |
| 53: | * |
| 54: | * @param string $namespace The fqn of the UI5 artifact |
| 55: | * @return Ui5ArtifactInterface|null The instantiated artifact, or null if not found |
| 56: | */ |
| 57: | public function get(string $namespace): ?Ui5ArtifactInterface; |
| 58: | |
| 59: | /** |
| 60: | * Returns all settings declared via #[Setting] attributes, |
| 61: | * grouped by artifact namespace. |
| 62: | * |
| 63: | * - When `$namespace` is provided, only settings belonging to |
| 64: | * that namespace are returned. |
| 65: | * - When `$namespace` is null, all settings across all registered |
| 66: | * artifacts are returned. |
| 67: | * |
| 68: | * The result reflects the normalized internal structure: |
| 69: | * `$settings[$namespace][$settingName] = Setting`. |
| 70: | * |
| 71: | * Example: |
| 72: | * ```php |
| 73: | * $registry->settings('io.pragmatiqu.dashboard'); |
| 74: | * // → [ 'refreshInterval' => Setting, 'theme' => Setting, ... ] |
| 75: | * ``` |
| 76: | * |
| 77: | * @param string|null $namespace Optional artifact namespace to filter by. |
| 78: | * @return array |
| 79: | */ |
| 80: | public function settings(?string $namespace = null): array; |
| 81: | |
| 82: | /** |
| 83: | * Returns the artifact instance for the given slug (as used in routing or URLs), |
| 84: | * or null if not found. |
| 85: | * |
| 86: | * @param string $slug The URL slug to identify the artifact |
| 87: | * @return Ui5ArtifactInterface|null The instantiated artifact, or null if not found |
| 88: | */ |
| 89: | public function fromSlug(string $slug): ?Ui5ArtifactInterface; |
| 90: | |
| 91: | /** |
| 92: | * Returns the canonical slug (e.g. "app/offers") for the given artifact. |
| 93: | * |
| 94: | * @param Ui5ArtifactInterface $artifact |
| 95: | * @return string|null |
| 96: | */ |
| 97: | public function slugFor(Ui5ArtifactInterface $artifact): ?string; |
| 98: | |
| 99: | /** |
| 100: | * Resolves a full public URL path for the given namespace |
| 101: | * (e.g. "/ui5/app/offers/1.0.0"). |
| 102: | * |
| 103: | * @param string $namespace The fqn of the UI5 artifact |
| 104: | * @return string|null The absolute path, or null if not found |
| 105: | */ |
| 106: | public function resolve(string $namespace): ?string; |
| 107: | |
| 108: | /** |
| 109: | * Resolves all semantic navigation intents for the given module. |
| 110: | * |
| 111: | * @param string $slug The module slug |
| 112: | * @return array<string, array<string, array>> |
| 113: | */ |
| 114: | public function resolveIntents(string $slug): array; |
| 115: | |
| 116: | /** |
| 117: | * Resolves resource root URLs (namespace => URL) for multiple namespaces. |
| 118: | * |
| 119: | * @param array<int,string> $namespaces The fqn of the UI5 artifact (app or lib!) |
| 120: | * @return array<string,string> |
| 121: | */ |
| 122: | public function resolveRoots(array $namespaces): array; |
| 123: | } |
| 124: |