feat(song-tags): add SongTags #161

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Group-member-fields and DBFields-API ([PR147](https://github.com/5pm-HDH/churchtools-api/issues/147))
 - Pagination Page-Size Option ([PR163](https://github.com/5pm-HDH/churchtools-api/pull/163))
 - DateTime-Getter ([PR167](https://github.com/5pm-HDH/churchtools-api/pull/167))
+- Song-Tags ([PR168](https://github.com/5pm-HDH/churchtools-api/pull/168))
 
 ### Changed
 - Refactor Imports ([PR165](https://github.com/5pm-HDH/churchtools-api/pull/165))

README.md

@@ -77,6 +77,7 @@ All APIs with examples:
 * [File-API](/docs/out/FileAPI.md)
 * [Search-API](/docs/out/SearchAPI.md)
 * [DB-Fields](/docs/out/DBFields.md)
+* [Tags-API](/docs/out/TagsAPI.md)
 
 The following brief examples demonstrate the capabilities of the ChurchTools-API client and provide a general overview
 of its potential uses:

docs/out/GroupAPI.md

@@ -3,6 +3,7 @@
 ## Group-Request & Group-Data:
 
 ```php
+        use CTApi\CTConfig;
         use CTApi\Requests\GroupRequest;
         use CTApi\Requests\PersonRequest;
         use CTApi\Test\Unit\TestCaseHttpMocked;
@@ -250,6 +251,17 @@
         $personGroupMember = $groupMember?->getPerson();
         $personGroupMember = $groupMember?->requestPerson();
 
+        // Retrieve Group-Tags
+        $tags = $group->requestTags()?->get();
+
+        $tag = end($tags);
+        var_dump( $tag->getName());
+        // Output: "Leader"
+
+        var_dump( $tag->getId());
+        // Output: 8
+
+
         /**
          * Upadate Group-Image: See FileAPI
          */

docs/out/SongAPI.md

@@ -134,6 +134,27 @@
         // Output: "https://multitracks.com/path/to/song?id=2912&login_token=notnullapikey"
 
 
+```
+
+## Retrieve tags for song
+
+```php
+        use CTApi\Requests\SongRequest;
+        use CTApi\Requests\TagRequest;
+        use CTApi\Test\Unit\TestCaseHttpMocked;
+
+        $song = SongRequest::findOrFail(21);
+        $tags = $song->requestTags()?->get() ?? [];
+
+        $tagList = "";
+        foreach ($tags as $tag) {
+            $tagList .= $tag->getName() . " (#" . $tag->getId() . "); ";
+        }
+
+        var_dump( $tagList);
+        // Output: "5pm Songpool (#5); Youth Songpool (#11); "
+
+
 ```
 
 ## Update Song

docs/out/TagsAPI.md

@@ -0,0 +1,43 @@
+# Tags-API
+
+## Retrieve all tags
+
+```php
+        use CTApi\Requests\SongRequest;
+        use CTApi\Requests\TagRequest;
+        use CTApi\Test\Unit\TestCaseHttpMocked;
+
+        $personTags = TagRequest::allPersonTags();
+        $songTags = TagRequest::allSongTags();
+
+        $tagList = "";
+        foreach ($songTags as $tag) {
+            $tagList .= $tag->getName() . " (#" . $tag->getId() . "); ";
+        }
+
+        var_dump( $tagList);
+        // Output: "Choral (#2); 5pm Songpool (#5); Deprecated (#8); Youth Songpool (#11); "
+
+
+```
+
+## Retrieve tags for song
+
+```php
+        use CTApi\Requests\SongRequest;
+        use CTApi\Requests\TagRequest;
+        use CTApi\Test\Unit\TestCaseHttpMocked;
+
+        $song = SongRequest::findOrFail(21);
+        $tags = $song->requestTags()?->get() ?? [];
+
+        $tagList = "";
+        foreach ($tags as $tag) {
+            $tagList .= $tag->getName() . " (#" . $tag->getId() . "); ";
+        }
+
+        var_dump( $tagList);
+        // Output: "5pm Songpool (#5); Youth Songpool (#11); "
+
+
+```

docs/src/ressources/SongAPI.md

@@ -4,6 +4,10 @@
 
 {{ \CTApi\Test\Unit\Docs\SongRequestTest.testExampleCode }}
 
+## Retrieve tags for song
+
+{{ \CTApi\Test\Unit\Docs\TagsRequestTest.testRetrieveTagForSong }}
+
 ## Update Song
 
 {{ \CTApi\Test\Unit\Docs\SongRequestTest.testUpdateSong }}

docs/src/ressources/TagsAPI.md

@@ -0,0 +1,9 @@
+# Tags-API
+
+## Retrieve all tags
+
+{{ \CTApi\Test\Unit\Docs\TagsRequestTest.testRetrieveTags }}
+
+## Retrieve tags for song
+
+{{ \CTApi\Test\Unit\Docs\TagsRequestTest.testRetrieveTagForSong }}

src/Models/Group.php

@@ -12,6 +12,7 @@
 use CTApi\Requests\GroupHierarchieParentsRequest;
 use CTApi\Requests\GroupMeetingRequestBuilder;
 use CTApi\Requests\GroupMemberRequestBuilder;
+use CTApi\Requests\GroupTagRequestBuilder;
 
 class Group extends AbstractModel
 {
@@ -114,6 +115,14 @@ public function requestGroupMeetings(): ?GroupMeetingRequestBuilder
         return null;
     }
 
+    public function requestTags(): ?GroupTagRequestBuilder
+    {
+        if (!is_null($this->getId())) {
+            return new GroupTagRequestBuilder($this->getIdAsInteger());
+        }
+        return null;
+    }
+
     /**
      * @param string|null $id
      * @return Group

src/Models/Song.php

@@ -10,6 +10,7 @@
 use CTApi\Models\Traits\MetaAttribute;
 use CTApi\Requests\SongRequest;
 use CTApi\Requests\SongStatisticRequest;
+use CTApi\Requests\SongTagRequestBuilder;
 
 class Song extends AbstractModel implements UpdatableModel
 {
@@ -102,6 +103,14 @@ public function requestSelectedArrangement(): ?SongArrangement
         return $selectedArrangement;
     }
 
+    public function requestTags(): ?SongTagRequestBuilder
+    {
+        if($this->id != null){
+            return new SongTagRequestBuilder($this->getIdAsInteger());
+        }
+        return null;
+    }
+
     /**
      * @param string|null $id
      * @return Song

src/Requests/GroupTagRequestBuilder.php

@@ -0,0 +1,27 @@
+<?php
+
+
+namespace CTApi\Requests;
+
+
+use CTApi\CTClient;
+use CTApi\Models\Tag;
+use CTApi\Utils\CTResponseUtil;
+
+class GroupTagRequestBuilder
+{
+
+    public function __construct(
+        private int $groupId
+    )
+    {
+    }
+
+    public function get(): array
+    {
+        $client = CTClient::getClient();
+        $response = $client->get('/api/groups/'.$this->groupId.'/tags');
+        $data = CTResponseUtil::dataAsArray($response);
+        return Tag::createModelsFromArray($data);
+    }
+}

src/Requests/SongTagRequestBuilder.php

@@ -0,0 +1,56 @@
+<?php
+
+
+namespace CTApi\Requests;
+
+
+use CTApi\Exceptions\CTRequestException;
+use CTApi\Models\SongStatistic;
+use CTApi\Requests\Traits\AjaxApi;
+use CTApi\Utils\CTResponseUtil;
+
+class SongTagRequestBuilder
+{
+    use AjaxApi;
+
+    public function __construct(
+        private int $songId
+    )
+    {
+    }
+
+    public function get(): array
+    {
+        $songData = $this->getTagData();
+        $songId = $this->songId;
+        $filteredSongs = array_filter($songData, function ($song) use ($songId) {
+            return $song["id"] == $songId;
+        });
+        $songElement = end($filteredSongs);
+
+        if ($songElement === false) {
+            return [];
+        }
+
+        $tags = $songElement["tags"] ?? [];
+
+        $tagRequestBuilder = new TagRequestBuilder("songs");
+
+        $tagsAsObjects = array_map(function ($tagId) use ($tagRequestBuilder) {
+            return $tagRequestBuilder->find($tagId);
+        }, $tags);
+        return $tagsAsObjects;
+    }
+
+    private function getTagData(): array
+    {
+        $response = $this->requestAjax("churchservice/ajax", "getAllSongs", []);
+        $data = CTResponseUtil::dataAsArray($response);
+
+        if(array_key_exists("songs", $data)){
+            return $data["songs"];
+        }else{
+            return $data;
+        }
+    }
+}

src/Requests/TagRequest.php

@@ -0,0 +1,40 @@
+<?php
+
+
+namespace CTApi\Requests;
+
+
+use CTApi\Models\Tag;
+
+class TagRequest
+{
+    public static function allPersonTags(): array
+    {
+        return (new TagRequestBuilder("persons"))->all();
+    }
+
+    public static function allSongTags(): array
+    {
+        return (new TagRequestBuilder("songs"))->all();
+    }
+
+    public static function findPersonTag(int $id): ?Tag
+    {
+        return (new TagRequestBuilder("persons"))->find($id);
+    }
+
+    public static function findSongTag(int $id): ?Tag
+    {
+        return (new TagRequestBuilder("songs"))->find($id);
+    }
+
+    public static function findPersonTagOrFail(int $id): Tag
+    {
+        return (new TagRequestBuilder("persons"))->findOrFail($id);
+    }
+
+    public static function findSongTagOrFail(int $id): Tag
+    {
+        return (new TagRequestBuilder("songs"))->findOrFail($id);
+    }
+}

src/Requests/TagRequestBuilder.php

@@ -0,0 +1,62 @@
+<?php
+
+
+namespace CTApi\Requests;
+
+
+use CTApi\CTClient;
+use CTApi\Exceptions\CTModelException;
+use CTApi\Exceptions\CTRequestException;
+use CTApi\Models\Tag;
+use CTApi\Utils\CTResponseUtil;
+
+class TagRequestBuilder
+{
+    private $tags = [];
+
+    public function __construct(
+        private string $type
+    )
+    {
+        $this->tags = $this->retrieveData();
+    }
+
+    private function retrieveData(): array
+    {
+        $client = CTClient::getClient();
+        $response = $client->get("/api/tags", ["query" => ["type" => $this->type]]);
+        $data = CTResponseUtil::dataAsArray($response);
+        return Tag::createModelsFromArray($data);
+    }
+
+    private function filterTag(int $tagId): ?Tag
+    {
+        $filteredTags = array_filter($this->tags, function(Tag $tag) use ($tagId){
+           return $tag->getIdAsInteger() == $tagId;
+        });
+        $foundTag = end($filteredTags);
+        if($foundTag === false){
+            return null;
+        }
+        return $foundTag;
+    }
+
+    public function find(int $id): ?Tag
+    {
+        return $this->filterTag($id);
+    }
+
+    public function findOrFail(int $id): Tag
+    {
+        $tag = $this->find($id);
+        if($tag == null){
+            throw CTRequestException::ofModelNotFound(Tag::class);
+        }
+        return $tag;
+    }
+
+    public function all(): array
+    {
+        return $this->tags;
+    }
+}