#64 - Deprecate the configuration keys, ignored without notice (no Configuration)

CHANGELOG.md

@@ -2,6 +2,7 @@ Latest
 ------
 
 ### Changes
+* [#64](https://github.com/cleverage/soap-process-bundle/issues/64) Configuring a key under `clever_age_soap_process` is deprecated: the bundle has no configuration and the keys were ignored without notice (new internal `Configuration`, empty; notice when the container is compiled). They will be rejected in 4.0. Require `symfony/deprecation-contracts`, used directly. Update documentation, add tests.
 * [#62](https://github.com/cleverage/soap-process-bundle/issues/62) The bundle throws exceptions implementing `ProcessExceptionInterface` of the process bundle instead of raw SPL exceptions (as [cleverage/process-bundle#317](https://github.com/cleverage/process-bundle/issues/317)): new `Exception\UnexpectedValueException`, `Exception\InvalidArgumentException` and `Exception\RuntimeException`, extending the SPL exceptions thrown before (same messages, the existing `catch` keep working). Add tests.
 * [#60](https://github.com/cleverage/soap-process-bundle/issues/60) Composer: require PHP `^8.2` instead of `>=8.2` (PHP 9 is no longer accepted before being tested), remove the authorization of the `symfony/flex` plugin, which is not required (the CI installs it globally), as [cleverage/process-bundle#319](https://github.com/cleverage/process-bundle/issues/319).
 * [#55](https://github.com/cleverage/soap-process-bundle/issues/55) Define the public API (Symfony BC promise, as [cleverage/process-bundle#279](https://github.com/cleverage/process-bundle/issues/279)): `RequestTask`, `RequestTransformer`, `ClientRegistry` and `CleverAgeSoapProcessBundle` are marked `@final since 3.3`, they will be `final` in 4.0: extending them triggers a deprecation with the Symfony `DebugClassLoader`. `Client` (extended by the applications) and `MissingClientException` stay open. `CleverAgeSoapProcessExtension` and `RegisterClientsPass` are marked `@internal`.

composer.json

@@ -55,6 +55,7 @@
         "psr/log": "^2|^3",
         "symfony/config": "^6.4|^7.4|^8",
         "symfony/dependency-injection": "^6.4|^7.4|^8",
+        "symfony/deprecation-contracts": "^2.5|^3",
         "symfony/http-kernel": "^6.4|^7.4|^8",
         "symfony/options-resolver": "^6.4|^7.4|^8",
         "symfony/polyfill-php83": "^1.33",

docs/index.md

@@ -55,6 +55,8 @@ The service id of the task and of the transformer is their class name. Fetching
 is deprecated since 3.3 (they will be private in 4.0); their former ids, `cleverage_soap_process.task.request` and
 `cleverage_soap_process.transformer.request`, are deprecated aliases since 3.3, removed in 4.0.
 
+No option can be configured under `clever_age_soap_process`: a key there is ignored. Configuring one is deprecated since 3.3 (an `E_USER_DEPRECATED` error is triggered when the container is compiled), the keys will be rejected in 4.0.
+
 ## Reference
 
 - [Client](reference/client.md)

src/DependencyInjection/CleverAgeSoapProcessExtension.php

@@ -31,6 +31,18 @@ class CleverAgeSoapProcessExtension extends Extension
 {
     public function load(array $configs, ContainerBuilder $container): void
     {
+        $keys = array_keys(array_merge(...$configs));
+        if ([] !== $keys) {
+            trigger_deprecation(
+                'cleverage/soap-process-bundle',
+                '3.3',
+                'Configuring "%s" is deprecated, the bundle has no configuration: the keys "%s" are ignored. They will be rejected in 4.0.',
+                $this->getAlias(),
+                implode('", "', $keys),
+            );
+        }
+        $this->processConfiguration(new Configuration(), $configs);
+
         $this->findServices($container, __DIR__.'/../../config/services');
 
         $container->registerAttributeForAutoconfiguration(

src/DependencyInjection/Configuration.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the CleverAge/SoapProcessBundle package.
+ *
+ * Copyright (c) Clever-Age
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CleverAge\SoapProcessBundle\DependencyInjection;
+
+use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+use Symfony\Component\Config\Definition\ConfigurationInterface;
+
+/**
+ * The bundle has no option: the configured keys are ignored with a deprecation (see CleverAgeSoapProcessExtension::load()), they will be
+ * rejected in 4.0.
+ *
+ * @internal
+ */
+final class Configuration implements ConfigurationInterface
+{
+    public function getConfigTreeBuilder(): TreeBuilder
+    {
+        $treeBuilder = new TreeBuilder('clever_age_soap_process');
+        /** @var ArrayNodeDefinition $rootNode */
+        $rootNode = $treeBuilder->getRootNode();
+        $rootNode->ignoreExtraKeys();
+
+        return $treeBuilder;
+    }
+}

tests/DependencyInjection/CleverAgeSoapProcessExtensionTest.php

@@ -15,6 +15,7 @@
 
 use CleverAge\SoapProcessBundle\Attribute\AsSoapClient;
 use CleverAge\SoapProcessBundle\DependencyInjection\CleverAgeSoapProcessExtension;
+use CleverAge\SoapProcessBundle\DependencyInjection\Configuration;
 use CleverAge\SoapProcessBundle\Registry\ClientRegistry;
 use CleverAge\SoapProcessBundle\Task\RequestTask;
 use CleverAge\SoapProcessBundle\Tests\Fixtures\AttributedClient;
@@ -31,6 +32,7 @@
 use Symfony\Component\Yaml\Yaml;
 
 #[CoversClass(CleverAgeSoapProcessExtension::class)]
+#[CoversClass(Configuration::class)]
 #[UsesClass(RequestTransformer::class)]
 #[CoversClass(AsSoapClient::class)]
 #[UsesClass(ClientRegistry::class)]
@@ -166,4 +168,52 @@ private function assertDeprecatedAlias(ContainerBuilder $container, string $id,
             $alias->getDeprecation($id)
         );
     }
+
+    public function testConfigurationKeysAreDeprecated(): void
+    {
+        $deprecations = $this->collectDeprecations(static function (): void {
+            (new CleverAgeSoapProcessExtension())->load([[], ['foo' => true], ['bar' => 1, 'foo' => false]], new ContainerBuilder());
+        });
+
+        self::assertSame(['Since cleverage/soap-process-bundle 3.3: Configuring "clever_age_soap_process" is deprecated, the bundle has no configuration: the keys "foo", "bar" are ignored. They will be rejected in 4.0.'], $deprecations);
+    }
+
+    public function testNoDeprecationWithoutConfigurationKey(): void
+    {
+        $deprecations = $this->collectDeprecations(static function (): void {
+            (new CleverAgeSoapProcessExtension())->load([[], []], new ContainerBuilder());
+        });
+
+        self::assertSame([], $deprecations);
+    }
+
+    public function testConfigurationHasNoOption(): void
+    {
+        $configuration = (new CleverAgeSoapProcessExtension())->getConfiguration([], new ContainerBuilder());
+
+        self::assertInstanceOf(Configuration::class, $configuration);
+        self::assertSame('clever_age_soap_process', $configuration->getConfigTreeBuilder()->buildTree()->getName());
+    }
+
+    /**
+     * @param callable(): void $callback
+     *
+     * @return list<string>
+     */
+    private function collectDeprecations(callable $callback): array
+    {
+        $deprecations = [];
+        set_error_handler(static function (int $errno, string $errstr) use (&$deprecations): bool {
+            $deprecations[] = $errstr;
+
+            return true;
+        }, \E_USER_DEPRECATED);
+        try {
+            $callback();
+        } finally {
+            restore_error_handler();
+        }
+
+        return $deprecations;
+    }
 }