Adding AssetFolderApi endpoint for managing asset folders

Author: roberto-butti

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 1.2.0 - WIP
 - Adding `AssetApi::update()` method for updating asset metadata (alt, title, asset_folder_id, internal_tag_ids, etc.)
+- Adding `AssetFolderApi` endpoint for managing asset folders (list, get, create, update, delete)
+- Adding `AssetFolder`, `AssetFolders` data classes
+- Adding `AssetFolderResponse`, `AssetFoldersResponse` response classes
 
 
 ## 1.1.5 - 2026-04-08

README.md

@@ -129,7 +129,7 @@ $client = new ManagementApiClient($storyblokPersonalAccessToken);
 
 The Storyblok **Management API Client** provides two main approaches for interacting with the API:
 
-- Using specific API classes (like `StoryApi` or `SpaceApi` or `AssetApi` or `TagApi` or `UserApi`)
+- Using specific API classes (like `StoryApi` or `SpaceApi` or `AssetApi` or `AssetFolderApi` or `TagApi` or `UserApi`)
 - Using specific API classes for handling bulk data (like `StoryBulkApi`)
 - Using the `ManagementApi` class
 
@@ -139,11 +139,12 @@ Alternatively, you can leverage dedicated classes like `SpaceApi`, which are tai
 
 If a dedicated API class like `SpaceApi` or `StoryApi` does not exist for your desired endpoint, you can always fall back to the more versatile `ManagementApi` class.
 
-In addition to the general-purpose `ManagementApi` class, the Storyblok Management PHP client also provides specific classes such as `SpaceApi`, `StoryApi`, `TagApi` and `AssetApi`. These classes function similarly to the `ManagementApi` but are tailored for specific scenarios, offering additional methods or data types to work with particular resources.
+In addition to the general-purpose `ManagementApi` class, the Storyblok Management PHP client also provides specific classes such as `SpaceApi`, `StoryApi`, `TagApi`, `AssetApi` and `AssetFolderApi`. These classes function similarly to the `ManagementApi` but are tailored for specific scenarios, offering additional methods or data types to work with particular resources.
 
 - `SpaceApi` focuses on managing space-level operations, such as retrieving space information, performing backup etc.
 - `StoryApi` specializes in handling stories and their content, including creating, updating, retrieving, and deleting stories. This class also provides methods that deal with the structure and fields specific to stories.
 - `AssetApi` designed to manage assets like images, files, and other media. It provides methods to upload, retrieve, and manage assets, offering features specific to media management.
+- `AssetFolderApi` designed to manage asset folders, including creating, retrieving, updating, and deleting folders for organizing assets.
 - `TagApi` designed to manage tags.
 - `UserApi` designed to handle the current user. "Current" means the user related to the access token used for instancing the `ManagementApiClient` object.
 
@@ -1035,6 +1036,76 @@ try {
 }
 ```
 
+## Handling asset folders
+
+For using the `AssetFolderApi` class you have to import:
+
+```php
+use Storyblok\ManagementApi\Endpoints\AssetFolderApi;
+```
+
+For using the `AssetFolder` class you have to import:
+
+```php
+use Storyblok\ManagementApi\Data\AssetFolder;
+```
+
+### Getting the AssetFolderApi instance
+
+```php
+$assetFolderApi = new AssetFolderApi($client, $spaceId);
+```
+
+### Listing asset folders
+
+```php
+$folders = $assetFolderApi->page()->data();
+
+foreach ($folders as $folder) {
+    echo $folder->id() . PHP_EOL;
+    echo $folder->name() . PHP_EOL;
+    echo $folder->parentId() . PHP_EOL;
+}
+```
+
+### Getting one asset folder
+
+```php
+$folder = $assetFolderApi->get($folderId)->data();
+echo $folder->id() . PHP_EOL;
+echo $folder->name() . PHP_EOL;
+```
+
+### Creating an asset folder
+
+```php
+$folder = new AssetFolder("My New Folder");
+$created = $assetFolderApi->create($folder)->data();
+echo "Created folder, ID: " . $created->id() . PHP_EOL;
+```
+
+To create a subfolder, set the `parent_id`:
+
+```php
+$folder = new AssetFolder("Subfolder");
+$folder->set("parent_id", $parentFolderId);
+$created = $assetFolderApi->create($folder)->data();
+```
+
+### Updating an asset folder
+
+```php
+$folder = $assetFolderApi->get($folderId)->data();
+$folder->set("name", "Renamed Folder");
+$updated = $assetFolderApi->update($folderId, $folder)->data();
+```
+
+### Deleting an asset folder
+
+```php
+$assetFolderApi->delete($folderId);
+```
+
 ## Handling tags
 
 For using the `TagApi` class you have to import:

src/Data/AssetFolder.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Data;
+
+use Storyblok\ManagementApi\Exceptions\StoryblokFormatException;
+
+class AssetFolder extends BaseData
+{
+    public function __construct(string $name)
+    {
+        $this->data = [];
+        $this->data["name"] = $name;
+    }
+
+    /**
+     * @param mixed[] $data
+     * @throws StoryblokFormatException
+     */
+    public static function make(array $data = []): self
+    {
+        $dataObject = new StoryblokData($data);
+        if (!($dataObject->hasKey("name"))) {
+            // is not valid
+        }
+
+        $assetFolder = new AssetFolder(
+            $dataObject->getString("name"),
+        );
+        $assetFolder->setData($dataObject->toArray());
+        if (!$assetFolder->isValid()) {
+            throw new StoryblokFormatException("AssetFolder is not valid");
+        }
+
+        return $assetFolder;
+    }
+
+    public function isValid(): bool
+    {
+        return $this->hasKey("name");
+    }
+
+    public function id(): string
+    {
+        return $this->getString("id");
+    }
+
+    public function name(): string
+    {
+        return $this->getString("name");
+    }
+
+    public function parentId(): int|null
+    {
+        return $this->getInt("parent_id");
+    }
+}

src/Data/AssetFolders.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Data;
+
+class AssetFolders extends StoryblokData
+{
+    #[\Override]
+    public function getDataClass(): string
+    {
+        return AssetFolder::class;
+    }
+
+    /**
+     * @param mixed[] $data
+     */
+    #[\Override]
+    public static function make(array $data = []): self
+    {
+        return new self($data);
+    }
+}

src/Endpoints/AssetFolderApi.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Endpoints;
+
+use Storyblok\ManagementApi\Data\AssetFolder;
+use Storyblok\ManagementApi\Response\AssetFolderResponse;
+use Storyblok\ManagementApi\Response\AssetFoldersResponse;
+
+class AssetFolderApi extends EndpointSpace
+{
+    /**
+     * Retrieve all asset folders.
+     * @link https://www.storyblok.com/docs/api/management/core-resources/asset-folders/retrieve-multiple-asset-folders
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
+    public function page(): AssetFoldersResponse
+    {
+        $httpResponse = $this->makeHttpRequest(
+            "GET",
+            "/v1/spaces/" . $this->spaceId . "/asset_folders",
+        );
+        return new AssetFoldersResponse($httpResponse);
+    }
+
+    /**
+     * Retrieve a single asset folder.
+     * @link https://www.storyblok.com/docs/api/management/core-resources/asset-folders/retrieve-one-asset-folder
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
+    public function get(string|int $assetFolderId): AssetFolderResponse
+    {
+        $httpResponse = $this->makeHttpRequest(
+            "GET",
+            "/v1/spaces/" . $this->spaceId . "/asset_folders/" . $assetFolderId,
+        );
+        return new AssetFolderResponse($httpResponse);
+    }
+
+    /**
+     * Create a new asset folder.
+     * @link https://www.storyblok.com/docs/api/management/core-resources/asset-folders/create-an-asset-folder
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
+    public function create(AssetFolder $assetFolderData): AssetFolderResponse
+    {
+        $httpResponse = $this->makeHttpRequest(
+            "POST",
+            "/v1/spaces/" . $this->spaceId . "/asset_folders",
+            [
+                "body" => json_encode(["asset_folder" => $assetFolderData->toArray()]),
+            ],
+        );
+        return new AssetFolderResponse($httpResponse);
+    }
+
+    /**
+     * Update an existing asset folder.
+     * @link https://www.storyblok.com/docs/api/management/core-resources/asset-folders/update-an-asset-folder
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
+    public function update(string|int $assetFolderId, AssetFolder $assetFolderData): AssetFolderResponse
+    {
+        $httpResponse = $this->makeHttpRequest(
+            "PUT",
+            "/v1/spaces/" . $this->spaceId . "/asset_folders/" . $assetFolderId,
+            [
+                "body" => json_encode(["asset_folder" => $assetFolderData->toArray()]),
+            ],
+        );
+        return new AssetFolderResponse($httpResponse);
+    }
+
+    /**
+     * Delete an asset folder.
+     * @link https://www.storyblok.com/docs/api/management/core-resources/asset-folders/delete-an-asset-folder
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
+    public function delete(string|int $assetFolderId): AssetFolderResponse
+    {
+        $httpResponse = $this->makeHttpRequest(
+            "DELETE",
+            "/v1/spaces/" . $this->spaceId . "/asset_folders/" . $assetFolderId,
+        );
+        return new AssetFolderResponse($httpResponse);
+    }
+}

src/Response/AssetFolderResponse.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Response;
+
+use Storyblok\ManagementApi\Data\AssetFolder;
+use Storyblok\ManagementApi\Exceptions\StoryblokFormatException;
+use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\RedirectionExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
+
+class AssetFolderResponse extends StoryblokResponse implements StoryblokResponseInterface
+{
+    /**
+     * @throws TransportExceptionInterface
+     * @throws ServerExceptionInterface
+     * @throws RedirectionExceptionInterface
+     * @throws DecodingExceptionInterface
+     * @throws StoryblokFormatException
+     * @throws ClientExceptionInterface
+     */
+    #[\Override]
+    public function data(): AssetFolder
+    {
+        $key = "asset_folder";
+        $array = $this->toArray();
+        if (array_key_exists($key, $array)) {
+            return AssetFolder::make($array[$key]);
+        }
+
+        throw new StoryblokFormatException(sprintf("Expected '%s' in the response.", $key));
+    }
+}

src/Response/AssetFoldersResponse.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Response;
+
+use Storyblok\ManagementApi\Data\AssetFolders;
+use Storyblok\ManagementApi\Exceptions\StoryblokFormatException;
+
+class AssetFoldersResponse extends StoryblokResponse implements StoryblokResponseInterface
+{
+    #[\Override]
+    public function data(): AssetFolders
+    {
+        $key = "asset_folders";
+        $array = $this->toArray();
+        if (array_key_exists($key, $array)) {
+            return new AssetFolders($array[$key]);
+        }
+
+        throw new StoryblokFormatException(sprintf("Expected '%s' in the response.", $key));
+    }
+}