README.md

 # DbpRelayBasePersonBundle
 
 [GitLab](https://gitlab.tugraz.at/dbp/relay/dbp-relay-base-person-bundle) | [Packagist](https://packagist.org/packages/dbp/relay-base-person-bundle)
+
+
+## Integration into the Relay API Server
+
+* Add the bundle package as a dependency:
+
+```
+composer require dbp/relay-base-person-bundle
+```
+
+* Add the bundle to your `config/bundles.php` in front of `DbpRelayCoreBundle`:
+
+```php
+...
+Dbp\Relay\BasePersonBundle\DbpRelayBasePersonBundle::class => ['all' => true],
+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-person-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\BasePersonBundle\API\PersonProviderInterface;
+use Dbp\Relay\BasePersonBundle\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\BasePersonBundle\API\PersonProviderInterface:
+    '@YourUniversity\Service\PersonProvider'
+```

composer.lock

@@ -7536,16 +7536,16 @@
         },
         {
             "name": "vimeo/psalm",
-            "version": "4.10.0",
+            "version": "4.11.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/vimeo/psalm.git",
-                "reference": "916b098b008f6de4543892b1e0651c1c3b92cbfa"
+                "reference": "99e510d6ab1da2d61d4b5eb6314baa797fe0e76d"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/vimeo/psalm/zipball/916b098b008f6de4543892b1e0651c1c3b92cbfa",
-                "reference": "916b098b008f6de4543892b1e0651c1c3b92cbfa",
+                "url": "https://api.github.com/repos/vimeo/psalm/zipball/99e510d6ab1da2d61d4b5eb6314baa797fe0e76d",
+                "reference": "99e510d6ab1da2d61d4b5eb6314baa797fe0e76d",
                 "shasum": ""
             },
             "require": {
@@ -7565,7 +7565,7 @@
                 "felixfbecker/advanced-json-rpc": "^3.0.3",
                 "felixfbecker/language-server-protocol": "^1.5",
                 "netresearch/jsonmapper": "^1.0 || ^2.0 || ^3.0 || ^4.0",
-                "nikic/php-parser": "^4.12",
+                "nikic/php-parser": "^4.13",
                 "openlss/lib-array2xml": "^1.0",
                 "php": "^7.1|^8",
                 "sebastian/diff": "^3.0 || ^4.0",
@@ -7635,9 +7635,9 @@
             ],
             "support": {
                 "issues": "https://github.com/vimeo/psalm/issues",
-                "source": "https://github.com/vimeo/psalm/tree/4.10.0"
+                "source": "https://github.com/vimeo/psalm/tree/4.11.0"
             },
-            "time": "2021-09-04T21:00:09+00:00"
+            "time": "2021-10-23T21:08:14+00:00"
         },
         {
             "name": "webmozart/path-util",

src/Entity/Person.php

@@ -10,7 +10,7 @@ use ApiPlatform\Core\Annotation\ApiResource;
  * @ApiResource(
  *     collectionOperations={
  *         "get" = {
- *             "path" = "/people",
+ *             "path" = "/base/people",
  *             "openapi_context" = {
  *                 "tags" = {"BasePerson"},
  *                 "parameters" = {
@@ -21,7 +21,7 @@ use ApiPlatform\Core\Annotation\ApiResource;
  *     },
  *     itemOperations={
  *         "get" = {
- *             "path" = "/people/{identifier}",
+ *             "path" = "/base/people/{identifier}",
  *             "openapi_context" = {
  *                 "tags" = {"BasePerson"},
  *             }
@@ -29,6 +29,7 @@ use ApiPlatform\Core\Annotation\ApiResource;
  *         },
  *     },
  *     iri="http://schema.org/Person",
+ *     shortName="BasePerson",
  *     description="A person of the LDAP system",
  *     normalizationContext={
  *         "groups" = {"BasePerson:output"},

tests/ExtTest.php

@@ -31,14 +31,14 @@ class ExtTest extends ApiTestCase
     public function testGetPersonNoAuth()
     {
         $client = $this->withUser('foobar', ['foo']);
-        $response = $client->request('GET', '/people/foobar');
+        $response = $client->request('GET', '/base/people/foobar');
         $this->assertEquals(Response::HTTP_UNAUTHORIZED, $response->getStatusCode());
     }
 
     public function testGetPersonWrongAuth()
     {
         $client = $this->withUser('foobar', [], '42');
-        $response = $client->request('GET', '/people/foobar', ['headers' => [
+        $response = $client->request('GET', '/base/people/foobar', ['headers' => [
             'Authorization' => 'Bearer NOT42',
         ]]);
         $this->assertEquals(Response::HTTP_FORBIDDEN, $response->getStatusCode());
@@ -50,12 +50,12 @@ class ExtTest extends ApiTestCase
         $user = $this->getUser($client);
         $person = $this->withPerson($client, $user);
         $person->setEmail('foo@bar.com');
-        $response = $client->request('GET', '/people/foobar', ['headers' => [
+        $response = $client->request('GET', '/base/people/foobar', ['headers' => [
             'Authorization' => 'Bearer 42',
         ]]);
         $this->assertJson($response->getContent(false));
         $data = json_decode($response->getContent(false), true, 512, JSON_THROW_ON_ERROR);
-        $this->assertEquals('/people/foobar', $data['@id']);
+        $this->assertEquals('/base/people/foobar', $data['@id']);
         $this->assertEquals('foobar', $data['identifier']);
         $this->assertEquals('foo@bar.com', $data['email']);
     }
@@ -63,7 +63,7 @@ class ExtTest extends ApiTestCase
     public function testResponseHeaders()
     {
         $client = $this->withUser('foobar', [], '42');
-        $response = $client->request('GET', '/people/foobar', ['headers' => [
+        $response = $client->request('GET', '/base/people/foobar', ['headers' => [
             'Authorization' => 'Bearer 42',
         ]]);
         $header = $response->getHeaders();
@@ -84,7 +84,7 @@ class ExtTest extends ApiTestCase
         $client = $this->withUser('foobar', ['ROLE'], '42');
         $user = $this->getUser($client);
         $this->withPerson($client, $user);
-        $response = $client->request('GET', '/people/foobar', ['headers' => [
+        $response = $client->request('GET', '/base/people/foobar', ['headers' => [
             'Authorization' => 'Bearer 42',
         ]]);
         $data = json_decode($response->getContent(), true, 512, JSON_THROW_ON_ERROR);
@@ -96,8 +96,8 @@ class ExtTest extends ApiTestCase
         $client = self::createClient();
 
         $endpoints = [
-            '/people',
-            '/people/foo',
+            '/base/people',
+            '/base/people/foo',
         ];
         foreach ($endpoints as $path) {
             $response = $client->request('GET', $path);