Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00%
0 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Core\Engine\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Core\Engine\Domain\Exception\ModuleNotFoundException;
12use App\Core\Engine\Domain\Model\FieldMetadata;
13use App\Core\Engine\Domain\Model\FilterGridMetadata;
14use App\Core\Engine\Domain\Model\FilterMetadata;
15use App\Core\Engine\Domain\Model\ModuleMetadata;
16use App\Core\Engine\Domain\Model\PermissionContext;
17use App\Core\Engine\Domain\Model\RelationGridMetadata;
18use App\Core\Engine\Domain\Model\SectionMetadata;
19use App\Core\Engine\Domain\Model\WidgetMetadata;
20
21/**
22 * Metadata Repository Interface.
23 *
24 * Defines the contract for reading engine metadata from persistent storage.
25 * Implemented by SqlMetadataRepository (Infrastructure) and decorated
26 * by RequestScopedMetadataCache for per-request in-memory caching.
27 *
28 * @package App\Core\Engine\Domain\Repository
29 */
30interface MetadataRepositoryInterface // NOSONAR
31{
32    /**
33     * Finds a module metadata record by its machine-readable name.
34     *
35     * @param string $moduleName Machine-readable module name slug.
36     * @return ModuleMetadata Resolved module value object.
37     * @throws ModuleNotFoundException When the module name cannot be found.
38     */
39    public function findModule(string $moduleName): ModuleMetadata;
40
41    /**
42     * Finds a module metadata record by its primary key ID.
43     *
44     * @param int $moduleId Module primary key ID.
45     * @return ModuleMetadata Resolved module value object.
46     * @throws ModuleNotFoundException When the module ID cannot be found.
47     */
48    public function findModuleById(int $moduleId): ModuleMetadata;
49
50    /**
51     * Returns all active module metadata definitions indexed by machine-readable name.
52     *
53     * @return array<string, ModuleMetadata>
54     */
55    public function findAllActiveModules(): array;
56
57    /**
58     * Returns all field definitions for a given module, ordered by sort_order.
59     *
60     * @param int $moduleId Module primary key.
61     * @return array<int, FieldMetadata> Ordered list of field metadata value objects.
62     */
63    public function findFields(int $moduleId): array;
64
65    /**
66     * Returns field definitions configured for global search for a given module.
67     *
68     * @param int $moduleId Module primary key.
69     * @return array<int, FieldMetadata> Ordered list of global search field metadata.
70     */
71    public function findGlobalSearchFields(int $moduleId): array;
72
73    /**
74     * Returns all logical field sections configured for a given module, ordered by sort_order.
75     *
76     * @param int $moduleId Module primary key.
77     * @return array<int, SectionMetadata> Ordered list of section metadata value objects.
78     */
79    public function findSections(int $moduleId): array;
80
81    /**
82     * Finds the filter configuration for a given module.
83     *
84     * If no specific filter ID is given, returns the default filter (is_default=1).
85     * If no default filter exists, returns a fallback showing all non-system fields.
86     *
87     * @param int      $moduleId Module primary key.
88     * @param int|null $filterId Optional specific filter primary key.
89     * @return FilterMetadata Resolved filter value object.
90     */
91    public function findFilter(int $moduleId, ?int $filterId): FilterMetadata;
92
93    /**
94     * Returns all accessible filter configurations for a given module and user context.
95     *
96     * @param int               $moduleId Module primary key.
97     * @param PermissionContext $context  Active user security context.
98     * @return array<int, FilterMetadata> List of visible filter value objects.
99     */
100    public function findModuleFilters(int $moduleId, PermissionContext $context): array;
101
102    /**
103     * Finds the GRID filter configuration for a given module.
104     *
105     * @param int      $moduleId     Module primary key.
106     * @param int|null $filterGridId Optional specific grid filter ID.
107     * @return FilterGridMetadata Resolved filter grid value object.
108     */
109    public function findFilterGrid(int $moduleId, ?int $filterGridId): FilterGridMetadata;
110
111    /**
112     * Returns all accessible GRID filter configurations for a given module.
113     *
114     * @param int               $moduleId Module primary key.
115     * @param PermissionContext $context  Active user security context.
116     * @return array<int, FilterGridMetadata> List of visible grid filter value objects.
117     */
118    public function findModuleFiltersGrid(int $moduleId, PermissionContext $context): array;
119
120    /**
121     * Finds a single widget metadata definition by its ID.
122     *
123     * @param int $widgetId Widget primary key.
124     * @return WidgetMetadata|null Resolved widget or null.
125     */
126    public function findWidget(int $widgetId): ?WidgetMetadata;
127
128    /**
129     * Returns all active widgets in the catalog.
130     *
131     * @return array<int, WidgetMetadata>
132     */
133    public function findAllActiveWidgets(): array;
134
135    /**
136     * Returns all GRID widget placement relations for a given module and optional grid filter.
137     *
138     * @param int      $moduleId     Module primary key ID.
139     * @param int|null $filterGridId Optional grid filter ID.
140     * @return array<int, RelationGridMetadata>
141     */
142    public function findGridRelationsByModule(int $moduleId, ?int $filterGridId = null): array;
143
144    /**
145     * Returns a list of all active module id and label pairs for relational dropdowns.
146     *
147     * @return array<int, array{id: int, name: string, label: string}>
148     */
149    public function findAllModuleOptions(): array;
150
151    /**
152     * Returns distinct faceted filter options present in the module table for all filterable fields.
153     *
154     * @param ModuleMetadata            $module  Module metadata.
155     * @param array<int, FieldMetadata> $fields  Module field definitions.
156     * @param PermissionContext         $context Security context.
157     * @return array<string, array<int, array{id: int|string, label: string, is_active?: int}>>
158     */
159    public function findFacetedFilterOptions(
160        ModuleMetadata    $module,
161        array             $fields,
162        PermissionContext $context
163    ): array;
164
165    /**
166     * Returns a list of all user id, username and active status pairs for relational dropdowns.
167     *
168     * @param string|null $tablePrefix Optional table prefix override ('a_' or 'c_').
169     * @return array<int, array{id: int, label: string, is_active?: int}>
170     */
171    public function findAllUserOptions(?string $tablePrefix = null): array;
172
173    /**
174     * Returns a list of all active structure node options for relational dropdowns.
175     *
176     * @param string|null $tablePrefix Optional table prefix override ('a_' or 'c_').
177     * @return array<int, array{id: int, label: string, is_active?: int}>
178     */
179    public function findAllStructureOptions(?string $tablePrefix = null): array;
180
181    /**
182     * Returns a list of all active picklist options, optionally filtered by module ID.
183     *
184     * @param int|null $moduleId Optional module ID filter.
185     * @return array<int, array<string, mixed>> List of picklist catalog options.
186     */
187    public function findAllPicklistOptions(?int $moduleId = null): array;
188
189    /**
190     * Returns a list of all active UiType options ordered by label.
191     *
192     * @return array<int, array{id: int, name: string, label: string}> List of UiType options.
193     */
194    public function findAllUitypeOptions(): array;
195
196    /**
197     * Returns all values for a given picklist ID ordered by sort_order.
198     *
199     * @param int $picklistId Picklist primary key ID.
200     * @return array<int, array<string, mixed>> List of picklist values.
201     */
202    public function findPicklistValues(int $picklistId): array;
203
204    /**
205     * Returns all active 1:M relations where the given module is the source parent.
206     *
207     * @param int $sourceModuleId Source module primary key ID.
208     * @return array<int, \App\Core\Engine\Domain\Model\Relation1mMetadata> List of relations.
209     */
210    public function findRelationsBySourceModule(int $sourceModuleId): array;
211
212    /**
213     * Returns all active M:M relations where the given module is in source_module_ids.
214     *
215     * @param int $sourceModuleId Source module primary key ID.
216     * @return array<int, \App\Core\Engine\Domain\Model\RelationMmMetadata> List of M:M relations.
217     */
218    public function findMmRelationsBySourceModule(int $sourceModuleId): array;
219
220    /**
221     * Clears cached metadata entries, optionally limited to a specific module ID.
222     *
223     * @param int|null $moduleId Optional module ID to invalidate.
224     */
225    public function clearCache(?int $moduleId = null): void;
226}