Add PersonProviderInterface documentation

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'
+```

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;
 
     /**