Storyblok PHP Content API Client

https://github.com/storyblok/php-content-api-client
Admin
A PHP client library for interacting with the Storyblok Content Delivery API, enabling developers to...
Tokens:6,222
Snippets:38
Trust Score:10
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Storyblok PHP Content API Client

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Installs the Storyblok PHP Content API Client using Composer. This is the primary method for adding the library to your PHP project.

```bash
composer require storyblok/php-content-api-client
```

--------------------------------

### LikeFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a LikeFilter to perform pattern matching on a text field, using wildcards.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\LikeFilter;

new LikeFilter(field: 'description', value: '*I love Symfony*');
```

--------------------------------

### Get All Links

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves all available links from Storyblok. This method requires an initialized LinksApi instance.

```php
use Storyblok\Api\LinksApi;
use Storyblok\Api\StoryblokClient;

$client = new StoryblokClient(/* ... */);

$linksApi = new LinksApi($client);
$response = $linksApi->all();
```

--------------------------------

### Get All Tags

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves all available tags from Storyblok. This method requires an initialized TagsApi instance.

```php
use Storyblok\Api\TagsApi;
use Storyblok\Api\StoryblokClient;

$client = new StoryblokClient(/* ... */);

$api = new TagsApi($client);
$response = $api->all(); // returns Storyblok\Api\Response\TagsResponse
```

--------------------------------

### LessThanDateFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a LessThanDateFilter to filter entries where a date field is before a specified date.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\LessThanDateFilter;

new LessThanDateFilter(field: 'created_at', value: new \DateTimeImmutable());
```

--------------------------------

### Get All Root Links

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves all root links from Storyblok. This method is used to get top-level links in the content tree.

```php
use Storyblok\Api\LinksApi;
use Storyblok\Api\StoryblokClient;

$client = new StoryblokClient(/* ... */);

$linksApi = new LinksApi($client);
$response = $linksApi->roots($id);
```

--------------------------------

### NotLikeFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a NotLikeFilter to exclude text fields that match a specified pattern.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\NotLikeFilter;

new NotLikeFilter(field: 'description', value: '*Text*');
```

--------------------------------

### OrFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates an OrFilter to combine multiple filter conditions, where at least one condition must be true.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\OrFilter;
use Storyblok\Api\Domain\Value\Filter\Filters\LikeFilter;
use Storyblok\Api\Domain\Value\Filter\Filters\NotLikeFilter;

new OrFilter(
    new LikeFilter(field: 'text', value: 'Yes!*'),
    new LikeFilter(field: 'text', value: 'Maybe!*'),
    // ...
);
```

--------------------------------

### LessThanFloatFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a LessThanFloatFilter to filter entries where a float field is less than a specified value.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\LessThanFloatFilter;

new LessThanFloatFilter(field: 'price', value: 199.99);
```

--------------------------------

### BlogPostCollection Implementation

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Example implementation of a ContentTypeCollection for BlogPosts. It extends the abstract class and provides the `createItem` method to instantiate BlogPost objects using a ContentTypeFactory.

```php
<?php

declare(strict_types=1);

namespace App\ContentType\BlogPost;

use App\ContentType\ContentTypeCollection;
use App\ContentType\ContentTypeFactory;

/**
 * @extends ContentTypeCollection<BlogPost>
 */
final readonly class BlogPostCollection extends ContentTypeCollection
{
    protected function createItem(array $values): BlogPost
    {
        return ContentTypeFactory::create($values, BlogPost::class);
    }
}

```

--------------------------------

### Setup Storyblok Client

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Initializes the StoryblokClient with the base URI, API token, and an optional timeout. This client instance is used to make authenticated requests to the Storyblok API.

```php
use Storyblok\Api\StoryblokClient;

$client = new StoryblokClient(
    baseUri: 'https://api.storyblok.com',
    token: '***********',
    timeout: 10 // optional
);

// you can now request any endpoint which needs authentication
$client->request('GET', '/api/something', $options);
```

--------------------------------

### AnyInArrayFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates an AnyInArrayFilter to check if any of the specified values are present in an array field.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\AnyInArrayFilter;

new AnyInArrayFilter(field: 'tags', value: ['foo', 'bar', 'baz']);
```

--------------------------------

### LessThanIntFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a LessThanIntFilter to filter entries where an integer field is less than a specified value.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\LessThanIntFilter;

new LessThanIntFilter(field: 'stock', value: 100);
```

--------------------------------

### Get Story by Slug

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Fetches a Storyblok story using its slug. Requires a Storyblok client and specifies the language for the request.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Request\StoryRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->bySlug('folder/slug', new StoryRequest(
    language: 'de',
));
```

--------------------------------

### AllInArrayFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates an AllInArrayFilter to check if all specified values are present in an array field.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\AllInArrayFilter;

new AllInArrayFilter(field: 'tags', value: ['foo', 'bar', 'baz']);
```

--------------------------------

### GreaterThanDateFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a GreaterThanDateFilter to filter entries where a date field is after a specified date.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\GreaterThanDateFilter;

new GreaterThanDateFilter(field: 'created_at', value: new \DateTimeImmutable());
```

--------------------------------

### Get all available stories by Content Type

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves all stories of a specific content type, with optional request parameters like language.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Request\StoriesRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->allByContentType('custom_content_type', new StoriesRequest(
    language: 'de',
));
```

--------------------------------

### Get story by UUID

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves a single story by its UUID, with optional request parameters.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Uuid;
use Storyblok\Api\Request\StoryRequest;

$uuid = new Uuid(/** ... */);

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->byUuid($uuid, new StoryRequest(
    language: 'de',
));
```

--------------------------------

### IsFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates an IsFilter to check for specific states of a field, such as empty, not empty, true, false, or null.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\IsFilter;

// You can use one of the following constants:
// IsFilter::EMPTY_ARRAY
// IsFilter::NOT_EMPTY_ARRAY
// IsFilter::EMPTY
// IsFilter::NOT_EMPTY
// IsFilter::TRUE
// IsFilter::FALSE
// IsFilter::NULL
// IsFilter::NOT_NULL

new IsFilter(field: 'text', value: IsFilter::EMPTY);
```

--------------------------------

### GreaterThanFloatFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a GreaterThanFloatFilter to filter entries where a float field is greater than a specified value.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\GreaterThanFloatFilter;

new GreaterThanFloatFilter(field: 'price', value: 39.99);
```

--------------------------------

### Get Asset by Filename

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Fetches an asset from Storyblok using its filename. Requires configuring the Assets client with the base URI and an assets API token.

```php
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\AssetsApi;

$client = new StoryblokClient(
    baseUri: 'https://api.storyblok.com',
    token: 'assets-api-token',
    timeout: 10 // optional
);

$assetsApi = new AssetsApi($assetsClient);
$assetsApi->get('filename.png')
```

--------------------------------

### GreaterThanIntFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a GreaterThanIntFilter to filter entries where an integer field is greater than a specified value.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\GreaterThanIntFilter;

new GreaterThanIntFilter(field: 'stock', value: 0);
```

--------------------------------

### Get Datasource Entries by Name

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Fetches datasource entries by their name. If the datasource has dimensions, a specific dimension can be requested.

```php
use Storyblok\Api\DatasourceApi;
use Storyblok\Api\StoryblokClient;

$client = new StoryblokClient(/* ... */);

$api = new DatasourceApi($client);
$response = $api->byName('tags'); // returns Storyblok\Api\Domain\Value\Datasource
```

```php
use Storyblok\Api\DatasourceApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Datasource\Dimension;

$client = new StoryblokClient(/* ... */);

$api = new DatasourceApi($client);
$response = $api->byName('tags', new Dimension('de')); // returns Storyblok\Api\Domain\Value\Datasource
```

--------------------------------

### Get Links with Pagination

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves links from Storyblok with custom pagination settings. Allows specifying the page number and items per page.

```php
use Storyblok\Api\LinksApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Dto\Pagination;
use Storyblok\Api\Request\LinksRequest;

$client = new StoryblokClient(/* ... */);

$linksApi = new LinksApi($client);
$response = $linksApi->all(new LinksRequest(
    pagination: new Pagination(page: 1, perPage: 1000)
));
```

--------------------------------

### InFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates an InFilter to check if a field's value is present in a given list or matches a single value.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\InFilter;

new InFilter(field: 'text', value: 'Hello World!');
// or
new InFilter(field: 'text', value: ['Hello Symfony!', 'Hello SensioLabs!']);
```

--------------------------------

### NotInFilter Example

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Creates a NotInFilter to check if a field's value is not present in a given list or does not match a single value.

```php
use Storyblok\Api\Domain\Value\Filter\Filters\NotInFilter;

new NotInFilter(field: 'text', value: 'Hello World!');
// or
new NotInFilter(field: 'text', value: ['Bye Symfony!', 'Bye SensioLabs!']);
```

--------------------------------

### Get multiple stories by multiple UUIDs

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves multiple stories by providing an array of UUID objects, with optional request parameters.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Request\StoriesRequest;
use Storyblok\Api\Domain\Value\Uuid;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->allByUuids([new Uuid(/** ... */), new Uuid(/** ... */)], new StoriesRequest(
    language: 'de',
));
```

--------------------------------

### Get Story by ID

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Fetches a Storyblok story using its unique ID. Requires a Storyblok client, a story ID object, and specifies the language for the request.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Id;
use Storyblok\Api\Request\StoryRequest;

$id = new Id(/** ... */);

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->byId($id, new StoryRequest(
    language: 'de',
));
```

--------------------------------

### Get Links by Parent ID

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Fetches links that are children of a specified parent link ID. Requires a Storyblok client and the parent ID.

```php
use Storyblok\Api\LinksApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Id;

$id = new Id(/** ... */);

$client = new StoryblokClient(/* ... */);

$linksApi = new LinksApi($client);
$response = $linksApi->byParent($id);
```

--------------------------------

### Get Current Space Information

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves information about the current Storyblok space associated with the provided API token. It utilizes the SpacesApi class for this operation.

```php
use Storyblok\Api\SpacesApi;
use Storyblok\Api\StoryblokClient;

$client = new StoryblokClient(/* ... */);
$spacesApi = new SpacesApi($client);

$response = $spacesApi->me();
```

--------------------------------

### Fetch Stories with Filtering

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves stories filtered by specific criteria, such as values within a field. This example demonstrates filtering stories where a 'single_reference_field' matches a given UUID.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Filter\FilterCollection;
use Storyblok\Api\Domain\Value\Dto\Direction;
use Storyblok\Api\Domain\Value\Filter\Filters\InFilter;
use Storyblok\Api\Request\StoriesRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->all(new StoriesRequest(
    language: 'de',
    filters: new FilterCollection([
        new InFilter(field: 'single_reference_field', value: 'f2fdb571-a265-4d8a-b7c5-7050d23c2383')
    ])
));
```

--------------------------------

### Instantiating BlogPostCollection

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Demonstrates how to instantiate a BlogPostCollection by passing the result of a Storyblok API call to the constructor. It includes parameters for content type, language, pagination, sorting, filters, and excluded fields.

```php
new BlogPostCollection(
    $this->stories->allByContentType(
        BlogPost::type(),
        new StoriesRequest(
            language: $this->localeSwitcher->getLocale(),
            pagination: new Pagination($this->curPage, self::PER_PAGE),
            sortBy: new SortBy('first_published_at', Direction::Desc),
            filters: $filters,
            excludeFields: new FieldCollection([
                new Field('body'),
                new Field('additional_contents'),
            ]),
        ),
    ),
);

```

--------------------------------

### Fetch Story by Slug with Version

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Fetches a specific story by its slug, allowing you to specify the version (Draft or Published) globally or per method call. A StoryRequest object is used for parameters like language and version.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Dto\Version;
use Storyblok\Api\Request\StoryRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client, Version::Draft);
$response = $storiesApi->bySlug('/my-story/', new StoryRequest(
    language: 'de',
));
```

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Dto\Version;
use Storyblok\Api\Request\StoryRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client, Version::Published);
$response = $storiesApi->bySlug('/my-story/', new StoryRequest(
    language: 'de',
    version: Version::Draft, // This overrides the global "version"
));
```

--------------------------------

### Fetch Stories with Pagination

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves stories with specific pagination settings, allowing you to control the page number and the number of items per page. This is useful for handling large sets of content.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Dto\Pagination;
use Storyblok\Api\Request\StoriesRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->all(new StoriesRequest(
    language: 'de',
    pagination: new Pagination(page: 1, perPage: 30)
));
```

--------------------------------

### Storyblok Content API Client Methods

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Provides methods for mapping various data types from the Storyblok Content API into PHP objects and primitive types. Includes handling for single items, lists, optional values, enums, dates, UUIDs, assets, rich text, booleans, and numeric types.

```APIDOC
StoryblokContentApiClientMethods:
  one(): Maps a single item to an object.
  list(): Maps a list of items to objects, with support for count constraints.
  nullOrOne(): Similar to one(), but allows the field to be null.
  enum(string $value, array $allowedValues = [], ?string $defaultValue = null): Maps a string to an enum, with optional default and whitelisting.
  DateTimeImmutable(string $dateString): Returns a Safe\DateTimeImmutable object from a date string.
  Uuid(string $uuidString): Returns a Storyblok\Api\Domain\Value\Uuid instance from a string.
  Asset(): Maps an asset array to a Storyblok\Api\Domain\Type\Asset object.
  nullOrAsset(): Similar to Asset(), but allows null or invalid input.
  MultiLink(): Maps a multilink array to a Storyblok\Api\Domain\Type\MultiLink object.
  nullOrMultiLink(): Similar to MultiLink(), but returns null if essential link data is missing.
  RichText(): Maps rich text content to a Storyblok\Api\Domain\Type\RichText object.
  nullOrRichText(): Similar to RichText(), but returns null if content is empty or whitespace only.
  boolean(): Returns true if the key exists and its value is true, otherwise false.
  zeroOrInteger(): Returns an integer from the field, or 0 if missing.
  zeroOrFloat(): Returns a float from the field, or 0.0 if missing.
  string(): Returns a trimmed non-empty string, with optional max length check.
  nullOrString(): Similar to string(), but returns null if missing or invalid.
  nullOrEditable(): Returns an Editable instance or null.
```

--------------------------------

### Fetch All Stories

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves all available stories from Storyblok, optionally specifying a language. This method uses the StoriesApi and accepts a StoriesRequest object for parameters.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Request\StoriesRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->all(new StoriesRequest(language: 'de'));
```

--------------------------------

### ContentTypeCollection Class Definition

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Defines the abstract ContentTypeCollection class for managing Storyblok content types. It handles pagination, total counts, and provides an iterator for content items. It requires an implementation of `createItem` to map raw data to specific content type objects.

```php
<?php

declare(strict_types=1);

namespace App\ContentType;

use IteratorAggregate;
use Storyblok\Api\Response\StoriesResponse;

/**
 * @template T of ContentTypeInterface
 *
 * @implements IteratorAggregate<int, T>
 */
abstract readonly class ContentTypeCollection implements \Countable, \IteratorAggregate
{
    public int $total;
    public int $perPage;
    public int $curPage;
    public int $lastPage;
    public ?int $prevPage;
    public ?int $nextPage;

    /**
     * @var list<T>
     */
    private array $items;

    final public function __construct(StoriesResponse $response)
    {
        $this->items = array_values(array_map($this->createItem(...), $response->stories));

        $this->total = $response->total->value;
        $this->curPage = $response->pagination->page;
        $this->perPage = $response->pagination->perPage;

        $this->lastPage = (int) ceil($this->total / $this->perPage);
        $this->prevPage = 1 < $this->curPage ? $this->curPage - 1 : null;
        $this->nextPage = $this->curPage < $this->lastPage ? $this->curPage + 1 : null;
    }

    /**
     * @return \Traversable<int, T>
     */
    final public function getIterator(): \Traversable
    {
        return new \ArrayIterator($this->items);
    }

    final public function count(): int
    {
        return \count($this->items);
    }

    /**
     * @param array<string, mixed> $values
     *
     * @return T
     */
    abstract protected function createItem(array $values): ContentTypeInterface;
}

```

--------------------------------

### Fetch Stories with Sorting

Source: https://github.com/storyblok/php-content-api-client/blob/master/README.md

Retrieves stories sorted by a specified field and direction (Ascending or Descending). This allows for ordered retrieval of content based on criteria like title or creation date.

```php
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;
use Storyblok\Api\Domain\Value\Dto\SortBy;
use Storyblok\Api\Domain\Value\Dto\Direction;
use Storyblok\Api\Request\StoriesRequest;

$client = new StoryblokClient(/* ... */);

$storiesApi = new StoriesApi($client);
$response = $storiesApi->all(new StoriesRequest(
    language: 'de',
    sortBy: new SortBy(field: 'title', direction: Direction::Desc)
));
```
Tokens:
Raw