Welcome to StoryBulkApi class

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.0.5 - WIP
+
+- Re-structuring bulk operations and pagination with `StoryBulkApi` class
+
 ## 0.0.4 - 2025-02-05
 
 - Adding WorkflowStage Api class for handling workflow stages

README.md

@@ -210,13 +210,17 @@ $stories = $storyApi->page(
 ### 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.)
 
 ```php
 use Storyblok\ManagementApi\QueryParameters\Filters\Filter;
 use Storyblok\ManagementApi\QueryParameters\Filters\QueryFilters;
 
-$stories = $storyApi->all(
+$storyBulkApi = $client->storyBulkApi($spaceId);
+$stories = $storyBulkApi->all(
     filters: (new QueryFilters())->add(
         new Filter(
             "title",
@@ -298,7 +302,7 @@ $storyApi->publish($storyId);
 
 
 ### Creating stories in bulk
-You can create multiple stories using the `createBulk()` method, which processes an array of stories while managing rate limits through a retry mechanism that respects the '429' status code.
+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.
 
@@ -308,10 +312,10 @@ myslug-002;My Story 2 BULK;page
 myslug-003;My Story 3 BULK;page
 ```
 
-Next, you can implement a script to load and parse the CSV file. In this case, we use `SplFileObject` and then call the `createBulk` method to process the data:
+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:
 
 ```php
-$storyApi = $client->storyApi($spaceId);
+$storyBulkApi = $client->storyBulkApi($spaceId);
 $file = new SplFileObject("stories.csv");
 $file->setFlags(SplFileObject::READ_CSV);
 $file->setCsvControl(separator: ";");
@@ -324,7 +328,7 @@ foreach ($file as $row) {
     $story->setContentType($contentType);
     $stories[] = $story;
 }
-$createdStories = iterator_to_array($storyApi->createBulk($stories));
+$createdStories = iterator_to_array($storyBulkApi->createStories($stories));
 ```
 
 ## Handling users

src/Endpoints/StoryApi.php

@@ -24,16 +24,6 @@
  */
 class StoryApi extends EndpointSpace
 {
-    private const int DEFAULT_ITEMS_PER_PAGE = 25;
-
-    private const int DEFAULT_PAGE = 1;
-
-    private const int RATE_LIMIT_STATUS_CODE = 429;
-
-    private const int RETRY_DELAY = 1;
-
-    private const int MAX_RETRIES = 3;
-
     /**
      * StoryApi constructor.
      */
@@ -45,47 +35,6 @@ public function __construct(
         parent::__construct($httpClient, $spaceId);
     }
 
-    /**
-     * Retrieves all stories using pagination
-     *
-     * @param int $itemsPerPage Number of items to retrieve per page
-     * @return \Generator<StoryData>
-     * @throws StoryblokApiException
-     */
-    public function all(?StoriesParams $params = null, ?QueryFilters $filters = null, int $itemsPerPage = self::DEFAULT_ITEMS_PER_PAGE): \Generator
-    {
-
-        $totalPages = null;
-        $retryCount = 0;
-        $page = new PaginationParams(self::DEFAULT_PAGE, $itemsPerPage);
-
-        do {
-            try {
-                $response = $this->page(
-                    params: $params,
-                    queryFilters: $filters,
-                    page: $page,
-                );
-
-                if ($response->isOk()) {
-                    $totalPages = $this->handleSuccessfulResponse($response, $totalPages, $itemsPerPage);
-                    yield from $this->getStoriesFromResponse($response);
-                    $page->incrementPage();
-                    $retryCount = 0;
-                } else {
-                    $this->handleErrorResponse($response, $retryCount);
-                    ++$retryCount;
-                }
-            } catch (\Exception $e) {
-                $this->logger->error('Error fetching stories', [
-                    'error' => $e->getMessage(),
-                    'page' => $page->page(),
-                ]);
-                throw new StoryblokApiException('Failed to fetch stories: ' . $e->getMessage(), 0, $e);
-            }
-        } while ($page->page() <= $totalPages);
-    }
-
     /**
      * Retrieves a specific page of stories
      */
@@ -280,114 +229,7 @@ public function unpublish(
         );
     }
 
-    /**
-     * Creates multiple stories with rate limit handling and retries
-     *
-     * @param StoryData[] $stories Array of stories to create
-     * @return \Generator<StoryblokDataInterface> Generated stories
-     * @throws StoryblokApiException
-     */
-    public function createBulk(array $stories): \Generator
-    {
-        $retryCount = 0;
-
-        foreach ($stories as $storyData) {
-            while (true) {
-                try {
-                    $response = $this->create($storyData);
-                    yield $response->data();
-                    $retryCount = 0;
-                    break;
-                } catch (StoryblokApiException $e) {
-                    if ($e->getCode() === self::RATE_LIMIT_STATUS_CODE) {
-                        if ($retryCount >= self::MAX_RETRIES) {
-                            $this->logger->error('Max retries reached while creating story', [
-                                'story_name' => $storyData->name(),
-                            ]);
-                            throw new StoryblokApiException(
-                                'Rate limit exceeded maximum retries',
-                                self::RATE_LIMIT_STATUS_CODE,
-                            );
-                        }
-
-                        $this->logger->warning('Rate limit reached while creating story, retrying...', [
-                            'retry_count' => $retryCount + 1,
-                            'max_retries' => self::MAX_RETRIES,
-                            'story_name' => $storyData->name(),
-                        ]);
-
-                        $this->handleRateLimit();
-                        ++$retryCount;
-                        continue;
-                    }
-
-                    throw $e;
-                }
-            }
-        }
-    }
-
-    /**
-     * Handles successful API response
-     */
-    private function handleSuccessfulResponse(
-        StoryblokResponseInterface $response,
-        ?int $totalPages,
-        int $itemsPerPage,
-    ): int {
-        if ($totalPages === null) {
-            $totalPages = (int) ceil($response->total() / $itemsPerPage);
-            $this->logger->info('Total stories found: ' . $response->total());
-        }
-
-        return $totalPages;
-    }
-
-    /**
-     * Handles error responses from the API
-     *
-     * @throws StoryblokApiException
-     */
-    private function handleErrorResponse(StoryblokResponseInterface $response, int $retryCount): void
-    {
-        if ($response->getResponseStatusCode() === self::RATE_LIMIT_STATUS_CODE) {
-            if ($retryCount < self::MAX_RETRIES) {
-                $this->handleRateLimit();
-            } else {
-                throw new StoryblokApiException('Rate limit exceeded maximum retries');
-            }
-        } else {
-            $this->logger->error('API error', [
-                'status' => $response->getResponseStatusCode(),
-                'message' => $response->getErrorMessage(),
-            ]);
-            throw new StoryblokApiException($response->getErrorMessage());
-        }
-    }
-
-    /**
-     * Handles rate limiting by implementing a delay
-     */
-    protected function handleRateLimit(): void
-    {
-        $this->logger->warning('Rate limit reached, waiting before retry...');
-        sleep(self::RETRY_DELAY);
-    }
 
-    /**
-     * Extracts stories from the API response
-     *
-     * @return \Generator<int, StoryData>
-     */
-    private function getStoriesFromResponse(StoryblokResponseInterface $response): \Generator
-    {
-        /** @var StoriesData $stories */
-        $stories = $response->data();
-        foreach ($stories as $story) {
-            /** @var StoryData $story */
-            yield $story;
-        }
-    }
 
     /**
      * Validates pagination parameters