Add typed accessors for story and workflow stage data

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.5 - 2026-04-08
+- Adding `contentType()` accessor to `StoryCollectionItem` for retrieving the root component name in list responses
+- Adding `hasUnpublishedChanges()` accessor to stories for checking draft changes status
+- Adding `workflowStageId()` accessor to stories for retrieving the workflow stage ID (returns `null` when not set)
+- Adding `color()` and `workflowId()` accessors to `WorkflowStageData`
+- Fixing `updatedAt()` signature to accept a `$format` parameter, consistent with `publishedAt()`, `createdAt()`, and `firstPublishedAt()`
+
 ## 1.1.4 - 2026-03-23
 - Adding `StoryApi::versions()` endpoint for listing story versions with pagination
 - Fixing asset upload folder assignment: using `asset_folder_id` instead of `parent_id`

README.md

@@ -369,6 +369,25 @@ foreach ($stories as $story) {
 }
 ```
 
+Each story item exposes typed accessors for commonly used fields:
+
+```php
+foreach ($stories as $story) {
+    echo $story->contentType() . PHP_EOL;       // e.g. "article-page"
+    echo $story->updatedAt() . PHP_EOL;          // e.g. "2024-02-08"
+    echo $story->updatedAt("Y-m-d H:i:s") . PHP_EOL; // e.g. "2024-02-08 16:27:10"
+
+    if ($story->hasUnpublishedChanges()) {
+        echo "This story has unpublished draft changes" . PHP_EOL;
+    }
+
+    $stageId = $story->workflowStageId();        // int or null
+    if ($stageId !== null) {
+        echo "Workflow stage ID: " . $stageId . PHP_EOL;
+    }
+}
+```
+
 In the case you need to retrieve the response to access to some additional information you can obtain a `StoriesResponse` via the `page()` method:
 
 ```php
@@ -1237,6 +1256,8 @@ $workflowStages = $response->data();
 foreach ($workflowStages as $key => $workflowStage) {
     echo "Workflow Stage: " . $workflowStage->name() . " - ";
     echo $workflowStage->id() . PHP_EOL;
+    echo "Color: " . $workflowStage->color() . PHP_EOL;       // e.g. "#2db47d"
+    echo "Workflow ID: " . $workflowStage->workflowId() . PHP_EOL;
 }
 ```
 ### Creating a new custom workflow stage

src/Data/StoryBaseData.php

@@ -65,9 +65,9 @@ public function publishedAt(string $format = "Y-m-d"): null|string
         return $this->getFormattedDateTime("published_at", "", format: $format);
     }
 
-    public function updatedAt(): null|string
+    public function updatedAt(string $format = "Y-m-d"): null|string
     {
-        return $this->getFormattedDateTime("updated_at", "", format: "Y-m-d");
+        return $this->getFormattedDateTime("updated_at", "", format: $format);
     }
 
     /**
@@ -115,4 +115,16 @@ public function firstPublishedAt(string $format = "Y-m-d"): null|string
     {
         return $this->getFormattedDateTime("first_published_at", "", format: $format);
     }
+
+    public function hasUnpublishedChanges(): bool
+    {
+        return $this->getBoolean("unpublished_changes", false);
+    }
+
+    public function workflowStageId(): ?int
+    {
+        $id = $this->getInt("stage.workflow_stage_id", 0);
+
+        return $id > 0 ? $id : null;
+    }
 }

src/Data/StoryCollectionItem.php

@@ -47,6 +47,11 @@ public static function make(array $data = []): self
         return $storyItem;
     }
 
+    public function contentType(): string
+    {
+        return $this->getString("content_type");
+    }
+
     /**
      * Set tags for Story, from a `Tags` collection
      * @return $this

src/Data/WorkflowStageData.php

@@ -42,4 +42,14 @@ public function id(): string
     {
         return $this->getString('id', "");
     }
+
+    public function color(): string
+    {
+        return $this->getString("color", "");
+    }
+
+    public function workflowId(): string
+    {
+        return $this->getString("workflow_id", "");
+    }
 }

tests/Feature/StoryApiTest.php

@@ -35,7 +35,6 @@ public function testOneStoryStoryData(): void
         $storyApi = new StoryApi($mapiClient, "222");
 
         $storyblokResponse = $storyApi->get("111");
-        /** @var Story $storyblokData */
         $storyblokData = $storyblokResponse->data();
 
         $this->assertSame("My third post", $storyblokData->get("name"));
@@ -112,7 +111,6 @@ public function testCreateStoryEncodesDataCorrectlyAsJson(): void
         $this->assertTrue($response->isOk());
         $this->assertSame(201, $response->getResponseStatusCode());
 
-        /** @var Story $responseData */
         $responseData = $response->data();
         $this->assertSame("Test Story", $responseData->name());
         $this->assertSame("test-story", $responseData->slug());

tests/Unit/StoryBaseDataTest.php

@@ -95,6 +95,7 @@ public function testUpdatedAtOnStory(): void
     {
         $story = $this->makeStory();
         $this->assertSame("2024-02-08", $story->updatedAt());
+        $this->assertSame("2024-02-08 16:27:10", $story->updatedAt("Y-m-d H:i:s"));
     }
 
     public function testUpdatedAtOnStoryCollectionItem(): void
@@ -224,4 +225,66 @@ public function testNameOnStoryCollectionItem(): void
         $item = $this->makeStoryCollectionItem();
         $this->assertSame("My third post", $item->name());
     }
+
+    public function testHasUnpublishedChangesOnStory(): void
+    {
+        $story = $this->makeStory();
+        $this->assertFalse($story->hasUnpublishedChanges());
+    }
+
+    public function testHasUnpublishedChangesTrue(): void
+    {
+        $item = StoryCollectionItem::make([
+            "name" => "Draft story",
+            "slug" => "draft-story",
+            "unpublished_changes" => true,
+        ]);
+        $this->assertTrue($item->hasUnpublishedChanges());
+    }
+
+    public function testHasUnpublishedChangesDefault(): void
+    {
+        $item = $this->makeStoryCollectionItem();
+        $this->assertFalse($item->hasUnpublishedChanges());
+    }
+
+    public function testWorkflowStageIdOnStory(): void
+    {
+        $story = $this->makeStory();
+        $this->assertNull($story->workflowStageId());
+    }
+
+    public function testWorkflowStageIdWithValue(): void
+    {
+        $item = StoryCollectionItem::make([
+            "name" => "Reviewed story",
+            "slug" => "reviewed-story",
+            "stage" => [
+                "workflow_stage_id" => 653554,
+            ],
+        ]);
+        $this->assertSame(653554, $item->workflowStageId());
+    }
+
+    public function testWorkflowStageIdDefault(): void
+    {
+        $item = $this->makeStoryCollectionItem();
+        $this->assertNull($item->workflowStageId());
+    }
+
+    public function testContentTypeWithValue(): void
+    {
+        $item = StoryCollectionItem::make([
+            "name" => "Article story",
+            "slug" => "article-story",
+            "content_type" => "page",
+        ]);
+        $this->assertSame("page", $item->contentType());
+    }
+
+    public function testContentTypeDefault(): void
+    {
+        $item = $this->makeStoryCollectionItem();
+        $this->assertSame("", $item->contentType());
+    }
 }

tests/Unit/WorkflowStageDataTest.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit;
+
+use Storyblok\ManagementApi\Data\WorkflowStageData;
+use Tests\TestCase;
+
+final class WorkflowStageDataTest extends TestCase
+{
+    private function makeWorkflowStage(): WorkflowStageData
+    {
+        $contentString = $this->mockData("one-workflow-stage");
+        /** @var array<string, array<mixed>> $content */
+        $content = json_decode($contentString, true);
+
+        return WorkflowStageData::makeFromResponse($content);
+    }
+
+    public function testColorWithValue(): void
+    {
+        $stage = $this->makeWorkflowStage();
+        $this->assertSame("#babcb6", $stage->color());
+    }
+
+    public function testColorDefault(): void
+    {
+        $stage = WorkflowStageData::make([]);
+        $this->assertSame("", $stage->color());
+    }
+
+    public function testWorkflowIdWithValue(): void
+    {
+        $stage = $this->makeWorkflowStage();
+        $this->assertSame("93606", $stage->workflowId());
+    }
+
+    public function testWorkflowIdDefault(): void
+    {
+        $stage = WorkflowStageData::make([]);
+        $this->assertSame("", $stage->workflowId());
+    }
+}