Speed up URL/tag generation via Configuration clone fast-path

const-cloudinary · const-cloudinary · commit a0a334b9ee3c · 2026-04-26T18:57:02.000+03:00
Reduce per-asset/per-tag Configuration construction overhead and tighten
a few hot paths exercised by URL building.

- Add Configuration::__clone() that deep-clones every section so cloning the
  global singleton produces a fully independent working copy without the
  cost of a JSON import/export round-trip.
- Use the clone fast-path in BaseAsset::fromParams,
  BaseTag::configuration (replaces a pre-existing TODO), and
  BaseTag::fromParamsDefaultConfig instead of new Configuration(...).
- Memoize BaseConfigSection::exportableKeys() per (class, sensitivity) to
  eliminate repeated ReflectionClass::getConstants() calls on every config
  serialization.
- Replace array_values(section)[0] with current(section) in the two
  jsonSerialize implementations.

Add tests/Unit/Configuration/ConfigurationCloneTest.php to lock in clone
isolation across all configuration sections and across the asset/tag
fast-paths, so a future regression to a shallow copy fails loudly.
diff --git a/src/Asset/BaseAsset.php b/src/Asset/BaseAsset.php
@@ -199,7 +199,7 @@ public static function fromParams(string $source, array $params): static
         $params['public_id'] = $source;
 
         $asset         = AssetDescriptor::fromParams($source, $params);
-        $configuration = new Configuration(Configuration::instance());
+        $configuration = clone Configuration::instance();
 
         # set v1 defaults
         if (! $configuration->url->isExplicitlySet('secure')) {
@@ -377,7 +377,7 @@ public function jsonSerialize(bool $includeEmptyKeys = false, bool $includeEmpty
 
         foreach ([$this->cloud, $this->urlConfig] as $confSection) {
             $section = $confSection->jsonSerialize(false, $includeEmptyKeys, $includeEmptySections);
-            if (! $includeEmptySections && empty(array_values($section)[0])) {
+            if (! $includeEmptySections && empty(current($section))) {
                 continue;
             }
             $json += $section;
diff --git a/src/Configuration/BaseConfigSection.php b/src/Configuration/BaseConfigSection.php
@@ -43,6 +43,11 @@ abstract class BaseConfigSection implements ConfigurableInterface
      */
     protected array $explicitlySetKeys = [];
 
+    /**
+     * @var array<string, array>
+     */
+    private static array $exportableKeysCache = [];
+
 
     /**
      * BaseConfig constructor.
@@ -195,12 +200,17 @@ public function assertNotEmpty(array $keys): void
      */
     protected static function exportableKeys(bool $includeSensitive = true): array
     {
+        $cacheKey = static::class . ($includeSensitive ? ':1' : ':0');
+        if (isset(self::$exportableKeysCache[$cacheKey])) {
+            return self::$exportableKeysCache[$cacheKey];
+        }
+
         $blacklisted = [static::CONFIG_NAME];
         if (! $includeSensitive) {
             $blacklisted = array_merge($blacklisted, static::$sensitiveDataKeys);
         }
 
-        return array_filter(
+        return self::$exportableKeysCache[$cacheKey] = array_filter(
             ClassUtils::getConstants(static::class, $blacklisted),
             static fn($key) => ! empty($key) && is_string($key)
         );
diff --git a/src/Configuration/Configuration.php b/src/Configuration/Configuration.php
@@ -118,6 +118,17 @@ public function __construct(Configuration|array|string|null $config = null, bool
         $this->init($config, $includeSensitive);
     }
 
+    public function __clone(): void
+    {
+        $this->cloud                 = clone $this->cloud;
+        $this->api                   = clone $this->api;
+        $this->url                   = clone $this->url;
+        $this->tag                   = clone $this->tag;
+        $this->responsiveBreakpoints = clone $this->responsiveBreakpoints;
+        $this->authToken             = clone $this->authToken;
+        $this->logging               = clone $this->logging;
+    }
+
     /**
      * Configuration initializer.
      *
@@ -328,7 +339,7 @@ public function jsonSerialize(
         foreach ($this->sections as $section) {
             $section = StringUtils::snakeCaseToCamelCase($section);
             $section = $this->$section->jsonSerialize($includeSensitive, $includeEmptyKeys);
-            if (! $includeEmptySections && empty(array_values($section)[0])) {
+            if (! $includeEmptySections && empty(current($section))) {
                 continue;
             }
             $json += $section;
diff --git a/src/Tag/BaseTag.php b/src/Tag/BaseTag.php
@@ -86,8 +86,13 @@ public function __construct(Configuration|array|string|null $configuration = nul
      */
     public function configuration(Configuration|array|string|null $configuration): Configuration
     {
-        $tempConfiguration = new Configuration($configuration); // TODO: improve performance here
-        $this->config      = $tempConfiguration;
+        if ($configuration instanceof Configuration) {
+            $tempConfiguration = clone $configuration;
+        } else {
+            $tempConfiguration = new Configuration($configuration);
+        }
+
+        $this->config = $tempConfiguration;
 
         return $tempConfiguration;
     }
@@ -339,7 +344,7 @@ protected static function collectAttributesFromParams(array $params): array
      */
     protected static function fromParamsDefaultConfig(): Configuration
     {
-        $configuration = new Configuration(Configuration::instance());
+        $configuration = clone Configuration::instance();
         # set v1 defaults
         $configuration->tag->quotesType       = self::SINGLE_QUOTES;
         $configuration->tag->sortAttributes   = true;
diff --git a/tests/Unit/Configuration/ConfigurationCloneTest.php b/tests/Unit/Configuration/ConfigurationCloneTest.php
@@ -0,0 +1,147 @@
+<?php
+/**
+ * This file is part of the Cloudinary PHP package.
+ *
+ * (c) Cloudinary
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cloudinary\Test\Unit\Configuration;
+
+use Cloudinary\Asset\Image;
+use Cloudinary\Configuration\Configuration;
+use Cloudinary\Tag\ImageTag;
+use Cloudinary\Test\Unit\UnitTestCase;
+
+/**
+ * Verifies that cloning a Configuration (and the clone fast-paths in BaseAsset / BaseTag /
+ * fromParams) produces a fully independent copy.
+ *
+ * If any of these tests fail, mutations on a per-asset / per-tag working copy can leak back
+ * into the global Configuration::instance() singleton.
+ */
+class ConfigurationCloneTest extends UnitTestCase
+{
+    public function testCloneCopiesEverySectionAsDistinctObject()
+    {
+        $source = Configuration::instance();
+        $clone  = clone $source;
+
+        self::assertNotSame($source, $clone);
+        self::assertNotSame($source->cloud, $clone->cloud);
+        self::assertNotSame($source->api, $clone->api);
+        self::assertNotSame($source->url, $clone->url);
+        self::assertNotSame($source->tag, $clone->tag);
+        self::assertNotSame($source->responsiveBreakpoints, $clone->responsiveBreakpoints);
+        self::assertNotSame($source->authToken, $clone->authToken);
+        self::assertNotSame($source->logging, $clone->logging);
+    }
+
+    public function testCloneMutationsDoNotLeakIntoSource()
+    {
+        $source = Configuration::instance();
+        $clone  = clone $source;
+
+        $originals = [
+            'cloudName'       => $source->cloud->cloudName,
+            'secure'          => $source->url->secure,
+            'cname'           => $source->url->cname,
+            'sortAttributes'  => $source->tag->sortAttributes,
+            'authTokenKey'    => $source->authToken->key,
+            'loggingLevel'    => $source->logging->level,
+            'apiProxy'        => $source->api->apiProxy,
+            'breakpoints'     => $source->responsiveBreakpoints->breakpoints,
+        ];
+
+        $clone->cloud->cloudName              = 'mutated_cloud';
+        $clone->url->secure                   = ! (bool) $originals['secure'];
+        $clone->url->cname                    = 'clone.example.com';
+        $clone->tag->sortAttributes           = ! (bool) $originals['sortAttributes'];
+        $clone->authToken->key                = '00112233445566778899aabbccddeeff';
+        $clone->logging->level                = 'critical';
+        $clone->api->apiProxy                 = 'http://proxy.example.com';
+        $clone->responsiveBreakpoints->breakpoints = [100, 200, 300];
+
+        self::assertEquals($originals['cloudName'], $source->cloud->cloudName);
+        self::assertEquals($originals['secure'], $source->url->secure);
+        self::assertEquals($originals['cname'], $source->url->cname);
+        self::assertEquals($originals['sortAttributes'], $source->tag->sortAttributes);
+        self::assertEquals($originals['authTokenKey'], $source->authToken->key);
+        self::assertEquals($originals['loggingLevel'], $source->logging->level);
+        self::assertEquals($originals['apiProxy'], $source->api->apiProxy);
+        self::assertEquals($originals['breakpoints'], $source->responsiveBreakpoints->breakpoints);
+    }
+
+    public function testAssetConstructorClonesGlobalConfig()
+    {
+        $global = Configuration::instance();
+        $image  = new Image('sample.png');
+
+        self::assertNotSame($global->cloud, $image->cloud);
+        self::assertNotSame($global->url, $image->urlConfig);
+        self::assertNotSame($global->logging, $image->logging);
+
+        $originalCloudName = $global->cloud->cloudName;
+        $originalSecure    = $global->url->secure;
+        $originalLevel     = $global->logging->level;
+
+        $image->cloud->cloudName = 'mutated_cloud';
+        $image->urlConfig->secure = ! (bool) $originalSecure;
+        $image->logging->level    = 'critical';
+
+        self::assertEquals($originalCloudName, $global->cloud->cloudName);
+        self::assertEquals($originalSecure, $global->url->secure);
+        self::assertEquals($originalLevel, $global->logging->level);
+    }
+
+    public function testAssetFromParamsDoesNotMutateGlobalConfig()
+    {
+        $global            = Configuration::instance();
+        $originalCloudName = $global->cloud->cloudName;
+        $originalSecure    = $global->url->secure;
+
+        $image = Image::fromParams('sample.png', [
+            'cloud_name' => 'from_params_cloud',
+            'secure'     => true,
+        ]);
+
+        self::assertEquals('from_params_cloud', $image->cloud->cloudName);
+        self::assertEquals($originalCloudName, $global->cloud->cloudName);
+        self::assertEquals($originalSecure, $global->url->secure);
+    }
+
+    public function testTagConstructorClonesGivenConfiguration()
+    {
+        $source = new Configuration(Configuration::instance());
+        $tag    = new ImageTag('sample.jpg', $source);
+
+        self::assertNotSame($source, $tag->config);
+        self::assertNotSame($source->cloud, $tag->config->cloud);
+        self::assertNotSame($source->tag, $tag->config->tag);
+
+        $originalCloudName     = $source->cloud->cloudName;
+        $originalSortAttribute = $source->tag->sortAttributes;
+
+        $tag->config->cloud->cloudName       = 'tag_mutated_cloud';
+        $tag->config->tag->sortAttributes    = ! (bool) $originalSortAttribute;
+
+        self::assertEquals($originalCloudName, $source->cloud->cloudName);
+        self::assertEquals($originalSortAttribute, $source->tag->sortAttributes);
+    }
+
+    public function testTagFromParamsDoesNotMutateGlobalConfig()
+    {
+        $global            = Configuration::instance();
+        $originalCloudName = $global->cloud->cloudName;
+        $originalQuotes    = $global->tag->quotesType;
+
+        ImageTag::fromParams('sample.jpg', [
+            'cloud_name' => 'tag_from_params_cloud',
+        ]);
+
+        self::assertEquals($originalCloudName, $global->cloud->cloudName);
+        self::assertEquals($originalQuotes, $global->tag->quotesType);
+    }
+}
