fix: reconcile the config mapping callback type between BuilderStack and BuilderConfigurator

BuilderStack declared the callback as `array<array-key, string>|null` while
BuilderConfigurator declared it as `(\Closure(mixed): mixed)|null`. Both describe
the same array, dumped into the container by SensiolabsGotenbergExtension, so one
of them had to be wrong — the Closure one was: BuilderStack stores array callables
(`[$enumClass, 'from']`, `[Unit::class, 'parse']`), and the container cannot dump a
closure at all (PhpDumper throws on any object argument). PHPStan never noticed
because the two types only met at compile time, outside analysed code.

Both sides now share a single `BuilderConfigurationMapping` phpstan-type declared on
BuilderConfigurator, honest about what is stored: a static method target on a backed
enum. The invocation destructures it so PHPStan can follow the static call instead of
having to prove an array literal is callable — behaviour is identical, PHP resolved
`[$class, $method]($value)` the same way.

BuilderConfiguratorTest builds the mapping with BuilderStack and feeds it straight
into BuilderConfigurator, so the two shapes now meet in analysed code and cannot
silently drift apart again.

Assisted-by: Claude Code:Opus-5

Author: Marilena Ruffelaere

src/Configurator/BuilderConfigurator.php

@@ -4,11 +4,21 @@
 
 use Sensiolabs\GotenbergBundle\Builder\BuilderInterface;
 
+/**
+ * The mapping is built at compile time by {@see \Sensiolabs\GotenbergBundle\DependencyInjection\BuilderStack} and
+ * dumped into the container, so a callback can only be a static method target — the container cannot dump a closure.
+ *
+ * @phpstan-type BuilderConfigurationMapping array<class-string<BuilderInterface>, array<string, array{
+ *     method: string,
+ *     mustUseVariadic: bool,
+ *     callback: array{class-string<\BackedEnum>, string}|null,
+ * }>>
+ */
 final class BuilderConfigurator
 {
     /**
-     * @param array<class-string<BuilderInterface>, array<string, array{'method': string, 'mustUseVariadic': bool, 'callback': (\Closure(mixed): mixed)|null}>> $configurations
-     * @param array<class-string<BuilderInterface>, array<string, mixed>>                                                                                       $values
+     * @param BuilderConfigurationMapping                                 $configurations
+     * @param array<class-string<BuilderInterface>, array<string, mixed>> $values
      */
     public function __construct(
         private readonly array $configurations,
@@ -28,7 +38,8 @@ public function __invoke(BuilderInterface $builder): void
             }
 
             if (null !== $configurationMap['callback']) {
-                $value = $configurationMap['callback']($value);
+                [$callbackClass, $callbackMethod] = $configurationMap['callback'];
+                $value = $callbackClass::$callbackMethod($value);
             }
 
             if (\is_array($value) && true === $configurationMap['mustUseVariadic']) {

src/DependencyInjection/BuilderStack.php

@@ -5,13 +5,16 @@
 use Sensiolabs\GotenbergBundle\Builder\Attributes\WithBuilderConfiguration;
 use Sensiolabs\GotenbergBundle\Builder\Attributes\WithConfigurationNode;
 use Sensiolabs\GotenbergBundle\Builder\BuilderInterface;
+use Sensiolabs\GotenbergBundle\Configurator\BuilderConfigurator;
 use Sensiolabs\GotenbergBundle\Enumeration\Unit;
 use Sensiolabs\GotenbergBundle\NodeBuilder\ArrayNodeBuilder;
 use Sensiolabs\GotenbergBundle\NodeBuilder\NativeEnumNodeBuilder;
 use Sensiolabs\GotenbergBundle\NodeBuilder\NodeBuilderInterface;
 use Sensiolabs\GotenbergBundle\NodeBuilder\UnitNodeBuilder;
 
 /**
+ * @phpstan-import-type BuilderConfigurationMapping from BuilderConfigurator
+ *
  * @internal
  */
 final class BuilderStack
@@ -27,7 +30,7 @@ final class BuilderStack
     private array $typeReverseMapping = [];
 
     /**
-     * @var array<class-string<BuilderInterface>, array<string, array{'method': string, 'mustUseVariadic': bool, 'callback': array<array-key, string>|null}>>
+     * @var BuilderConfigurationMapping
      */
     private array $configMapping = [];
 
@@ -112,7 +115,7 @@ public function getTypeReverseMapping(): array
     }
 
     /**
-     * @return array<class-string<BuilderInterface>, array<string, array{'method': string, 'mustUseVariadic': bool, 'callback': array<array-key, string>|null}>>
+     * @return BuilderConfigurationMapping
      */
     public function getConfigMapping(): array
     {

tests/Configurator/BuilderConfiguratorTest.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace Sensiolabs\GotenbergBundle\Tests\Configurator;
+
+use Sensiolabs\GotenbergBundle\Builder\Pdf\UrlPdfBuilder;
+use Sensiolabs\GotenbergBundle\Configurator\BuilderConfigurator;
+use Sensiolabs\GotenbergBundle\DependencyInjection\BuilderStack;
+use Sensiolabs\GotenbergBundle\Test\Builder\GotenbergBuilderTestCase;
+use Symfony\Component\Routing\Generator\UrlGenerator;
+use Symfony\Component\Routing\RequestContext;
+use Symfony\Component\Routing\RouteCollection;
+
+/**
+ * The mapping the extension dumps into the container is the very one the configurator consumes. Building it with
+ * BuilderStack and feeding it straight into BuilderConfigurator makes both declared shapes meet in analysed code,
+ * so they cannot drift apart again without PHPStan noticing.
+ *
+ * @extends GotenbergBuilderTestCase<UrlPdfBuilder>
+ */
+final class BuilderConfiguratorTest extends GotenbergBuilderTestCase
+{
+    protected function createBuilder(): UrlPdfBuilder
+    {
+        $this->container->set('router', new UrlGenerator(new RouteCollection(), new RequestContext()));
+
+        return (new UrlPdfBuilder())->url('https://example.com');
+    }
+
+    public function testEnumConfigurationValuesAreConvertedThroughTheirEnumClass(): void
+    {
+        $this->configure([
+            'pdf_format' => 'PDF/A-1b',
+            'emulated_media_type' => 'screen',
+        ]);
+
+        $this->getBuilder()->generate();
+
+        $this->assertGotenbergFormData('pdfa', 'PDF/A-1b');
+        $this->assertGotenbergFormData('emulatedMediaType', 'screen');
+    }
+
+    public function testUnitConfigurationValuesAreParsedAndSpreadOverTheMethodArguments(): void
+    {
+        $this->configure([
+            'paper_width' => '21cm',
+            'margin_top' => 4.5,
+        ]);
+
+        $this->getBuilder()->generate();
+
+        $this->assertGotenbergFormData('paperWidth', '21cm');
+        $this->assertGotenbergFormData('marginTop', '4.5in');
+    }
+
+    /**
+     * @param array<string, mixed> $values
+     */
+    private function configure(array $values): void
+    {
+        $builderStack = new BuilderStack();
+        $builderStack->push(UrlPdfBuilder::class);
+
+        $configurator = new BuilderConfigurator($builderStack->getConfigMapping(), [UrlPdfBuilder::class => $values]);
+        $configurator($this->getBuilder());
+    }
+}