| 1: | <?php declare(strict_types=1); |
| 2: | |
| 3: | namespace Salient\Contract\Sync; |
| 4: | |
| 5: | use Salient\Contract\Container\ContainerInterface; |
| 6: | use Salient\Contract\Core\HasId; |
| 7: | use Salient\Contract\Core\HasName; |
| 8: | use Salient\Contract\Core\ProvidableEntityInterface; |
| 9: | use Salient\Contract\Core\Relatable; |
| 10: | use Salient\Contract\Sync\Exception\SyncEntityNotFoundExceptionInterface; |
| 11: | use Salient\Contract\Sync\SyncEntityLinkType as LinkType; |
| 12: | use JsonSerializable; |
| 13: | |
| 14: | /** |
| 15: | * Represents the state of an entity in an external system |
| 16: | * |
| 17: | * @extends ProvidableEntityInterface<SyncProviderInterface,SyncContextInterface> |
| 18: | */ |
| 19: | interface SyncEntityInterface extends |
| 20: | HasId, |
| 21: | HasName, |
| 22: | ProvidableEntityInterface, |
| 23: | Relatable, |
| 24: | JsonSerializable |
| 25: | { |
| 26: | /** |
| 27: | * Get the entity's default provider |
| 28: | */ |
| 29: | public static function getDefaultProvider(ContainerInterface $container): SyncProviderInterface; |
| 30: | |
| 31: | /** |
| 32: | * Perform sync operations on the entity using its default provider |
| 33: | * |
| 34: | * @return SyncEntityProviderInterface<static> |
| 35: | */ |
| 36: | public static function withDefaultProvider(ContainerInterface $container, ?SyncContextInterface $context = null): SyncEntityProviderInterface; |
| 37: | |
| 38: | /** |
| 39: | * Get the entity's serialization rules |
| 40: | * |
| 41: | * @return SyncSerializeRulesInterface<static> |
| 42: | */ |
| 43: | public static function getSerializeRules(): SyncSerializeRulesInterface; |
| 44: | |
| 45: | /** |
| 46: | * Get the plural form of the entity's unqualified name |
| 47: | * |
| 48: | * If this method returns a value other than `null`, an empty string, or the |
| 49: | * unqualified name of the entity, it may be used to identify provider |
| 50: | * methods that implement sync operations on the entity. |
| 51: | * |
| 52: | * For example, if `Faculty::getPlural()` returns `null`, a provider may |
| 53: | * implement `Faculty` sync operations via one or more of the following: |
| 54: | * |
| 55: | * - `create_faculty()` |
| 56: | * - `get_faculty()` |
| 57: | * - `update_faculty()` |
| 58: | * - `delete_faculty()` |
| 59: | * - `createList_faculty()` |
| 60: | * - `getList_faculty()` |
| 61: | * - `updateList_faculty()` |
| 62: | * - `deleteList_faculty()` |
| 63: | * |
| 64: | * If the same method returns `"Faculties"`, these are also recognised as |
| 65: | * `Faculty` sync implementations: |
| 66: | * |
| 67: | * - `createFaculty()` |
| 68: | * - `getFaculty()` |
| 69: | * - `updateFaculty()` |
| 70: | * - `deleteFaculty()` |
| 71: | * - `createFaculties()` |
| 72: | * - `getFaculties()` |
| 73: | * - `updateFaculties()` |
| 74: | * - `deleteFaculties()` |
| 75: | */ |
| 76: | public static function getPlural(): ?string; |
| 77: | |
| 78: | /** |
| 79: | * Get the unique identifier assigned to the entity by its provider |
| 80: | */ |
| 81: | public function getId(); |
| 82: | |
| 83: | /** |
| 84: | * Get the unique identifier assigned to the entity by its canonical backend |
| 85: | * |
| 86: | * If a provider is bound to the service container as the default |
| 87: | * implementation of the entity's underlying provider interface, it is |
| 88: | * regarded as its canonical backend. |
| 89: | * |
| 90: | * To improve the accuracy and performance of sync operations, providers |
| 91: | * should propagate this value to and from backends capable of storing it. |
| 92: | * |
| 93: | * @return int|string|null |
| 94: | */ |
| 95: | public function getCanonicalId(); |
| 96: | |
| 97: | /** |
| 98: | * Get the name of the entity |
| 99: | */ |
| 100: | public function getName(): string; |
| 101: | |
| 102: | /** |
| 103: | * Resolve a name or entity ID to the entity ID of one matching entity |
| 104: | * |
| 105: | * Returns: |
| 106: | * |
| 107: | * - `null` if `$nameOrId` is `null` |
| 108: | * - `$nameOrId` if it is a valid identifier for the entity in the given |
| 109: | * provider (see {@see SyncProviderInterface::isValidIdentifier()}), or |
| 110: | * - the entity ID of the entity to which `$nameOrId` resolves |
| 111: | * |
| 112: | * A {@see SyncEntityNotFoundExceptionInterface} is thrown if: |
| 113: | * |
| 114: | * - there are no matching entities, or |
| 115: | * - there are multiple matching entities |
| 116: | * |
| 117: | * @param int|string|null $nameOrId |
| 118: | * @param SyncProviderInterface|SyncContextInterface $providerOrContext |
| 119: | * @return int|string|null |
| 120: | */ |
| 121: | public static function idFromNameOrId( |
| 122: | $nameOrId, |
| 123: | $providerOrContext, |
| 124: | ?float $uncertaintyThreshold = null, |
| 125: | ?string $nameProperty = null, |
| 126: | ?float &$uncertainty = null |
| 127: | ); |
| 128: | |
| 129: | /** |
| 130: | * Serialize the entity and any nested entities |
| 131: | * |
| 132: | * Rules returned by {@see SyncEntityInterface::getSerializeRules()} are |
| 133: | * used. |
| 134: | * |
| 135: | * @return array<string,mixed> |
| 136: | */ |
| 137: | public function toArray(?SyncStoreInterface $store = null): array; |
| 138: | |
| 139: | /** |
| 140: | * Use the given serialization rules to serialize the entity and any nested |
| 141: | * entities |
| 142: | * |
| 143: | * @param SyncSerializeRulesInterface<static> $rules |
| 144: | * @return array<string,mixed> |
| 145: | */ |
| 146: | public function toArrayWith(SyncSerializeRulesInterface $rules, ?SyncStoreInterface $store = null): array; |
| 147: | |
| 148: | /** |
| 149: | * Get the entity's canonical location in the form of an array |
| 150: | * |
| 151: | * Inspired by JSON-LD. |
| 152: | * |
| 153: | * @param LinkType::* $type |
| 154: | * @return array<string,int|string> |
| 155: | */ |
| 156: | public function toLink(?SyncStoreInterface $store = null, int $type = LinkType::DEFAULT, bool $compact = true): array; |
| 157: | |
| 158: | /** |
| 159: | * Get the entity's canonical location in the form of a URI |
| 160: | * |
| 161: | * Inspired by OData. |
| 162: | */ |
| 163: | public function getUri(?SyncStoreInterface $store = null, bool $compact = true): string; |
| 164: | } |
| 165: |