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: | use Stringable; |
8: | |
9: | /** |
10: | * Services objects on behalf of a backend |
11: | * |
12: | * @template TContext of ProviderContextInterface |
13: | */ |
14: | interface ProviderInterface extends HasContainer, HasName |
15: | { |
16: | /** |
17: | * Get the name of the provider |
18: | * |
19: | * Appropriate values to return are: |
20: | * |
21: | * - already in scope (no lookup or transformation required) |
22: | * - likely to be unique |
23: | * - human-readable |
24: | */ |
25: | public function getName(): string; |
26: | |
27: | /** |
28: | * Get a stable list of values that, together with its class name, uniquely |
29: | * identifies the provider's backend instance |
30: | * |
31: | * This method must be idempotent for each backend instance the provider |
32: | * connects to. The return value should correspond to the smallest possible |
33: | * set of stable metadata that uniquely identifies the specific data source |
34: | * backing the connected instance. |
35: | * |
36: | * This may include: |
37: | * |
38: | * - an endpoint URI (if backend instances are URI-specific or can be |
39: | * expressed as an immutable URI) |
40: | * - a tenant ID |
41: | * - an installation GUID |
42: | * |
43: | * It should not include: |
44: | * |
45: | * - usernames, API keys, tokens, or other identifiers with a shorter |
46: | * lifespan than the data source itself |
47: | * - values that aren't unique to the connected data source |
48: | * - case-insensitive values (unless normalised first) |
49: | * |
50: | * It must not include: |
51: | * |
52: | * - values retrieved from a provider at runtime |
53: | * |
54: | * @return array<int|float|string|bool|Stringable|null> |
55: | */ |
56: | public function getBackendIdentifier(): array; |
57: | |
58: | /** |
59: | * Get a date formatter to work with the backend's date and time format |
60: | * and/or timezone |
61: | */ |
62: | public function getDateFormatter(): DateFormatterInterface; |
63: | |
64: | /** |
65: | * Get a context within which to instantiate entities on the provider's |
66: | * behalf |
67: | * |
68: | * @return TContext |
69: | */ |
70: | public function getContext(?ContainerInterface $container = null): ProviderContextInterface; |
71: | |
72: | /** |
73: | * Throw an exception if the backend isn't reachable |
74: | * |
75: | * Positive results should be cached for `$ttl` seconds. Negative results |
76: | * must never be cached. |
77: | * |
78: | * @return $this |
79: | * @throws MethodNotImplementedExceptionInterface if heartbeat monitoring |
80: | * isn't supported. |
81: | */ |
82: | public function checkHeartbeat(int $ttl = 300); |
83: | } |
84: |