[TASK] Verify service availability when a service is requested

ChangeLog

@@ -1,6 +1,7 @@
 2024-12-07 Francois Suter (Idéative)  <[email protected]>
 
     * Verify compatibility with PHP 8.4
+    * Verify service availability when a service is requested
 
 2024-11-26 Francois Suter (Idéative)  <[email protected]>
 

Classes/Exception/UnavailableServiceException.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cobweb\Svconnector\Exception;
+
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+/**
+ * Exception to throw when an unknown service is requested.
+ */
+class UnavailableServiceException extends ConnectorException {}

Classes/Registry/ConnectorRegistry.php

@@ -18,6 +18,7 @@
 namespace Cobweb\Svconnector\Registry;
 
 use Cobweb\Svconnector\Attribute\AsConnectorService;
+use Cobweb\Svconnector\Exception\UnavailableServiceException;
 use Cobweb\Svconnector\Exception\UnknownServiceException;
 use Cobweb\Svconnector\Service\ConnectorBase;
 
@@ -88,12 +89,22 @@ public function getAllServices(): iterable
      * @param array $parameters Parameters for the connector
      * @return ConnectorBase
      * @throws UnknownServiceException
+     * @throws UnavailableServiceException
      */
     public function getServiceForType(string $type, array $parameters = []): ConnectorBase
     {
         if (isset($this->connectors[$type])) {
             /** @var ConnectorBase $connector */
             $connector = $this->connectors[$type];
+            if (!$connector->isAvailable()) {
+                throw new UnavailableServiceException(
+                    sprintf(
+                        'Connector service for type %s is not available.',
+                        $type
+                    ),
+                    1733675709
+                );
+            }
             $connector->setParameters($parameters);
             return $connector;
         }

Documentation/Developers/ConnectorApi/Index.rst

@@ -60,9 +60,10 @@ initialize()
 
 
 isAvailable()
-  This method can be called when a connector service is about to be used
-  to check if it is available or not. It is expected to return a boolean value
-  accordingly.
+  This method is called when a connector service is requested via the registry.
+  It is designed to check whether the service is actually available or not.
+  It is expected to return a boolean value accordingly. If the service is not available,
+  the registry will throw a :php:`\Cobweb\Svconnector\Exception\UnavailableServiceException`.
 
   Input
     none

Documentation/Installation/Index.rst

@@ -41,6 +41,10 @@ Instead, parameters must be passed when getting the connector from the registry:
 
     $service = $connectorRegistry->getServiceForType('json', $parameters);
 
+When :code:`getServiceForType()` is called, the connector's :code:`isAvailable()` method is
+now called. If the connector is not available a :php:`\Cobweb\Svconnector\Exception\UnavailableServiceException`
+is thrown.
+
 This version also provides :ref:`events <developers-events>` in replacement of existing hooks
 for all connector services. All hooks have been deprecated and will be removed in the next major version.
 Please update your code if you have developed custom connectors.