| 1: | <?php |
| 2: | |
| 3: | namespace LaravelUi5\Core\Infrastructure\Contracts; |
| 4: | |
| 5: | use LogicException; |
| 6: | use ReflectionException; |
| 7: | |
| 8: | /** |
| 9: | * Resolves the appropriate Ui5SourceStrategy for a given UI5 module. |
| 10: | * |
| 11: | * The Ui5SourceStrategyResolver is responsible for deciding *how* |
| 12: | * UI5 source metadata should be accessed for a module, based on |
| 13: | * runtime context and filesystem layout. |
| 14: | * |
| 15: | * It encapsulates all resolution logic, including: |
| 16: | * - workspace overrides (e.g. .ui5-sources.php) |
| 17: | * - reflection-based module location |
| 18: | * - package conventions (vendor resources) |
| 19: | * |
| 20: | * The resolver does NOT: |
| 21: | * - read UI5 metadata itself |
| 22: | * - create Ui5Source objects directly |
| 23: | * - know anything about App vs Library consumers |
| 24: | * |
| 25: | * Instead, it returns a {@see Ui5SourceStrategyInterface} that |
| 26: | * fully encapsulates the chosen access strategy. |
| 27: | * |
| 28: | * Typical resolution flow: |
| 29: | * |
| 30: | * 1. Check for workspace override (developer workspace) |
| 31: | * 2. Fallback to package-based resolution via module class location |
| 32: | * 3. Fail explicitly if no valid source location can be resolved |
| 33: | * |
| 34: | * This resolver is intended to be: |
| 35: | * - used by Ui5Registry (Core & SDK) |
| 36: | * - cached at registry level |
| 37: | * - extended in the future (e.g. remote sources, prebuilt descriptors) |
| 38: | */ |
| 39: | interface Ui5SourceStrategyResolverInterface |
| 40: | { |
| 41: | /** |
| 42: | * Resolves the source strategy for the given module class. |
| 43: | * |
| 44: | * The module class does not need to be instantiated. |
| 45: | * Resolution is based on class name, reflection, and |
| 46: | * configured overrides. |
| 47: | * |
| 48: | * @param class-string $moduleClass Fully qualified module class name. |
| 49: | * @return Ui5SourceStrategyInterface A concrete strategy (e.g. WorkspaceStrategy, PackageStrategy). |
| 50: | * |
| 51: | * @throws ReflectionException If the module class cannot be reflected. |
| 52: | * @throws LogicException If no valid UI5 source location can be resolved. |
| 53: | */ |
| 54: | public function resolve(string $moduleClass): Ui5SourceStrategyInterface; |
| 55: | } |
| 56: |