From 6b9b080c198bd9d63c20f0c6c91d06aac8fa08fd Mon Sep 17 00:00:00 2001 From: Patrizio Bekerle <patrizio@bekerle.com> Date: Thu, 21 Oct 2021 10:44:14 +0200 Subject: [PATCH] Add PersonProviderInterface documentation --- README.md | 85 +++++++++++++++++++++++++++++ src/API/PersonProviderInterface.php | 8 +++ 2 files changed, 93 insertions(+) diff --git a/README.md b/README.md index 7c66e41..57f5fd1 100644 --- a/README.md +++ b/README.md @@ -23,3 +23,88 @@ Dbp\Relay\CoreBundle\DbpRelayCoreBundle => ['all' => true], * Run `composer install` to clear caches +## PersonProvider service + +For this bundle to work you need to create a service that implements +[PersonProviderInterface](https://gitlab.tugraz.at/dbp/relay/dbp-relay-base-bundle/-/blob/main/src/API/PersonProviderInterface.php) +in your application. + +### Example + +#### Service class + +You can for example put below code into `src/Service/PersonProvider.php`: + +```php +<?php + +declare(strict_types=1); + +namespace YourUniversity\Service; + +use Dbp\Relay\BaseBundle\API\PersonProviderInterface; +use Dbp\Relay\BaseBundle\Entity\Person; +use Symfony\Component\HttpKernel\Exception\BadRequestHttpException; + +class PersonProvider implements PersonProviderInterface +{ + /** + * @param array $filters $filters['search'] can be a string to search for people (e.g. part of the name) + * @return Person[] + */ + public function getPersons(array $filters): array + { + $people = some_method_to_fetch_persons($filters); + + return $people; + } + + public function getPersonsByNameAndBirthDate(string $givenName, string $familyName, string $birthDate): array + { + $people = some_method_to_fetch_persons_by_name_and_birthday($givenName, $familyName, $birthDate); + + return $people; + } + + public function getPerson(string $id): Person + { + return some_method_to_fetch_person_by_id($id); + } + + /** + * This is only used by external services (e.g. the alma bundle) to translate external persons to internal persons + * + * @param string $service identifies the service that wants to fetch a person + * @param string $serviceID identifies person by an external id + * @return Person + */ + public function getPersonForExternalService(string $service, string $serviceID): Person + { + switch($service) { + case "some-service": + return some_method_to_fetch_person_from_external_service($serviceID); + break; + default: + throw new BadRequestHttpException("Unknown service: $service"); + } + } + + /** + * Returns the Person matching the current user. Or null if there is no associated person + * like when the client is another server. + */ + public function getCurrentPerson(): ?Person + { + return some_method_to_fetch_current_person(); + } +} +``` + +#### Services configuration + +For above class you need to add this to your `src/Resources/config/services.yaml`: + +```yaml + Dbp\Relay\BaseBundle\API\PersonProviderInterface: + '@YourUniversity\Service\PersonProvider' +``` diff --git a/src/API/PersonProviderInterface.php b/src/API/PersonProviderInterface.php index 12b1f91..f1da3af 100644 --- a/src/API/PersonProviderInterface.php +++ b/src/API/PersonProviderInterface.php @@ -9,6 +9,7 @@ use Dbp\Relay\BaseBundle\Entity\Person; interface PersonProviderInterface { /** + * @param array $filters $filters['search'] can be a string to search for people (e.g. part of the name) * @return Person[] */ public function getPersons(array $filters): array; @@ -20,6 +21,13 @@ interface PersonProviderInterface public function getPerson(string $id): Person; + /** + * This is only used by external services (e.g. the alma bundle) to translate external persons to internal persons + * + * @param string $service identifies the service that wants to fetch a person + * @param string $serviceID identifies person by an external id + * @return Person + */ public function getPersonForExternalService(string $service, string $serviceID): Person; /** -- GitLab