1: | <?php declare(strict_types=1); |
2: | |
3: | namespace Salient\Contract\Core; |
4: | |
5: | use Salient\Contract\Container\ContainerInterface; |
6: | use Salient\Contract\Container\HasContainer; |
7: | |
8: | /** |
9: | * The context within which entities of a given type are instantiated by a |
10: | * provider |
11: | * |
12: | * @template TProvider of ProviderInterface |
13: | * @template TEntity of Providable |
14: | * |
15: | * @extends HasProvider<TProvider> |
16: | */ |
17: | interface ProviderContextInterface extends |
18: | Immutable, |
19: | HasContainer, |
20: | HasProvider |
21: | { |
22: | /** |
23: | * Apply a container to the context |
24: | * |
25: | * @return static |
26: | */ |
27: | public function withContainer(ContainerInterface $container); |
28: | |
29: | /** |
30: | * Push the entity propagating the context onto the stack |
31: | * |
32: | * Note that although the same entity may be passed to both |
33: | * {@see ProviderContextInterface::push()} and |
34: | * {@see ProviderContextInterface::withParent()} (e.g. when a hierarchy is |
35: | * being populated from a root entity), they serve different purposes. |
36: | * |
37: | * Example: a `Post` object would `push()` itself onto the entity stack to |
38: | * retrieve a `User` instance for its `Author` property, but a `Staff` |
39: | * object would `push()` itself onto the entity stack to retrieve `Staff` |
40: | * instances for its `DirectReports` property, **and** pass itself to |
41: | * `withParent()` as the parent (a.k.a. manager) of those `Staff`. |
42: | * |
43: | * Pushing an entity that implements {@see HasId} onto the stack implicitly |
44: | * adds its unique identifier to the context as a value with name |
45: | * `<entity_basename>_id` if {@see HasId::getId()} returns a value other |
46: | * than `null`. |
47: | * |
48: | * @param TEntity $entity |
49: | * @return static |
50: | */ |
51: | public function push($entity); |
52: | |
53: | /** |
54: | * Apply a value to the context |
55: | * |
56: | * @param (int|string|float|bool|null)[]|int|string|float|bool|null $value |
57: | * @return static |
58: | */ |
59: | public function withValue(string $name, $value); |
60: | |
61: | /** |
62: | * Apply a parent entity to the context |
63: | * |
64: | * @see ProviderContextInterface::push() |
65: | * |
66: | * @param (TEntity&Treeable)|null $parent |
67: | * @return static |
68: | */ |
69: | public function withParent(?Treeable $parent); |
70: | |
71: | /** |
72: | * Apply the current payload's array key conformity to the context |
73: | * |
74: | * @param ListConformity::* $conformity Use {@see ListConformity::COMPLETE} |
75: | * wherever possible to improve performance. |
76: | * @return static |
77: | */ |
78: | public function withConformity($conformity); |
79: | |
80: | /** |
81: | * @return TProvider |
82: | */ |
83: | public function getProvider(): ProviderInterface; |
84: | |
85: | /** |
86: | * Get the entities responsible for propagating this context |
87: | * |
88: | * @return TEntity[] |
89: | */ |
90: | public function stack(): array; |
91: | |
92: | /** |
93: | * Get the entity responsible for the most recent propagation of this |
94: | * context |
95: | * |
96: | * @return TEntity|null |
97: | */ |
98: | public function last(): ?Providable; |
99: | |
100: | /** |
101: | * Get the parent entity applied to the context |
102: | * |
103: | * @return (TEntity&Treeable)|null |
104: | */ |
105: | public function getParent(): ?Treeable; |
106: | |
107: | /** |
108: | * Get a value previously applied to the context |
109: | * |
110: | * Returns `null` if no value for `$name` has been applied to the context. |
111: | * |
112: | * @return (int|string|float|bool|null)[]|int|string|float|bool|null |
113: | */ |
114: | public function getValue(string $name); |
115: | |
116: | /** |
117: | * True if a value was previously applied to the context |
118: | */ |
119: | public function hasValue(string $name): bool; |
120: | |
121: | /** |
122: | * Get the current payload's array key conformity |
123: | * |
124: | * @return ListConformity::* |
125: | */ |
126: | public function getConformity(); |
127: | } |
128: |