The Storyblok Management API PHP Client library simplifies the integration with Storyblok's Management API in PHP applications. With easy-to-use methods, you can interact with your Storyblok space effectively.

For the Content API PHP Client, see storyblok/php-content-api-client.

Installation

Install the package via Composer:

Below is an example showcasing how to use the library to interact with the Management API.

Initializing the ManagementApiClient

Initialize the ManagementApiClient with your personal access token to interact with the API:

For using the ManagementApiClient class you have to import:

Setting the space region

The second optional parameter is for setting the region.

If you are interested to know more about Storyblok regions, check this FAQ: https://www.storyblok.com/faq/where-are-your-servers-or-aws-sites-located

We provide an Enum class to set the region. In this case, you can use the Region enum: Region::US or Region::AP or Region::CA or Region::CN.

For example, for using the US region, you can use:

Handling the Personal Access Token

To access the Management API and interact with its endpoints, you need to follow two steps:

• Retrieve a Personal Access Token (or an OAuth token).
• Store the token securely and make it available to your application (e.g., in an environment variable or another secure location).

The token for accessing the Management API differs from the Access Token used for the Content Delivery API.

To obtain a proper token for accessing the Management API you can choose:

• Personal Access Token: Navigate to your Storyblok account settings and click on "Generate new token."
• OAuth Token: Follow the steps outlined in this guide on authentication apps.

Once you have your Token, instead of storing the access token directly in the source code, you should consider handling it via environment variables. For example, you can create the .env file (if it does not already exist) and set a parameter for storing the Personal Access Token.

Then, for loading the environment variable, you can use the PHP "dotenv" package:

The PHP dotenv package is here: https://github.com/vlucas/phpdotenv

Using the Api classes

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 for handling bulk data (like StoryBulkApi)
• Using the ManagementApi class

The ManagementApi class offers a flexible, generic interface for managing content. It includes methods to get, create, update, and delete content. With this approach, you can define the endpoint path and pass query string parameters as a generic array. The response is returned as a StoryblokData object, allowing you to access the JSON payload, status codes, and other details directly.

Alternatively, you can leverage dedicated classes like SpaceApi, which are tailored to specific resources. For instance, the SpaceApi class provides methods for managing spaces and returns specialized data objects, such as Space (for a single space) or Spaces (for a collection of spaces). These classes simplify interactions with specific endpoints by offering resource-specific methods.

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.

• 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.
• 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.

These specialized classes extend the functionality of the ManagementApi class, offering more precise control and optimized methods for interacting with specific resource types in your Storyblok space.

Let's start analyzing the specialized classes, like for example the SpaceApi.

Handling Spaces

For using the SpaceApi class you have to import:

For using the Space class you have to import:

Retrieve all the spaces

Fetch a list of all spaces associated with your account in the current region (the region is initialized in the ManagementApiClient):

Loop through the spaces

Iterate through the list of spaces to access their details:

Get one specific Space

Retrieve detailed information about a specific space using its ID:

Triggering the backup

Create a backup of a specific space by triggering the backup API:

Handling Stories

For using the StoryApi class you have to import:

For using the Story class you have to import:

Getting the StoryApi instance

To handle Stories, get stories, get a single story, create a story, update a story, or delete a story, you can start getting the instance of StoryApi that allows you to access the methods for handling stories.

Getting a page of stories

When retrieving a list of stories from a space, the Management API provides paginated results. By default, each page contains 25 stories, but you can customize the number of stories per page and specify which page to retrieve.

To fetch the first page of stories:

In the case you need to retrieve the response to access to some additional information you can obtain a StoriesResponse via the page() method:

Filtering stories

You can filter stories using StoriesParams.

The StoriesParams attributes are documented in the Query Parameters of Retrieving multiple stories

Filtering stories via query filters

Besides using query parameters to filter stories, you can leverage more powerful query filters.

If you need to handle pagination (retrieving all stories across multiple pages) or create multiple stories at once, you can use the StoryBulkApi instead of the StoryApi class.

In this example, you will retrieve all stories where the "title" field is empty. (Stories with content types that do not include a "title" field in their schema will be skipped.)

Even the "query filters" are documented in the Content Delivery API, you can use the query filters with Management API. Here you can find more examples: https://www.storyblok.com/docs/api/content-delivery/v2/filter-queries/

For retrieving stories with article-page content type:

Getting a Story by ID

Creating a Story

To create a story, you can call the create() method provided by StoryApi and use the Story class. The Story class is specific for storing and handling story information. It also provides some nice methods for accessing some relevant Story fields. And because a story stores also the content, you can use the StoryComponent class to handle the fields in the content.

Publishing a story

For publishing a story by the story identifier you can use the publish method:

Creating stories in bulk

You can create multiple stories using the createStories() method (in the StoryBulkApi class), which processes an array of stories while managing rate limits through a retry mechanism that respects the '429' status code.

For example, if you have a CSV file containing content for new stories, you can use this method to efficiently create them.

Next, you can implement a script to load and parse the CSV file. In this case, we use SplFileObject and then call the createStories method to process the data:

Handling users

For using the UserApi class you have to import:

For using the User class you have to import:

Getting the current user

To get the current user, owner of the Personal access token used you can use the UserApi class for calling endpoints and the User for accessing to returned data object properties. For example, here we want to retrieve the current user (via the me() method) and obtaining the User object via data().

Typically, all the data object provides you some helper methods like:

• toArray() to obtain the data in a PHP array;
• toJson() to obtain a JSON string;
• dump() for debugging purposes, it prints on standard output the indented JSON.

Handling assets

For using the AssetApi class you have to import:

For using the Asset class you have to import:

Getting the AssetApi instance

To handle assets, get assets, get a single asset, upload an asset, update an asset, or delete an asset, you can start getting the instance of AssetApi that allows you to access the methods for handling assets.

Getting the assets list

To get the assets list you can use the assetApi and the AssetsData.

Filtering assets

Using the AssetsParams class you can set up filters for filtering the assets.

In the example above, we are filtering the deleted assets (inFolder : -1) and with the filename that contains the term something. Additional info: using PaginationParams you can retrieve a specific page. The example new PaginationParams(1,1000) retrieves the page number 1 and 1000 items per page.

Getting one asset

To get a specific asset, you can use the AssetApi and the AssetData classes.

Uploading an Asset

To upload an asset, you can use the upload() method:

Deleting an Asset

To delete an asset, you can use the delete() method. The delete() method requires the asset ID (you want to delete) as parameter:

Handling tags

For using the TagApi class you have to import:

For using the Tag class you have to import:

Getting the TagApi instance

To handle tags, get tags,create an asset, update an asset, or delete an asset, you can start getting the instance of TagApi that allows you to access the methods for handling tags.

Getting the tags list

To get the tags list you can use the page method from TagApi class and obtaining the TagsData object.

Creating a new tag

To create a new tag, you can define the name of the tag using the create method:

A practical example

Now we want to upload a new image, and then create a new simple story that includes the new image.

Another Example with a Nested Component

Now that we've seen how to programmatically create a story (content) with fields like title, body, and image, let's dive deeper into handling nested components.

Scenario

You have a default-page content type that includes a Blok field. The Blok field allows you to nest components within your content. This means you can add a Hero Section component, followed by an Image Text Section component, and so on.

Goal

The objective is to:

• Set up a Hero Section component.
• Set up an Image Text Section component.
• Add these components to a story.

To demonstrate deeper levels of nesting, we will also set up a Button component and nest it within the Image Text Section component.

Handling Workflows

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.

For using the WorkflowApi class you have to import:

For using the Workflow class you have to import:

Retrieving workflows

Creating a new custom workflow

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

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):

And then create a new workflow stage:

Using the ManagementApi class

To illustrate how to use the ManagementApi class, we will demonstrate its usage with the Internal Tags endpoint.

Reference: Management API documentation for the Internal Tags endpoint

This approach can be adapted to create other resources by modifying the endpoint and payload, for example, for handling data sources, components, etc. To learn more about the endpoints, the parameters, and the structure of the response payload, you can use the Storyblok Management API reference.

Retrieving content with ManagementApi class

To retrieve content using the ManagementApi class:

1. Initialize the client.
2. Obtain an instance of the ManagementApi class.
3. Call the get method of the ManagementApi class using the appropriate parameters.

For example, to retrieve multiple internal tags, use the Internal Tags endpoint with the GET HTTP method: Retrieve Multiple Internal Tags.

Below is an example of initializing the client for the EU region (default) using a Personal Access Token:

Getting the ManagementApi instance:

Calling GET HTTP method with spaces/:spaceid/internal_tags:

Using Query Parameters and Accessing Data

You can pass query string parameters as an array in the second parameter of the get() method.

To retrieve internal tags, specify the object type, such as asset or component. In the example below, the by_object_type parameter is set to asset to fetch tags for assets. You can also filter asset tags by name using the search query parameter.

The get() method returns a StoryblokResponse instance, which provides useful information such as the last called URL, the total number of items (helpful for paginated responses), and the data itself:

You can access the internal_tags data in the returned JSON like this:

The $response->data() method retrieves an instance of the StoryblokData class, which is responsible for storing the JSON response data in memory. It also provides convenient methods to access JSON values, including nested data.

For example, the get() method, provided by the StoryblokData class, allows access to specific data:

In this case, you're retrieving the name of the first tag in the internal_tags array.

Looping through the items

Thanks to the StoryblokData object returned by the $response->data(), you can loop through the items and get values.

To loop through internal_tags from the StoryblokData object and access individual values.

To retrieve the items, you use the get() method to access the internal_tags array.

To iterate through the items, you can use foreach because StoryblokData is iterable, and you can access specific properties of each tag using the get() method:

Creating a new resource with the Storyblok Management API

This example demonstrates creating a new internal tag using the Storyblok Management API.

First, define the tag details in an array, including attributes like name and object_type. Then, use the post method of the ManagementApi class to send a POST request to the internal_tags endpoint for the specified space.

The response will indicate whether the operation was successful. If it succeeds, you can retrieve the created tag’s data using the data()->get("internal_tag") method. If the operation fails, the error message can be retrieved using the getErrorMessage() method.

Here is the complete example:

Editing a resource with the Storyblok Management API

This example demonstrates how to update an existing resource, such as an internal tag, using the Storyblok Management API.

To edit a resource, first retrieve or define the resource data you want to update. Modify the desired fields in the resource array, then use the put method of the ManagementApi class to send an update request to the appropriate endpoint, including the resource's ID.

After sending the request, check if the operation was successful. If successful, you can log the updated response or any relevant details. If it fails, retrieve the error message for debugging.

Here is the complete example:

Deleting a resource with the Storyblok Management API

This example explains how to delete a resource, such as an internal tag, using the Storyblok Management API.

To delete a resource, use the delete method of the ManagementApi class and specify the appropriate endpoint along with the resource's ID. The ID uniquely identifies the resource you want to remove.

After sending the delete request, check the response to confirm whether the operation was successful. For a successful delete, the response body is typically empty. If the operation fails, retrieve and log the error message for further investigation.

Here is the complete example:

Quick recap: using the ManagementApi Class

The ManagementApi class is used for performing generic administrative tasks in Storyblok, including creating, updating, retrieving, and deleting resources.

Documentation

Refer to the official documentation for detailed API descriptions and additional usage examples: https://www.storyblok.com/docs/api/management/getting-started

Contributing

Feel free to open issues or submit pull requests to improve the package.

License

This SDK is licensed under the MIT License. See the LICENSE file for details.

Next implementations

• [ ] define LocalizedPath class to allow to handle the localized path in setting the Story for creating and update the story
• [ ] add the set method for localized field (for example set("heading", $value, "de")) for setting the heading__i18n__de field