Route the remaining ResultSet and Container throw sites through named constructors

The last 5 throw sites outside the components covered by #191 to #194. Message
text is byte-identical, verified template by template against the originals.

- Add ResultSet\Exception\RuntimeException::forUnbufferedIteration()
- Add forNonAdapterAwareDelegate() to Exception\ContainerException, and give
  the three reasons that AdapterInterfaceFactory and
  AbstractAdapterInterfaceFactory passed as inline strings their own factories:
  forMissingConfigService(), forMissingConfiguration() and forMissingDriver(),
  each composing the reason into the SERVICE template
- Retype the delegator's non-AdapterAware guard from the root
  Exception\RuntimeException to ContainerException, which extends it, so the
  failure carries PSR-11's ContainerExceptionInterface as a container failure
  should
- Own the "not found in container" wording as ContainerException::MISSING_SERVICE
  while still throwing the ServiceManager's own ServiceNotFoundException. Laminas
  annotates that class @Final, so this package cannot own it; the throw site
  renders the template itself, which docs/book/exceptions.md now records as the
  single documented exception to the convention
- Derive the message assertions in the six test files the earlier PRs do not
  touch from the templates rather than restating them

One literal assertion is deliberately left in
test/unit/Container/TableIdentifierFactoryFactoryTest.php: it asserts
Sql\Exception\InvalidArgumentException::EMPTY_SEPARATOR, a constant #192
introduces, so it can only be migrated once that has landed.

Signed-off-by: Simon Mundy <simon.mundy@peptolab.com>

Author: simon-mundy

docs/book/exceptions.md

@@ -64,6 +64,14 @@ a named constructor cannot:
 
 Everything else is a named constructor on the component's SPL-shaped class.
 
+### The one exception to the rule
+
+`PhpDb\Container\AdapterInterfaceDelegator` renders a template at the throw site rather than
+calling a named constructor. The ServiceManager decides the type it must throw, and Laminas
+annotates `ServiceNotFoundException` `@final`, so this package cannot own the class. It owns
+the wording instead, as `PhpDb\Exception\ContainerException::MISSING_SERVICE`. Anywhere the
+thrown type is ours, the rule above applies without exception.
+
 ## Component namespaces
 
 There is exactly one marker interface, `PhpDb\Exception\ExceptionInterface`, and every

src/Container/AbstractAdapterInterfaceFactory.php

@@ -88,11 +88,7 @@ public function __invoke(
         $driverClass = $this->config[$requestedName]['driver'] ?? null;
 
         if (null === $driverClass) {
-            throw ContainerException::forService(
-                $requestedName,
-                self::class,
-                'no driver configured',
-            );
+            throw ContainerException::forMissingDriver($requestedName, self::class);
         }
 
         /** @var DriverInterface|PdoDriverInterface $driver */

src/Container/AdapterInterfaceDelegator.php

@@ -7,7 +7,7 @@
 use Laminas\ServiceManager\Exception\ServiceNotFoundException;
 use PhpDb\Adapter\AdapterAwareInterface;
 use PhpDb\Adapter\AdapterInterface;
-use PhpDb\Exception;
+use PhpDb\Exception\ContainerException;
 use Psr\Container\ContainerExceptionInterface;
 use Psr\Container\ContainerInterface;
 use Psr\Container\NotFoundExceptionInterface;
@@ -33,18 +33,11 @@ public function __invoke(
         $instance = $callback();
 
         if (! $instance instanceof AdapterAwareInterface) {
-            throw new Exception\RuntimeException(sprintf(
-                'Delegated service "%s" must implement %s',
-                $name,
-                AdapterAwareInterface::class,
-            ));
+            throw ContainerException::forNonAdapterAwareDelegate($name, AdapterAwareInterface::class);
         }
 
         if (! $container->has($this->adapterName)) {
-            throw new ServiceNotFoundException(sprintf(
-                'Service "%s" not found in container',
-                $this->adapterName,
-            ));
+            throw new ServiceNotFoundException(sprintf(ContainerException::MISSING_SERVICE, $this->adapterName));
         }
 
         $databaseAdapter = $container->get($this->adapterName);

src/Container/AdapterInterfaceFactory.php

@@ -23,22 +23,14 @@ public function __invoke(
         string $requestedName,
     ): AdapterInterface&Adapter {
         if (! $container->has('config')) {
-            throw ContainerException::forService(
-                $requestedName,
-                self::class,
-                'Container is missing a config service',
-            );
+            throw ContainerException::forMissingConfigService($requestedName, self::class);
         }
 
         $config        = $container->get('config') ?? [];
         $adapterConfig = $config[AdapterInterface::class] ?? $config[Adapter::class] ?? [];
 
         if ([] === $adapterConfig) {
-            throw ContainerException::forService(
-                AdapterInterface::class,
-                self::class,
-                "No configuration found for {$requestedName}",
-            );
+            throw ContainerException::forMissingConfiguration(AdapterInterface::class, self::class, $requestedName);
         }
 
         /** @var class-string<DriverInterface>|class-string<PdoDriverInterface>|null $driverClass */

src/Exception/ContainerException.php

@@ -10,8 +10,46 @@
 
 final class ContainerException extends RuntimeException implements ContainerExceptionInterface
 {
+    /**
+     * The ServiceManager dictates the thrown type here, and Laminas annotates
+     * ServiceNotFoundException @final, so this package owns the wording without owning the
+     * class.
+     */
+    final public const string MISSING_SERVICE = 'Service "%s" not found in container';
+
+    final public const string MISSING_CONFIGURATION = 'No configuration found for %s';
+
+    final public const string MISSING_CONFIG_SERVICE = 'Container is missing a config service';
+
+    final public const string MISSING_DRIVER = 'no driver configured';
+
+    final public const string NON_ADAPTER_AWARE_DELEGATE = 'Delegated service "%s" must implement %s';
+
     final public const string SERVICE = 'Failed to create service "%s" in factory %s Reason: %s';
 
+    public static function forMissingConfigService(string $serviceName, string $factoryClass): self
+    {
+        return self::forService($serviceName, $factoryClass, self::MISSING_CONFIG_SERVICE);
+    }
+
+    public static function forMissingConfiguration(
+        string $serviceName,
+        string $factoryClass,
+        string $requestedName,
+    ): self {
+        return self::forService($serviceName, $factoryClass, sprintf(self::MISSING_CONFIGURATION, $requestedName));
+    }
+
+    public static function forMissingDriver(string $serviceName, string $factoryClass): self
+    {
+        return self::forService($serviceName, $factoryClass, self::MISSING_DRIVER);
+    }
+
+    public static function forNonAdapterAwareDelegate(string $name, string $interface): self
+    {
+        return new self(sprintf(self::NON_ADAPTER_AWARE_DELEGATE, $name, $interface));
+    }
+
     public static function forService(
         string $serviceName,
         string $factoryClass,

src/ResultSet/AbstractResultSet.php

@@ -45,7 +45,7 @@ abstract class AbstractResultSet implements ResultSetInterface
     public function buffer(): ResultSetInterface
     {
         if ($this->buffer === -2) {
-            throw new RuntimeException('Buffering must be enabled before iteration is started');
+            throw RuntimeException::forUnbufferedIteration();
         } elseif ($this->buffer === null) {
             $this->buffer = [];
             if ($this->dataSource instanceof ResultInterface) {

src/ResultSet/Exception/RuntimeException.php

@@ -6,4 +6,12 @@
 
 use PhpDb\Exception;
 
-class RuntimeException extends Exception\RuntimeException {}
+class RuntimeException extends Exception\RuntimeException
+{
+    final public const string UNBUFFERED_ITERATION = 'Buffering must be enabled before iteration is started';
+
+    public static function forUnbufferedIteration(): self
+    {
+        return new self(self::UNBUFFERED_ITERATION);
+    }
+}

test/unit/Adapter/Container/AbstractAdapterInterfaceFactoryTest.php

@@ -93,7 +93,7 @@ public function testGetConfigReturnsEmptyWhenContainerHasNoConfig(): void
     #[DataProvider('providerInvalidService')]
     public function testInvalidService(string $service): void
     {
-        $this->expectException(ServiceNotFoundException::class);
+        self::expectException(ServiceNotFoundException::class);
         $this->serviceManager->get($service);
     }
 
@@ -111,8 +111,8 @@ public function testInvokeThrowsWhenDriverNotConfigured(): void
         $factory = new AbstractAdapterInterfaceFactory();
         $factory->canCreate($container, 'PhpDb\Adapter\NoDriver');
 
-        $this->expectException(ContainerException::class);
-        $this->expectExceptionMessage('no driver configured');
+        self::expectException(ContainerException::class);
+        self::expectExceptionMessage(ContainerException::MISSING_DRIVER);
         $factory($container, 'PhpDb\Adapter\NoDriver');
     }
 

test/unit/Adapter/Container/AdapterInterfaceDelegatorTest.php

@@ -8,10 +8,12 @@
 use Laminas\ServiceManager\Exception\ServiceNotFoundException;
 use Laminas\ServiceManager\ServiceManager;
 use PhpDb\Adapter\Adapter;
+use PhpDb\Adapter\AdapterAwareInterface;
 use PhpDb\Adapter\AdapterInterface;
 use PhpDb\Adapter\Driver\DriverInterface;
 use PhpDb\Adapter\Platform\PlatformInterface;
 use PhpDb\Container\AdapterInterfaceDelegator;
+use PhpDb\Exception\ContainerException;
 use PhpDb\Exception\RuntimeException;
 use PhpDb\ResultSet\ResultSetInterface;
 use PhpDbTest\Adapter\TestAsset\ConcreteAdapterAwareObject;
@@ -24,6 +26,8 @@
 use Psr\Container\NotFoundExceptionInterface;
 use stdClass;
 
+use function sprintf;
+
 #[Group('unit')]
 #[CoversMethod(AdapterInterfaceDelegator::class, '__construct')]
 #[CoversMethod(AdapterInterfaceDelegator::class, '__set_state')]
@@ -247,8 +251,8 @@ public function testSetAdapterShouldNotBeCalledForMissingAdapter(): void
 
         $callback = static fn(): ConcreteAdapterAwareObject => new ConcreteAdapterAwareObject();
 
-        $this->expectException(ServiceNotFoundException::class);
-        $this->expectExceptionMessage('Service "PhpDb\Adapter\AdapterInterface" not found in container');
+        self::expectException(ServiceNotFoundException::class);
+        self::expectExceptionMessage(sprintf(ContainerException::MISSING_SERVICE, AdapterInterface::class));
 
         (new AdapterInterfaceDelegator())(
             $container,
@@ -268,10 +272,12 @@ public function testSetAdapterShouldNotBeCalledForWrongClassInstance(): void
 
         $callback = static fn(): stdClass => new stdClass();
 
-        $this->expectException(RuntimeException::class);
-        $this->expectExceptionMessage(
-            'Delegated service "stdClass" must implement PhpDb\Adapter\AdapterAwareInterface',
-        );
+        self::expectException(RuntimeException::class);
+        self::expectExceptionMessage(sprintf(
+            ContainerException::NON_ADAPTER_AWARE_DELEGATE,
+            stdClass::class,
+            AdapterAwareInterface::class,
+        ));
 
         (new AdapterInterfaceDelegator())(
             $container,

test/unit/Container/AdapterInterfaceFactoryTest.php

@@ -111,8 +111,8 @@ public function testInvokeThrowsWhenAdapterConfigIsEmpty(): void
 
         $factory = new AdapterInterfaceFactory();
 
-        $this->expectException(ContainerException::class);
-        $this->expectExceptionMessage('No configuration found for');
+        self::expectException(ContainerException::class);
+        self::expectExceptionMessage('No configuration found for');
         $factory($container, AdapterInterface::class);
     }
 
@@ -130,8 +130,8 @@ public function testInvokeThrowsWhenContainerHasNoConfig(): void
 
         $factory = new AdapterInterfaceFactory();
 
-        $this->expectException(ContainerException::class);
-        $this->expectExceptionMessage('Container is missing a config service');
+        self::expectException(ContainerException::class);
+        self::expectExceptionMessage(ContainerException::MISSING_CONFIG_SERVICE);
         $factory($container, AdapterInterface::class);
     }
 }