handle Curl transport & PSR-18 client

guillaume-sainthillier · guillaume-sainthillier · commit 74673b780a4d · 2026-05-28T13:02:04.000+02:00
diff --git a/CHANGELOG-7.0.md b/CHANGELOG-7.0.md
@@ -6,6 +6,10 @@ in 7.x versions.
 
 ### 7.1.1 (2026-xx-xx)
 * Added Elasticsearch 9 and Elastica 9 support.
+* `headers` client config is now applied via `Transport::setHeader()` so it works uniformly across Guzzle, Symfony HTTP Client, and elastic-transport's bundled Curl client.
+* `timeout` client config is now translated to `CURLOPT_TIMEOUT` at runtime when the active transport client is elastic-transport's bundled Curl — Guzzle/Symfony HTTP Client keep consuming the original `'timeout'` key as before.
+* Default config no longer injects `'headers' => []` / `'timeout' => 30` into `http_client_options`, which would otherwise break elastic-transport's bundled Curl client (PHP 8+ `ValueError` on unknown `curl_setopt_array` keys).
+* **Deprecated** the top-level `headers` and `timeout` client config. Move them into `client_options` — for Guzzle/Symfony HTTP Client use `headers` / `timeout`, for the bundled Curl client use `CURLOPT_HTTPHEADER` / `CURLOPT_TIMEOUT`.
 * Fix deprecated Symfony method call.
 * Instantiate custom repositories using the DI service locator.
 * Add compatibility with `doctrine/doctrine-bundle` 3.x, `doctrine/phpcr-odm` 3.x and Symfony 8.0 in highest-deps CI.
diff --git a/composer.json b/composer.json
@@ -59,6 +59,7 @@
         "phpstan/phpstan-symfony": "^1.4",
         "phpunit/phpunit": "^9.5",
         "symfony/expression-language": "^6.4 || ^7.4 || ^8.0",
+        "symfony/http-client": "^6.4 || ^7.4 || ^8.0",
         "symfony/messenger": "^6.4 || ^7.4 || ^8.0",
         "symfony/serializer": "^6.4 || ^7.4 || ^8.0",
         "symfony/twig-bundle": "^6.4 || ^7.4 || ^8.0",
@@ -86,6 +87,7 @@
     "config": {
         "allow-plugins": {
             "ergebnis/composer-normalize": true,
+            "php-http/discovery": true,
             "phpstan/extension-installer": true
         }
     },
diff --git a/doc/cookbook/elastica-http-client-configuration.md b/doc/cookbook/elastica-http-client-configuration.md
@@ -4,10 +4,16 @@ Configuring Elastica HTTP client
 Setting HTTP Headers
 --------------------
 
+> **Deprecated since 7.1**: the top-level `headers` client option is deprecated.
+> Move headers into `client_options` for your HTTP client (`headers` key for
+> Guzzle/Symfony HTTP Client, `CURLOPT_HTTPHEADER` for elastic-transport's
+> bundled Curl client).
+
 It may be necessary to set HTTP headers on the Elastica client, for example an
 Authorization header.
 
-They can be set using the `headers` configuration key:
+They can be set using the deprecated `headers` configuration key (still works,
+applied via `Transport::setHeader` so it covers every HTTP client):
 
 ```yaml
 # app/config/config.yml
@@ -59,7 +65,7 @@ fos_elastica:
 Setting other client options
 --------------------
 
-Any other client option for Elastica client can be set using the `client_options` configuration key:
+`client_options` is a raw pass-through to the underlying HTTP client (Guzzle, Symfony HTTP Client, or elastic-transport's bundled Curl client). Configure it with whatever option names your client understands:
 
 ```yaml
 # app/config/config.yml
@@ -68,7 +74,16 @@ fos_elastica:
         default:
             hosts: ['http://example.com:80']
             client_options:
-              !php/const \CURLOPT_RANDOM_FILE: /dev/urandom
+              # Guzzle / Symfony HTTP Client
+              timeout: 30
+              connect_timeout: 10
               proxy: 'http://localhost:8125'
-              connect_timeout: 10 # if using Guzzle
+
+              # elastic-transport's bundled Curl client (used when neither Guzzle nor
+              # Symfony HTTP Client is installed). Use CURLOPT_* integer keys:
+              !php/const \CURLOPT_TIMEOUT: 30
+              !php/const \CURLOPT_CONNECTTIMEOUT: 10
+              !php/const \CURLOPT_RANDOM_FILE: /dev/urandom
 ```
+
+> **Deprecated since 7.1:** the top-level `timeout` client option is no longer applied — move it into `client_options` for your specific HTTP client (`timeout` for Guzzle/Symfony, `CURLOPT_TIMEOUT` for bundled Curl).
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
@@ -356,12 +356,22 @@ private function addClientsSection(ArrayNodeDefinition $rootNode): void
                                 ->prototype('scalar')->end()
                             ->end()
                             ->arrayNode('headers')
+                                ->setDeprecated(
+                                    'friendsofsymfony/elastica-bundle',
+                                    '7.1',
+                                    'The "%node%" option is deprecated. Configure headers via "client_options" instead — for Guzzle/Symfony HTTP Client use "headers", for elastic-transport\'s bundled Curl client use CURLOPT_HTTPHEADER.',
+                                )
                                 ->normalizeKeys(false)
                                 ->useAttributeAsKey('name')
                                 ->prototype('scalar')->end()
                             ->end()
                             ->scalarNode('timeout')
                                 ->defaultValue(30)
+                                ->setDeprecated(
+                                    'friendsofsymfony/elastica-bundle',
+                                    '7.1',
+                                    'The "%node%" option is deprecated. Configure your HTTP client directly via "client_options" instead — "timeout" for Guzzle/Symfony HTTP Client, CURLOPT_TIMEOUT for elastic-transport\'s bundled Curl client.',
+                                )
                             ->end()
                             ->scalarNode('retry_on_conflict')
                                 ->defaultValue(0)
diff --git a/src/Elastica/Client.php b/src/Elastica/Client.php
@@ -14,6 +14,7 @@
 use Elastic\Elasticsearch\Exception\ClientResponseException;
 use Elastic\Elasticsearch\Exception\ElasticsearchException;
 use Elastic\Elasticsearch\Response\Elasticsearch;
+use Elastic\Transport\Client\Curl;
 use Elastica\Client as BaseClient;
 use Elastica\Exception\ClientException;
 use FOS\ElasticaBundle\Event\ElasticaRequestExceptionEvent;
@@ -36,7 +37,55 @@ class Client extends BaseClient implements ResetInterface
 {
     public function __construct(array|string $config = [], private readonly array $forbiddenCodes = [400, 403, 404], ?LoggerInterface $logger = null)
     {
+        // Reroute deprecated http_client_options.headers via Transport::setHeader so it works for any
+        // PSR-18 client — elastic-transport's bundled Curl client ValueErrors on string keys in curl_setopt_array.
+        $headers = [];
+        if (\is_array($config) && \is_array($config['transport_config']['http_client_options']['headers'] ?? null)) {
+            $headers = $config['transport_config']['http_client_options']['headers'];
+            unset($config['transport_config']['http_client_options']['headers']);
+        }
+
         parent::__construct($config, $logger);
+
+        foreach ($headers as $name => $value) {
+            $this->getTransport()->setHeader($name, $value);
+        }
+
+        $this->translateOptionsForBundledCurl();
+    }
+
+    /**
+     * When the active transport client is elastic-transport's bundled Curl, swap any 'timeout' string
+     * key (deprecated bundle alias) to CURLOPT_TIMEOUT — otherwise curl_setopt_array ValueErrors on
+     * the unknown option.
+     */
+    private function translateOptionsForBundledCurl(): void
+    {
+        if (!\class_exists(Curl::class)) {
+            return;
+        }
+
+        $transportClient = $this->getTransport()->getClient();
+        if (!$transportClient instanceof Curl) {
+            return;
+        }
+
+        $optionsProperty = new \ReflectionProperty($transportClient, 'options');
+        $options = $optionsProperty->getValue($transportClient);
+
+        // `timeout` -> CURLOPT_TIMEOUT
+        if (isset($options['timeout'])) {
+            $options[\CURLOPT_TIMEOUT] = $options['timeout'];
+            unset($options['timeout']);
+        }
+
+        // `connect_timeout` -> CURLOPT_CONNECTTIMEOUT
+        if (isset($options['connect_timeout'])) {
+            $options[\CURLOPT_CONNECTTIMEOUT] = $options['connect_timeout'];
+            unset($options['connect_timeout']);
+        }
+
+        $transportClient->setOptions($options);
     }
 
     /**
diff --git a/tests/Unit/DependencyInjection/FOSElasticaExtensionTest.php b/tests/Unit/DependencyInjection/FOSElasticaExtensionTest.php
@@ -79,6 +79,28 @@ public function testYamlConfiguration(): void
         ], $defaultClientDefinition->getArgument('$config')['transport_config']);
     }
 
+    /**
+     * @group legacy
+     */
+    public function testDeprecatedHeadersAndTimeoutAreMergedIntoHttpClientOptionsForBC(): void
+    {
+        $containerBuilder = new ContainerBuilder();
+        $containerBuilder->registerExtension($extension = new FOSElasticaExtension());
+        $containerBuilder->setParameter('kernel.debug', true);
+
+        $loader = new YamlFileLoader($containerBuilder, new FileLocator(__DIR__.'/fixtures'));
+        $loader->load('deprecated_headers_timeout.yml');
+
+        $extensionConfig = $containerBuilder->getExtensionConfig($extension->getAlias());
+        $extension->load($extensionConfig, $containerBuilder);
+
+        $defaultClientDefinition = $containerBuilder->findDefinition('fos_elastica.client.default');
+        $this->assertSame([
+            'headers' => ['Authorization' => 'Bearer xyz'],
+            'timeout' => 10,
+        ], $defaultClientDefinition->getArgument('$config')['transport_config']['http_client_options']);
+    }
+
     public function testShouldRegisterDoctrineORMPagerProviderIfEnabled(): void
     {
         $container = new ContainerBuilder();
diff --git a/tests/Unit/DependencyInjection/fixtures/deprecated_headers_timeout.yml b/tests/Unit/DependencyInjection/fixtures/deprecated_headers_timeout.yml
@@ -0,0 +1,15 @@
+fos_elastica:
+    clients:
+        default:
+            hosts: [http://localhost:9200]
+            headers:
+                Authorization: 'Bearer xyz'
+            timeout: 10
+    indexes:
+        test_index:
+            client: default
+            properties:
+                text: ~
+            persistence:
+                driver: orm
+                model: foo_model
diff --git a/tests/Unit/Elastica/ClientTest.php b/tests/Unit/Elastica/ClientTest.php
@@ -234,6 +234,63 @@ public function testGetIndexTemplate(): void
         $this->assertSame($template, $client->getIndexTemplate('some_index'));
     }
 
+    /**
+     * Headers arriving via the deprecated http_client_options['headers'] passthrough are
+     * extracted in the constructor and re-applied via Transport::setHeader. This makes
+     * them work uniformly across Guzzle, Symfony HTTP Client, and elastic-transport's
+     * bundled Curl client (which would otherwise ValueError on the string key in
+     * curl_setopt_array).
+     */
+    public function testHeadersFromHttpClientOptionsAreReroutedViaTransport(): void
+    {
+        $client = new Client([
+            'transport_config' => [
+                'http_client_options' => [
+                    'headers' => ['X-Foo' => 'bar', 'Authorization' => 'Bearer xyz'],
+                    'timeout' => 5,
+                ],
+            ],
+        ]);
+
+        $headers = $client->getTransport()->getHeaders();
+        self::assertSame('bar', $headers['X-Foo'] ?? null);
+        self::assertSame('Bearer xyz', $headers['Authorization'] ?? null);
+        // timeout is left in place so the underlying HTTP client (Guzzle/Symfony) can consume it
+        self::assertSame(['timeout' => 5], $client->getConfig()['transport_config']['http_client_options']);
+    }
+
+    /**
+     * When the active transport client is elastic-transport's bundled Curl, the deprecated
+     * 'timeout' string key in http_client_options is translated to CURLOPT_TIMEOUT — otherwise
+     * curl_setopt_array ValueErrors on the unknown option.
+     */
+    public function testTimeoutIsTranslatedToCurlOptForBundledCurl(): void
+    {
+        if (!\class_exists(\Elastic\Transport\Client\Curl::class)) {
+            self::markTestSkipped('Bundled Elastic\Transport\Client\Curl is only available on Elastica 9+.');
+        }
+
+        $client = new Client([
+            'transport_config' => [
+                'http_client' => new \Elastic\Transport\Client\Curl(),
+                'http_client_options' => [
+                    'timeout' => 7,
+                    \CURLOPT_RANDOM_FILE => '/dev/urandom',
+                ],
+            ],
+        ]);
+
+        $transportClient = $client->getTransport()->getClient();
+        self::assertInstanceOf(\Elastic\Transport\Client\Curl::class, $transportClient);
+
+        $optionsProperty = new \ReflectionProperty($transportClient, 'options');
+        $options = $optionsProperty->getValue($transportClient);
+
+        self::assertSame(7, $options[\CURLOPT_TIMEOUT] ?? null);
+        self::assertArrayNotHasKey('timeout', $options);
+        self::assertSame('/dev/urandom', $options[\CURLOPT_RANDOM_FILE] ?? null, 'other curl options must be preserved');
+    }
+
     private function getClient(LoggerInterface $logger, \Nyholm\Psr7\Response $response): Client
     {
         $httpClient = $this->createMock(ClientInterface::class);
