| 1: | <?php |
| 2: | |
| 3: | declare(strict_types=1); |
| 4: | |
| 5: | namespace LaravelUi5\OData\Service\Contracts; |
| 6: | |
| 7: | use Illuminate\Database\Query\Builder; |
| 8: | use LaravelUi5\OData\Http\CustomQueryOptions; |
| 9: | |
| 10: | /** |
| 11: | * Formal contract for SQL-backed entity set data sources. |
| 12: | * |
| 13: | * Implementations provide the base query for an entity set, including any |
| 14: | * implicit filters (tenant scoping, user permissions, etc.). OData system |
| 15: | * query options ($filter, $orderby, $top, $skip) are applied on top by the |
| 16: | * resolver — they never override the base query's constraints. |
| 17: | * |
| 18: | * Implementations are resolved from the Laravel container so that dependencies |
| 19: | * (e.g., the current tenant or authenticated user) are injected automatically. |
| 20: | * |
| 21: | * Example: |
| 22: | * |
| 23: | * final readonly class PartnerValueHelpSource implements EntitySetSourceInterface |
| 24: | * { |
| 25: | * public function __construct(private TenantContext $tenant) {} |
| 26: | * |
| 27: | * public function query(CustomQueryOptions $options): Builder |
| 28: | * { |
| 29: | * return DB::table('partner_value_help') |
| 30: | * ->where('tenant_id', $this->tenant->id); |
| 31: | * } |
| 32: | * } |
| 33: | */ |
| 34: | interface EntitySetSourceInterface |
| 35: | { |
| 36: | /** |
| 37: | * Return the base query for this entity set. |
| 38: | * |
| 39: | * The returned builder must be a fresh instance on each call — it will be |
| 40: | * mutated by the resolver when applying OData system query options |
| 41: | * (`$filter`/`$orderby`/`$top`/`$skip`) on top. |
| 42: | * |
| 43: | * @param CustomQueryOptions $options The request's custom (non-`$`) query |
| 44: | * options, threaded from the URL. Correct under `$batch` (each inner |
| 45: | * request carries its own). Sources that don't use them ignore the arg. |
| 46: | */ |
| 47: | public function query(CustomQueryOptions $options): Builder; |
| 48: | } |
| 49: |