[Notifier] [DX] Dsn::getRequiredOption()

Author: OskarStark

CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG
 
  * The component is not marked as `@experimental` anymore
 * [BC BREAK] Changed the return type of `AbstractTransportFactory::getEndpoint()` from `?string` to `string`
+ * Added `DSN::getRequiredOption` method which throws a new `MissingRequiredOptionException`.
 
 5.2.0
 -----

Exception/MissingRequiredOptionException.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Notifier\Exception;
+
+/**
+ * @author Oskar Stark <oskarstark@googlemail.com>
+ *
+ * @experimental in 5.3
+ */
+class MissingRequiredOptionException extends IncompleteDsnException
+{
+    public function __construct(string $option, string $dsn = null, ?\Throwable $previous = null)
+    {
+        $message = sprintf('The option "%s" is required but missing.', $option);
+
+        parent::__construct($message, $dsn, $previous);
+    }
+}

Tests/Transport/DsnTest.php

@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Notifier\Exception\InvalidArgumentException;
+use Symfony\Component\Notifier\Exception\MissingRequiredOptionException;
 use Symfony\Component\Notifier\Transport\Dsn;
 
 final class DsnTest extends TestCase
@@ -120,4 +121,54 @@ public function testGetOption()
         $this->assertSame('default', $dsn->getOption('nullable', 'default'));
         $this->assertSame('default', $dsn->getOption('not_existent_property', 'default'));
     }
+
+    public function testGetRequiredOptionGetsOptionIfSet()
+    {
+        $options = ['with_value' => 'some value'];
+        $dsn = new Dsn('scheme', 'localhost', 'u$er', 'pa$s', '8000', $options, '/channel');
+
+        $this->assertSame('some value', $dsn->getRequiredOption('with_value'));
+    }
+
+    public function testGetRequiredOptionGetsOptionIfValueIsZero()
+    {
+        $options = ['timeout' => 0];
+        $dsn = new Dsn('scheme', 'localhost', 'u$er', 'pa$s', '8000', $options, '/channel');
+
+        $this->assertSame(0, $dsn->getRequiredOption('timeout'));
+    }
+
+    /**
+     * @dataProvider getRequiredOptionThrowsMissingRequiredOptionExceptionProvider
+     */
+    public function testGetRequiredOptionThrowsMissingRequiredOptionException(string $expectedExceptionMessage, array $options, string $option)
+    {
+        $dsn = new Dsn('scheme', 'localhost', 'u$er', 'pa$s', '8000', $options, '/channel');
+
+        $this->expectException(MissingRequiredOptionException::class);
+        $this->expectExceptionMessage($expectedExceptionMessage);
+
+        $dsn->getRequiredOption($option);
+    }
+
+    public function getRequiredOptionThrowsMissingRequiredOptionExceptionProvider(): iterable
+    {
+        yield [
+            'The option "foo_bar" is required but missing.',
+            ['with_value' => 'some value'],
+            'foo_bar',
+        ];
+
+        yield [
+            'The option "with_empty_string" is required but missing.',
+            ['with_empty_string' => ''],
+            'with_empty_string',
+        ];
+
+        yield [
+            'The option "with_null" is required but missing.',
+            ['with_null' => null],
+            'with_null',
+        ];
+    }
 }

Tests/TransportFactoryTestCase.php

@@ -14,6 +14,7 @@
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Notifier\Exception\IncompleteDsnException;
 use Symfony\Component\Notifier\Exception\UnsupportedSchemeException;
+use Symfony\Component\Notifier\Exception\MissingRequiredOptionException;
 use Symfony\Component\Notifier\Transport\Dsn;
 use Symfony\Component\Notifier\Transport\TransportFactoryInterface;
 
@@ -52,6 +53,14 @@ public function incompleteDsnProvider(): iterable
         return [];
     }
 
+    /**
+     * @return iterable<array{0: string, 1: string|null}>
+     */
+    public function missingRequiredOptionProvider(): iterable
+    {
+        return [];
+    }
+
     /**
      * @dataProvider supportsProvider
      */
@@ -106,4 +115,21 @@ public function testIncompleteDsnException(string $dsn, string $message = null)
 
         $factory->create($dsn);
     }
+
+    /**
+     * @dataProvider missingRequiredOptionProvider
+     */
+    public function testMissingRequiredOptionException(string $dsn, string $message = null): void
+    {
+        $factory = $this->createFactory();
+
+        $dsn = Dsn::fromString($dsn);
+
+        $this->expectException(MissingRequiredOptionException::class);
+        if (null !== $message) {
+            $this->expectExceptionMessage($message);
+        }
+
+        $factory->create($dsn);
+    }
 }

Transport/Dsn.php

@@ -12,6 +12,7 @@
 namespace Symfony\Component\Notifier\Transport;
 
 use Symfony\Component\Notifier\Exception\InvalidArgumentException;
+use Symfony\Component\Notifier\Exception\MissingRequiredOptionException;
 
 /**
  * @author Fabien Potencier <fabien@symfony.com>
@@ -94,6 +95,15 @@ public function getOption(string $key, $default = null)
         return $this->options[$key] ?? $default;
     }
 
+    public function getRequiredOption(string $key)
+    {
+        if (!\array_key_exists($key, $this->options) || '' === trim($this->options[$key])) {
+            throw new MissingRequiredOptionException($key);
+        }
+
+        return $this->options[$key];
+    }
+
     public function getPath(): ?string
     {
         return $this->path;

Transport/TransportFactoryInterface.php

@@ -12,6 +12,7 @@
 namespace Symfony\Component\Notifier\Transport;
 
 use Symfony\Component\Notifier\Exception\IncompleteDsnException;
+use Symfony\Component\Notifier\Exception\MissingRequiredOptionException;
 use Symfony\Component\Notifier\Exception\UnsupportedSchemeException;
 
 /**
@@ -22,6 +23,7 @@ interface TransportFactoryInterface
     /**
      * @throws UnsupportedSchemeException
      * @throws IncompleteDsnException
+     * @throws MissingRequiredOptionException
      */
     public function create(Dsn $dsn): TransportInterface;