1: | <?php declare(strict_types=1); |
2: | |
3: | namespace Salient\Contract\Sync; |
4: | |
5: | use Salient\Contract\Sync\SyncEntityLinkType as LinkType; |
6: | use Closure; |
7: | use LogicException; |
8: | |
9: | /** |
10: | * @template TEntity of SyncEntityInterface |
11: | */ |
12: | interface DeferredEntityInterface |
13: | { |
14: | /** |
15: | * Get the context within which the provider is servicing the entity |
16: | */ |
17: | public function getContext(): ?SyncContextInterface; |
18: | |
19: | /** |
20: | * Get the deferred entity's canonical location in the form of an array |
21: | * |
22: | * @param LinkType::* $type |
23: | * @return array<string,int|string> |
24: | */ |
25: | public function toLink(int $type = LinkType::DEFAULT, bool $compact = true): array; |
26: | |
27: | /** |
28: | * Get the deferred entity's canonical location in the form of a URI |
29: | */ |
30: | public function getUri(bool $compact = true): string; |
31: | |
32: | /** |
33: | * Resolve the deferred entity from the provider or the local entity store |
34: | * |
35: | * This method returns the resolved entity without taking further action. |
36: | * {@see DeferredEntityInterface::replace()} is called separately. |
37: | * |
38: | * @return TEntity |
39: | */ |
40: | public function resolve(): SyncEntityInterface; |
41: | |
42: | /** |
43: | * Resolve the deferred entity with an instance |
44: | * |
45: | * If `$callback` was given when the entity was deferred, it is called with |
46: | * the given entity, otherwise the variable or property given via `$replace` |
47: | * is replaced. |
48: | * |
49: | * Subsequent calls to {@see DeferredEntityInterface::resolve()} return the |
50: | * same instance. |
51: | * |
52: | * @param TEntity $entity |
53: | * @throws LogicException if the entity has already been resolved. |
54: | */ |
55: | public function replace(SyncEntityInterface $entity): void; |
56: | |
57: | /** |
58: | * Defer retrieval of a sync entity |
59: | * |
60: | * @param SyncProviderInterface $provider The provider servicing the entity. |
61: | * @param SyncContextInterface|null $context The context within which the |
62: | * provider is servicing the entity. |
63: | * @param class-string<TEntity> $entity The entity to instantiate. |
64: | * @param int|string $entityId The identifier of the deferred entity. |
65: | * @param TEntity|static|null $replace Refers to the variable or property to |
66: | * replace when the entity is resolved. |
67: | * @param (Closure(TEntity): void)|null $callback If given, `$replace` is |
68: | * ignored and the resolved entity is passed to the callback. |
69: | */ |
70: | public static function defer( |
71: | SyncProviderInterface $provider, |
72: | ?SyncContextInterface $context, |
73: | string $entity, |
74: | $entityId, |
75: | &$replace = null, |
76: | ?Closure $callback = null |
77: | ): void; |
78: | |
79: | /** |
80: | * Defer retrieval of a list of sync entities |
81: | * |
82: | * @param SyncProviderInterface $provider The provider servicing the entity. |
83: | * @param SyncContextInterface|null $context The context within which the |
84: | * provider is servicing the entity. |
85: | * @param class-string<TEntity> $entity The entity to instantiate. |
86: | * @param array<int|string> $entityIds A list of deferred entity |
87: | * identifiers. |
88: | * @param array<TEntity|static>|null $replace Refers to the variable or |
89: | * property to replace when the entities are resolved. |
90: | * @param (Closure(TEntity): void)|null $callback If given, `$replace` is |
91: | * ignored and each resolved entity is passed to the callback. |
92: | */ |
93: | public static function deferList( |
94: | SyncProviderInterface $provider, |
95: | ?SyncContextInterface $context, |
96: | string $entity, |
97: | array $entityIds, |
98: | &$replace = null, |
99: | ?Closure $callback = null |
100: | ): void; |
101: | } |
102: |