Adding parameters for updating a story (#31)

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.0.11 - 2026-01-05
+- Adding parameters for updating a story
+
 ## 1.0.10 - 2025-12-12
 - Introduce `shouldRetry` flag for automatic 429 retry handling
 

README.md

@@ -509,6 +509,89 @@ For publishing a story by the story identifier you can use the `publish` method:
 $storyApi->publish($storyId);
 ```
 
+### Update a Story
+
+Updates an existing story using the Storyblok Management API.
+
+#### Method Signature
+
+```php
+$storyApi->update(
+    string $storyId,
+    Story $storyData,
+    string $groupId = "",
+    string $forceUpdate = "",
+    int $releaseId = 0,
+    bool $publish = false,
+    string $lang = ""
+): StoryResponse
+```
+
+#### Parameters
+
+- **`storyId`** (`string`)
+  The ID of the story to update.
+
+- **`storyData`** (`Story`)
+  The Story object containing updated content and metadata.
+
+- **`groupId`** (`string`, optional)
+  Group ID (UUID string) shared between stories defined as alternates.
+
+- **`forceUpdate`** (`string`, optional)
+  Set to `"1"` to force an update of a locked story.
+  A story is locked when another user edits it. Forcing an update may cause content conflicts and has no effect if the story is locked due to a workflow stage.
+
+- **`releaseId`** (`int`, optional)
+  Numeric ID of the release in which the story should be updated.
+
+- **`publish`** (`bool`, optional)
+  Set to `true` to publish the story immediately after updating it.
+
+- **`lang`** (`string`, optional)
+  Language code to update or publish the story individually.
+  The language must be enabled in **Settings → Internationalization**.                           |
+
+#### Examples
+
+Update a story:
+
+```php
+$storyApi->update(
+    storyId: '123456',
+    storyData: $story
+);
+```
+
+Update and publish immediately:
+
+```php
+$storyApi->update(
+    storyId: '123456',
+    storyData: $story,
+    publish: true
+);
+```
+
+Update a specific language:
+
+```php
+$storyApi->update(
+    storyId: '123456',
+    storyData: $story,
+    lang: 'de'
+);
+```
+
+Force update a locked story:
+
+```php
+$storyApi->update(
+    storyId: '123456',
+    storyData: $story,
+    forceUpdate: '1'
+);
+```
 
 ### Creating stories from large CSV files (streamed, memory-efficient)
 When importing stories from a CSV file, especially very large ones, one of the approaches is to stream the CSV file using generators and create stories one by one using the Management API client. This keeps memory usage low and allows the client’s built-in retry logic to gracefully handle potential 429 Too Many Requests responses, which can occur multiple times when processing large CSV files.

src/Data/BaseData.php

@@ -157,7 +157,12 @@ public function set(
                 $array = &$array[$key];
             }
 
-            $array[array_shift($keys)] = $value;
+            $key = array_shift($keys);
+
+            if (!is_null($key)) {
+                $array[$key] = $value;
+            }
+
             return $this;
         }
 

src/Endpoints/StoryApi.php

@@ -133,20 +133,77 @@ public function create(
     }
 
     /**
-     * Updates an existing story
+     * Updates an existing story.
+     *
+     * @param string $storyId
+     *   The ID of the story to update.
+     *
+     * @param Story $storyData
+     *   The Story object containing the updated content and metadata.
+     *
+     * @param string $groupId
+     *   Optional. Group ID (UUID string) shared between stories defined as alternates.
+     *
+     * @param string $forceUpdate
+     *   Optional. Set to "1" to force an update of a locked story.
+     *   A story is locked when another user edits it. Forcing an update may cause
+     *   a content conflict. This parameter has no effect if the story is locked
+     *   due to a workflow stage.
+     *
+     * @param int $releaseId
+     *   Optional. Numeric ID of the release in which the story should be updated.
+     *
+     * @param bool $publish
+     *   Optional. Set to true to publish the story immediately after updating it.
+     *
+     * @param string $lang
+     *   Optional. Language code to update or publish the story individually.
+     *   The language must be enabled in Settings → Internationalization.
+     *
+     * @return StoryResponse
+     *   The response containing the updated story data.
      *
      * @throws InvalidStoryDataException
+     *   Thrown when the provided story data is invalid.
      */
-    public function update(string $storyId, Story $storyData): StoryResponse
-    {
+    public function update(
+        string $storyId,
+        Story $storyData,
+        string $groupId = "",
+        string $forceUpdate = "",
+        int $releaseId = 0,
+        bool $publish = false,
+        string $lang = "",
+    ): StoryResponse {
         $this->validateStoryId($storyId);
         //$this->validateStoryData($storyData);
+        $payload = ["story" => $storyData->toArray()];
+
+        if ($groupId !== "") {
+            $payload["group_id"] = $groupId;
+        }
+
+        if ($forceUpdate !== "") {
+            $payload["force_update"] = $forceUpdate;
+        }
+
+        if ($releaseId > 0) {
+            $payload["release_id"] = $releaseId;
+        }
+
+        if ($publish) {
+            $payload["publish"] = 1;
+        }
+
+        if ($lang !== "") {
+            $payload["lang"] = $lang;
+        }
 
         $httpResponse = $this->makeHttpRequest(
             "PUT",
             $this->buildStoryEndpoint($storyId),
             [
-                "body" => json_encode(["story" => $storyData->toArray()]),
+                "body" => json_encode($payload),
             ],
         );
         return new StoryResponse($httpResponse);