Handling Workflow Stage

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.0.4 - WIP
+
+- Adding WorkflowStage Api class for handling workflow stages
+-
 ## 0.0.3 - 2025-02-03
 
 - Adding helper methods for SpaceData (id(), updatedAt())

README.md

@@ -527,7 +527,7 @@ if ($response->isOk()) {
 
 ## Handling Workflows
 
-If you need to handle workflows (retrieving workflows or create new custome workflow - in the case you have a proper plan - ) you can use the `WorkflowApi` class.
+If you need to handle workflows (retrieving workflows or create new custom workflow - in the case you have a proper plan - ) you can use the `WorkflowApi` class.
 
 ### Retrieving workflows
 
@@ -555,6 +555,43 @@ $workflowData->setName("Name");
 $response = $workflowApi->create($workflowData);
 ```
 
+## Handling Workflow Stage
+
+If you need to handle workflow stages (retrieving workflow stages or create new custom workflow stage - in the case you have a proper plan - ) you can use the `WorkflowStageApi` class.
+
+### Retrieving workflow stages
+
+```php
+$response = $workflowStageApi->list();
+/** @var WorkflowsData $workflows */
+$workflowStages = $response->data();
+foreach ($workflowStages as $key => $workflowStage) {
+    echo "Workflow Stage: " . $workflowStage->name() . " - ";
+    echo $workflowStage->id() . PHP_EOL;
+}
+```
+### Creating a new custom workflow stage
+
+In this example, we are going to retrieve the first workflow id available (probably you should retrieve a proper workflow that makes sense for your use case):
+
+```php
+$workflowApi = $client->workflowApi($spaceId);
+$response = $workflowApi->list();
+$workflowId = $response->data()->get("0.id");
+```
+
+And then create a new workflow stage:
+
+```php
+use Storyblok\ManagementApi\Data\WorkflowStageData;
+
+$workflowStageApi = $client->workflowStageApi($spaceId);
+$workflowStageData = new WorkflowStageData();
+$workflowStageData->setName("Name");
+$workflowStageData->setWorkflowId($workflowId);
+$response = $workflowStageApi->create($workflowStageData);
+```
+
 
 ## Using the `ManagementApi` class
 

src/Data/WorkflowStageData.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Data;
+
+use Storyblok\ManagementApi\Data\StoryblokData;
+use Storyblok\ManagementApi\StoryblokUtils;
+
+class WorkflowStageData extends StoryblokData
+{
+    /**
+     * @param array<string, array<mixed>> $data
+     */
+    public static function makeFromResponse(array $data = []): self
+    {
+        return new self($data["workflow_stage"] ?? []);
+    }
+
+    #[\Override]
+    public static function make(array $data = []): self
+    {
+        return new self($data);
+    }
+
+    public function setName(string $name): void
+    {
+        $this->set('name', $name);
+    }
+
+    public function setWorkflowId(string|int $workflowId): void
+    {
+        $this->set('workflow_id', $workflowId);
+    }
+
+
+
+
+
+    public function name(): string
+    {
+        return $this->getString('name', "");
+    }
+
+    public function id(): string
+    {
+        return $this->getString('id', "");
+    }
+
+
+
+}

src/Data/WorkflowStagesData.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Data;
+
+class WorkflowStagesData extends StoryblokData
+{
+    #[\Override]
+    public function getDataClass(): string
+    {
+        return WorkflowStageData::class;
+    }
+
+    #[\Override]
+    public static function make(array $data = []): self
+    {
+        return new self($data);
+    }
+
+    /**
+     * @param array<string, array<mixed>> $data
+     */
+    public static function makeFromResponse(array $data = []): self
+    {
+        return new self($data["workflow_stages"] ?? []);
+    }
+
+
+    public function howManyWorkflowStages(): int
+    {
+        return $this->count();
+    }
+
+}

src/Endpoints/WorkflowStageApi.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Endpoints;
+
+use Storyblok\ManagementApi\Data\StoryblokData;
+use Storyblok\ManagementApi\Data\WorkflowStageData;
+use Storyblok\ManagementApi\Data\WorkflowStagesData;
+use Storyblok\ManagementApi\QueryParameters\WorkflowStagesParams;
+use Storyblok\ManagementApi\StoryblokResponseInterface;
+
+/**
+ *
+ */
+class WorkflowStageApi extends EndpointSpace
+{
+    /**
+     * @param string|string[]|null $byIds
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
+    public function list(
+        string|int|null $inWorkflowId = null,
+        string|null $search = null,
+        string|array|null $byIds = null,
+        string|null $excludeId = null,
+    ): StoryblokResponseInterface {
+        $options = [];
+        $params = new WorkflowStagesParams(
+            $inWorkflowId,
+            $search,
+            $byIds,
+            $excludeId,
+        );
+
+        $options = [
+            'query' => $params->toArray(),
+        ];
+
+        return $this->makeRequest(
+            "GET",
+            '/v1/spaces/' . $this->spaceId . '/workflow_stages',
+            options: $options,
+            dataClass: WorkflowStagesData::class,
+        );
+    }
+
+    public function get(string|int $workflowStageId): StoryblokResponseInterface
+    {
+
+        return $this->makeRequest(
+            "GET",
+            '/v1/spaces/' . $this->spaceId . '/workflow_stages/' . $workflowStageId,
+            dataClass: WorkflowStageData::class,
+        );
+    }
+
+
+    /**
+     * @param string|int $workflowStageId the workflow stage identifier
+     */
+    public function delete(string|int $workflowStageId): StoryblokResponseInterface
+    {
+        return $this->makeRequest(
+            "DELETE",
+            '/v1/spaces/' . $this->spaceId . '/workflow_stages/' . $workflowStageId,
+        );
+    }
+
+    public function create(StoryblokData $storyblokData): StoryblokResponseInterface
+    {
+        return $this->makeRequest(
+            "POST",
+            "/v1/spaces/" . $this->spaceId . '/workflow_stages',
+            [
+                "body" => [
+                    "workflow_stage" => $storyblokData->toArray(),
+                ],
+            ],
+            dataClass: WorkflowStageData::class,
+        );
+    }
+
+    public function update(string|int $workflowStageId, StoryblokData $storyblokData): StoryblokResponseInterface
+    {
+        return $this->makeRequest(
+            "POST",
+            "/v1/spaces/" . $this->spaceId . '/workflow_stages/' . $workflowStageId,
+            [
+                "body" => $storyblokData->toArray(),
+            ],
+            dataClass: WorkflowStageData::class,
+        );
+    }
+
+
+
+
+
+}

src/ManagementApiClient.php

@@ -12,6 +12,7 @@
 use Storyblok\ManagementApi\Endpoints\TagApi;
 use Storyblok\ManagementApi\Endpoints\UserApi;
 use Storyblok\ManagementApi\Endpoints\WorkflowApi;
+use Storyblok\ManagementApi\Endpoints\WorkflowStageApi;
 use Symfony\Component\HttpClient\HttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Psr\Log\LoggerInterface;
@@ -105,6 +106,11 @@ public function workflowApi(string|int $spaceId): WorkflowApi
         return new WorkflowApi($this->httpClient, $spaceId);
     }
 
+    public function workflowStageApi(string|int $spaceId): WorkflowStageApi
+    {
+        return new WorkflowStageApi($this->httpClient, $spaceId);
+    }
+
     public function managementApi(): ManagementApi
     {
         return new ManagementApi($this->httpClient);

src/QueryParameters/WorkflowStagesParams.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\QueryParameters;
+
+use Storyblok\ManagementApi\QueryParameters\Type\SortBy;
+
+class WorkflowStagesParams
+{
+    /**
+     * @param string|string[]|null $byIds
+     */
+    public function __construct(
+        private readonly string|int|null $inWorkflowId = null,
+        private readonly string|null $search = null,
+        private readonly string|array|null $byIds = null,
+        private readonly string|null $excludeId = null,
+    ) {}
+
+    /**
+     * @return array<mixed>
+     */
+    public function toArray(): array
+    {
+        $array = [];
+        if (null !== $this->inWorkflowId) {
+            $array['in_workflow'] = $this->inWorkflowId;
+        }
+
+        if (null !== $this->search) {
+            $array['search'] = $this->search;
+        }
+
+        if (null !== $this->excludeId) {
+            $array['exclude_id'] = $this->excludeId;
+        }
+
+
+
+        if (null !== $this->byIds) {
+            if (is_array($this->byIds)) {
+                $array['by_ids'] = implode(",", $this->byIds);
+            }
+
+            if (is_string($this->byIds)) {
+                $array['by_ids'] = $this->byIds;
+            }
+        }
+
+        return $array;
+    }
+}

tests/Feature/Data/list-workflow-stages.json

@@ -0,0 +1,15 @@
+{
+    "workflow_stages": [
+        {
+            "allow_publish":false,
+            "is_default":false,
+            "id":653554,"user_ids":[],"space_role_ids":[],"workflow_stage_ids":[653555],"name":"Drafting","color":"#babcb6","allow_all_stages":false,"allow_admin_publish":false,"allow_all_users":true,"allow_admin_change":false,"allow_editor_change":false,"position":1,"after_publish_id":null,"workflow_id":93606,"story_editing_locked":false,"allow_none_for_next_stages":false,"auto_remove_assignee":false,"_new":false,"_destroy":false
+        }
+,
+        {
+            "allow_publish":false,
+            "is_default":false,
+            "id":653555,"user_ids":[],"space_role_ids":[],"workflow_stage_ids":[653556],"name":"Review","color":"#babcb6","allow_all_stages":false,"allow_admin_publish":false,"allow_all_users":true,"allow_admin_change":false,"allow_editor_change":false,"position":1,"after_publish_id":null,"workflow_id":93606,"story_editing_locked":false,"allow_none_for_next_stages":false,"auto_remove_assignee":false,"_new":false,"_destroy":false
+        }
+    ]
+}

tests/Feature/Data/one-workflow-stage.json

@@ -0,0 +1,7 @@
+{
+    "workflow_stage":{
+        "allow_publish":false,
+        "is_default":false,
+        "id":653554,"user_ids":[],"space_role_ids":[],"workflow_stage_ids":[653555],"name":"Draftin","color":"#babcb6","allow_all_stages":false,"allow_admin_publish":false,"allow_all_users":true,"allow_admin_change":false,"allow_editor_change":false,"position":1,"after_publish_id":null,"workflow_id":93606,"story_editing_locked":false,"allow_none_for_next_stages":false,"auto_remove_assignee":false,"_new":false,"_destroy":false}
+}
+

tests/Feature/WorkflowStageTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+
+use Storyblok\ManagementApi\ManagementApiClient;
+use Symfony\Component\HttpClient\MockHttpClient;
+
+test('Testing list of workflow stages', function (): void {
+    $responses = [
+        \mockResponse("list-workflow-stages", 200, []),
+        \mockResponse("list-workflow-stages", 200,[]),
+        //\mockResponse("empty-asset", 404),
+    ];
+
+    $client = new MockHttpClient($responses);
+    $mapiClient = ManagementApiClient::initTest($client);
+    $workflowStageApi = $mapiClient->workflowStageApi("222");
+
+    $storyblokResponse = $workflowStageApi->list(
+        inWorkflowId: "12345"
+    );
+    $string = $storyblokResponse->getLastCalledUrl();
+    expect($string)->toMatch('/.*in_workflow=12345.*$/');
+
+    $storyblokResponse = $workflowStageApi->list(
+        byIds: [ "12345", "54321" ]
+    );
+    $string = $storyblokResponse->getLastCalledUrl();
+    expect($string)->toMatch('/.*by_ids=12345%2C54321.*$/');
+
+});