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