Deprecate API factory methods, prefer dependency injection

roberto-butti · roberto-butti · commit 7e7418d37a01 · 2026-01-23T22:39:54.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,8 @@
 # Changelog
 
-## 1.0.12 - WIP
+## 1.1.0 - WIP
 - Moving from PestPHP to PHPUnit
+- Deprecate API factory methods, prefer dependency injection
 
 ## 1.0.11 - 2026-01-05
 - Adding parameters for updating a story
diff --git a/README.md b/README.md
@@ -1173,8 +1173,9 @@ And then create a new workflow stage:
 
 ```php
 use Storyblok\ManagementApi\Data\WorkflowStageData;
+use Storyblok\ManagementApi\Endpoints\WorkflowStageApi;
 
-$workflowStageApi = $client->workflowStageApi($spaceId);
+$workflowStageApi = new WorkflowStageApi($client, $spaceId);
 $workflowStageData = new WorkflowStageData();
 $workflowStageData->setName("Name");
 $workflowStageData->setWorkflowId($workflowId);
diff --git a/src/ManagementApiClient.php b/src/ManagementApiClient.php
@@ -105,49 +105,113 @@ public function httpAssetClient(): HttpClientInterface
         return $this->httpAssetClient;
     }
 
+    /**
+     * @deprecated Use `new StoryApi($managementApiClient, $spaceId, $logger)` instead.
+     */
     public function storyApi(
         string|int $spaceId,
         ?LoggerInterface $logger = null,
     ): StoryApi {
+        trigger_error(
+            'Method storyApi() is deprecated. Use `new StoryApi($managementApiClient, $spaceId, $logger)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new StoryApi($this, $spaceId, $logger ?? new NullLogger());
     }
 
+    /**
+     * @deprecated Use `new StoryBulkApi($managementApiClient, $spaceId, $logger)` instead.
+     */
     public function storyBulkApi(
         string|int $spaceId,
         ?LoggerInterface $logger = null,
     ): StoryBulkApi {
+        trigger_error(
+            'Method storyBulkApi() is deprecated. Use `new StoryBulkApi($managementApiClient, $spaceId, $logger)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new StoryBulkApi($this, $spaceId, $logger ?? new NullLogger());
     }
 
+    /**
+     * @deprecated Use `new AssetApi($managementApiClient, $spaceId)` instead.
+     */
     public function assetApi(string|int $spaceId): AssetApi
     {
+        trigger_error(
+            'Method assetApi() is deprecated. Use `new AssetApi($managementApiClient, $spaceId)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new AssetApi($this, $spaceId);
     }
 
+    /**
+     * @deprecated Use `new TagApi($managementApiClient, $spaceId)` instead.
+     */
     public function tagApi(string|int $spaceId): TagApi
     {
+        trigger_error(
+            'Method tagApi() is deprecated. Use `new TagApi($managementApiClient, $spaceId)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new TagApi($this, $spaceId);
     }
 
+    /**
+     * @deprecated Use `new WorkflowApi($managementApiClient, $spaceId)` instead.
+     */
     public function workflowApi(string|int $spaceId): WorkflowApi
     {
+        trigger_error(
+            'Method workflowApi() is deprecated. Use `new WorkflowApi($managementApiClient, $spaceId)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new WorkflowApi($this, $spaceId);
     }
 
+    /**
+     * @deprecated Use `new WorkflowStageApi($managementApiClient, $spaceId)` instead.
+     */
     public function workflowStageApi(string|int $spaceId): WorkflowStageApi
     {
+        trigger_error(
+            'Method workflowStageApi() is deprecated. Use `new WorkflowStageApi($managementApiClient, $spaceId)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new WorkflowStageApi($this, $spaceId);
     }
 
+    /**
+     * @deprecated Use `new ComponentApi($managementApiClient, $spaceId, $logger)` instead.
+     */
     public function componentApi(
         string|int $spaceId,
         ?LoggerInterface $logger = null,
     ): ComponentApi {
+        trigger_error(
+            'Method componentApi() is deprecated. Use `new ComponentApi($managementApiClient, $spaceId, $logger)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new ComponentApi($this, $spaceId, $logger ?? new NullLogger());
     }
 
+    /**
+     * @deprecated Use `new ManagementApi($managementApiClient)` instead.
+     */
     public function managementApi(): ManagementApi
     {
+        trigger_error(
+            'Method managementApi() is deprecated. Use `new ManagementApi($managementApiClient)` instead.',
+            E_USER_DEPRECATED,
+        );
+
         return new ManagementApi($this);
     }
 }
diff --git a/tests/Feature/AssetApiTest.php b/tests/Feature/AssetApiTest.php
@@ -33,7 +33,10 @@ public function testOneAssetAssetData(): void
         $storyblokData = $storyblokResponse->data();
 
         $this->assertSame(111, $storyblokData->get("id"));
-        $this->assertSame("https://a.storyblok.com/f/222/3799x6005/3af265ee08/mypic.jpg", $storyblokData->filenameCDN());
+        $this->assertSame(
+            "https://a.storyblok.com/f/222/3799x6005/3af265ee08/mypic.jpg",
+            $storyblokData->filenameCDN(),
+        );
         $this->assertSame(200, $storyblokResponse->getResponseStatusCode());
         $this->assertSame("image/jpeg", $storyblokData->contentType());
         $this->assertSame(3_094_788, $storyblokData->contentLength());
@@ -51,13 +54,16 @@ public function testOneAssetAssetData(): void
     public function testListAssetsAssetsData(): void
     {
         $responses = [
-            $this->mockResponse("list-assets", 200, ["total" => 2, "per-page" => 25]),
+            $this->mockResponse("list-assets", 200, [
+                "total" => 2,
+                "per-page" => 25,
+            ]),
             $this->mockResponse("empty-asset", 404),
         ];
 
         $client = new MockHttpClient($responses);
         $mapiClient = ManagementApiClient::initTest($client);
-        $assetApi = $mapiClient->assetApi("222");
+        $assetApi = new AssetApi($mapiClient, "222");
 
         $storyblokResponse = $assetApi->page();
         $storyblokData = $storyblokResponse->data();
@@ -69,7 +75,10 @@ public function testListAssetsAssetsData(): void
         }
 
         $this->assertSame(200, $storyblokResponse->getResponseStatusCode());
-        $this->assertSame("No error detected, HTTP Status Code: 200", $storyblokResponse->getErrorMessage());
+        $this->assertSame(
+            "No error detected, HTTP Status Code: 200",
+            $storyblokResponse->getErrorMessage(),
+        );
         $this->assertSame(2, $storyblokResponse->total());
         $this->assertSame(25, $storyblokResponse->perPage());
 
@@ -84,7 +93,10 @@ public function testListAssetsAssetsData(): void
     public function testListAssetsParams(): void
     {
         $responses = [
-            $this->mockResponse("list-assets", 200, ["total" => 2, "per-page" => 25]),
+            $this->mockResponse("list-assets", 200, [
+                "total" => 2,
+                "per-page" => 25,
+            ]),
             $this->mockResponse("list-assets", 200, [
                 "total" => 200,
                 "per-page" => 25,
@@ -98,21 +110,27 @@ public function testListAssetsParams(): void
 
         $client = new MockHttpClient($responses);
         $mapiClient = ManagementApiClient::initTest($client);
-        $assetApi = $mapiClient->assetApi("222");
+        $assetApi = new AssetApi($mapiClient, "222");
 
         $response = $assetApi->page(params: new AssetsParams(inFolder: -1));
 
         $url = $response->getLastCalledUrl();
         $this->assertMatchesRegularExpression('/.*in_folder=-1.*$/', $url);
-        $this->assertMatchesRegularExpression('/.*page=1&per_page=25.*$/', $url);
+        $this->assertMatchesRegularExpression(
+            '/.*page=1&per_page=25.*$/',
+            $url,
+        );
 
         $response = $assetApi->page(
             params: new AssetsParams(inFolder: -1),
             page: new PaginationParams(5, 30),
         );
 
         $url = $response->getLastCalledUrl();
-        $this->assertMatchesRegularExpression('/.*page=5&per_page=30.*$/', $url);
+        $this->assertMatchesRegularExpression(
+            '/.*page=5&per_page=30.*$/',
+            $url,
+        );
 
         $response = $assetApi->page(
             params: new AssetsParams(search: "something", withTags: "aaa"),
@@ -135,7 +153,7 @@ public function testAssetPayload(): void
 
         $client = new MockHttpClient($responses);
         $mapiClient = ManagementApiClient::initTest($client);
-        $assetApi = $mapiClient->assetApi("222");
+        $assetApi = new AssetApi($mapiClient, "222");
 
         $payload = $assetApi->buildPayload(
             "./tests/Feature/Data/image-test.png",
@@ -242,7 +260,10 @@ public function testAssetFieldHandling(): void
         $assetField = AssetField::makeFromAsset($asset);
 
         $this->assertSame(111, $assetField->get("id"));
-        $this->assertSame("https://a.storyblok.com/f/222/3799x6005/3af265ee08/mypic.jpg", $assetField->get("filename"));
+        $this->assertSame(
+            "https://a.storyblok.com/f/222/3799x6005/3af265ee08/mypic.jpg",
+            $assetField->get("filename"),
+        );
         $this->assertSame("", $assetField->getString("title"));
     }
 
@@ -264,7 +285,10 @@ public function testSetAssetInStoryComponent(): void
         $content->setAsset("image", $asset);
 
         $this->assertNull($content->get("id"));
-        $this->assertSame("https://a.storyblok.com/f/222/3799x6005/3af265ee08/mypic.jpg", $content->get("image.filename"));
+        $this->assertSame(
+            "https://a.storyblok.com/f/222/3799x6005/3af265ee08/mypic.jpg",
+            $content->get("image.filename"),
+        );
         $this->assertSame("asset", $content->get("image.fieldtype"));
         $this->assertSame("My New Article", $content->get("title"));
     }
diff --git a/tests/Feature/ManagementApiTest.php b/tests/Feature/ManagementApiTest.php
@@ -4,12 +4,17 @@
 
 namespace Tests\Feature;
 
+use Storyblok\ManagementApi\Data\Enum\Region;
+use Storyblok\ManagementApi\Endpoints\ManagementApi;
 use Tests\TestCase;
 use Storyblok\ManagementApi\ManagementApiClient;
+use Symfony\Component\HttpClient\CurlHttpClient;
 use Symfony\Component\HttpClient\Exception\ClientException;
+use Symfony\Component\HttpClient\HttpClient;
 use Symfony\Component\HttpClient\MockHttpClient;
+use Symfony\Component\HttpClient\RetryableHttpClient;
 
-final class ManagementApiClientTest extends TestCase
+final class ManagementApiTest extends TestCase
 {
     public function testMultipleResourcesStoryblokData(): void
     {
@@ -26,7 +31,7 @@ public function testMultipleResourcesStoryblokData(): void
             baseUri: "https://mapi.storyblok.com",
         );
         $mapiClient = ManagementApiClient::initTest($client);
-        $managementApi = $mapiClient->managementApi();
+        $managementApi = new ManagementApi($mapiClient);
 
         $spaceId = "321388";
         $response = $managementApi->get(
@@ -36,7 +41,10 @@ public function testMultipleResourcesStoryblokData(): void
             ],
         );
 
-        $this->assertSame("https://mapi.storyblok.com/v1/spaces/321388/internal_tags?by_object_type=asset", $response->getLastCalledUrl());
+        $this->assertSame(
+            "https://mapi.storyblok.com/v1/spaces/321388/internal_tags?by_object_type=asset",
+            $response->getLastCalledUrl(),
+        );
         $this->assertSame(8, $response->total());
         $this->assertTrue($response->isOk());
 
@@ -73,7 +81,7 @@ public function testCreateResourceStoryblokData(): void
             baseUri: "https://mapi.storyblok.com",
         );
         $mapiClient = ManagementApiClient::initTest($client);
-        $managementApi = $mapiClient->managementApi();
+        $managementApi = new ManagementApi($mapiClient);
 
         $spaceId = "321388";
         $response = $managementApi->post(
@@ -107,7 +115,7 @@ public function testDeleteResourceStoryblokData(): void
             baseUri: "https://mapi.storyblok.com",
         );
         $mapiClient = ManagementApiClient::initTest($client);
-        $managementApi = $mapiClient->managementApi();
+        $managementApi = new ManagementApi($mapiClient);
 
         $spaceId = "321388";
         $tagId = "56980";
@@ -137,7 +145,7 @@ public function testEditResourceStoryblokData(): void
             baseUri: "https://mapi.storyblok.com",
         );
         $mapiClient = ManagementApiClient::initTest($client);
-        $managementApi = $mapiClient->managementApi();
+        $managementApi = new ManagementApi($mapiClient);
 
         $spaceId = "321388";
         $tagId = "56980";
@@ -170,7 +178,7 @@ public function testStoryblokDataToArray(): void
             baseUri: "https://mapi.storyblok.com",
         );
         $mapiClient = ManagementApiClient::initTest($client);
-        $managementApi = $mapiClient->managementApi();
+        $managementApi = new ManagementApi($mapiClient);
 
         $spaceId = "321388";
         $response = $managementApi->get(
@@ -182,4 +190,33 @@ public function testStoryblokDataToArray(): void
 
         $this->assertIsArray($response->toArray());
     }
+
+    public function testInitializeManagementClient(): void
+    {
+        $client = new ManagementApiClient(
+            personalAccessToken: "aaa",
+            region: Region::EU,
+            baseUri: "",
+            shouldRetry: true,
+        );
+        $httpClient = $client->httpClient();
+        $this->assertInstanceOf(RetryableHttpClient::class, $httpClient);
+
+        $client = new ManagementApiClient(
+            personalAccessToken: "aaa",
+            region: Region::EU,
+            baseUri: "",
+            shouldRetry: false,
+        );
+        $httpClient = $client->httpClient();
+        $this->assertInstanceOf(CurlHttpClient::class, $httpClient);
+
+        $client = ManagementApiClient::init(
+            personalAccessToken: "aaa",
+            region: Region::EU,
+            baseUri: "",
+        );
+        $httpClient = $client->httpClient();
+        $this->assertInstanceOf(CurlHttpClient::class, $httpClient);
+    }
 }
diff --git a/tests/Feature/StoryApiTest.php b/tests/Feature/StoryApiTest.php
diff --git a/tests/Feature/WorkflowStageApiTest.php b/tests/Feature/WorkflowStageApiTest.php
