Added a flag for forced person creation

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - [Serialize Models to Data-Array for JSON-Export](https://github.com/5pm-HDH/churchtools-api/pull/103)
 - [Retrieve Birthdays](https://github.com/5pm-HDH/churchtools-api/pull/104)
 - [Retrieve Tags of Person](https://github.com/5pm-HDH/churchtools-api/pull/110)
+- [Added force flag to person creation, to add persons with same name](https://github.com/5pm-HDH/churchtools-api/pull/107)
 - [Absence-API](https://github.com/5pm-HDH/churchtools-api/pull/111)
 
 ### Changed

docs/out/PersonAPI.md

@@ -133,6 +133,28 @@
 
 ```
 
+Sometimes it will happen that you have to add a person with the same name
+as an existing one. ChurchTools will respond with an error to prevent you from
+adding duplicates accidently.
+
+Therefore you can add the `force` parameter and set it to `true`.
+
+```php
+        use CTApi\Models\Person;
+        use CTApi\Requests\PersonRequest;
+
+        $newPerson = new Person();
+        $newPerson->setFirstName("John")
+            ->setLastName("Doe")
+            ->setBirthday("1970-01-01");
+        //add further attributes
+
+        PersonRequest::create($newPerson, force: true);
+
+```
+
+This will make ChurchTools to insert the record, even if there is a second John Doe.
+
 ## Update a person's data
 
 Use the setters of the person model to modify its data and utilize the

docs/src/ressources/PersonAPI.md

@@ -14,6 +14,16 @@
 
 {{ \Tests\Unit\Docs\PersonRequestTest.testCreatePerson }}
 
+Sometimes it will happen that you have to add a person with the same name
+as an existing one. ChurchTools will respond with an error to prevent you from
+adding duplicates accidently.
+
+Therefore you can add the `force` parameter and set it to `true`.
+
+{{ \Tests\Unit\Docs\PersonRequestTest.testCreatePersonWithEqualName }}
+
+This will make ChurchTools to insert the record, even if there is a second John Doe.
+
 ## Update a person's data
 
 Use the setters of the person model to modify its data and utilize the

src/Requests/AbstractRequestBuilder.php

@@ -66,8 +66,12 @@ public function get(): array
      * Send Create-Request for given Model.
      *
      * @param UpdatableModel $model Model
+     * @param bool $force
+     *        If the request fails because a duplicate is found (person with same name)
+     *        set the $force param to `true` to create this person even if a
+     *        duplicate is found.
      */
-    protected function createDataForModel(UpdatableModel $model): void
+    protected function createDataForModel(UpdatableModel $model, bool $force = false): void
     {
         $createAttributes = $model->getModifiableAttributes();
 
@@ -80,7 +84,7 @@ protected function createDataForModel(UpdatableModel $model): void
             return !is_null($value);
         });
 
-        $responseData = $this->createData($data);
+        $responseData = $this->createData($data, $force);
 
         // Some data like the ID is created on Churchtools and we have to sync it
         // back to the model.
@@ -100,13 +104,26 @@ protected function createDataForModel(UpdatableModel $model): void
      * Sends the data to the API endpoint to create a new record at ChurchTools.
      * When the action was successfull, the actual data from ChurchTools is returned
      * as an array.
+     *
+     * @param bool $force
+     *        If the request fails because a duplicate is found (person with same name)
+     *        set the $force param to `true` to create this person even if a
+     *        duplicate is found.
      */
-    protected function createData(array $data): array
+    protected function createData(array $data, bool $force = false): array
     {
         $url = $this->getApiEndpoint();
+        $query = [];
+
+        if ($force) {
+            $query['force'] = '1';
+        }
 
         $client = CTClient::getClient();
-        $response = $client->post($url, ['json' => $data]);
+        $response = $client->post($url, [
+            'query' => $query,
+            'json' => $data,
+        ]);
 
         $response->getBody();
         return CTResponseUtil::dataAsArray($response);

src/Requests/PersonRequest.php

@@ -44,10 +44,15 @@ public static function find(int $id): ?Person
 
     /**
      * Add the person to ChurchTools.
+     *
+     * @param bool $force
+     *        If the request fails because a duplicate is found (person with same name)
+     *        set the $force param to `true` to create this person even if a
+     *        duplicate is found.
      */
-    public static function create(Person $person): void
+    public static function create(Person $person, bool $force = false): void
     {
-        (new PersonRequestBuilder())->create($person);
+        (new PersonRequestBuilder())->create($person, $force);
     }
 
     /**

src/Requests/PersonRequestBuilder.php

@@ -34,15 +34,23 @@ public function get(): array
         return Person::createModelsFromArray($data);
     }
 
-
-    public function create(Person $person): void
+    /**
+     * Add the person to ChurchTools.
+     *
+     * @param bool $force
+     *        If the request fails because a duplicate is found (person with same name)
+     *        set the $force param to `true` to create this person even if a
+     *        duplicate is found.
+     * @throws CTModelException If the passed person already has an ID.
+     */
+    public function create(Person $person, bool $force = false): void
     {
         $id = $person->getId();
         if (!is_null($id)) {
             throw new CTModelException("ID of a new Person has to be null.");
         }
 
-        $this->createDataForModel($person);
+        $this->createDataForModel($person, $force);
     }
 
     /**

tests/unit/Docs/PersonRequestTest.php

@@ -56,6 +56,20 @@ public function testCreatePerson()
         PersonRequest::create($newPerson);
     }
 
+    /**
+     * @doesNotPerformAssertions
+     */
+    public function testCreatePersonWithEqualName()
+    {
+        $newPerson = new Person();
+        $newPerson->setFirstName("John")
+            ->setLastName("Doe")
+            ->setBirthday("1970-01-01");
+        //add further attributes
+
+        PersonRequest::create($newPerson, force: true);
+    }
+
     /**
      * @doesNotPerformAssertions
      */