[FOLLOWUP] Add one more event, deprecate existing hook, update docume…

…ntation, references #31

Classes/Event/PostProcessOperationsEvent.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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!
+ */
+
+namespace Cobweb\Svconnector\Event;
+
+use Cobweb\Svconnector\Service\ConnectorServiceInterface;
+
+/**
+ * Event for performing any custom process after the connector has finished its work.
+ * It depends on method \Cobweb\Svconnector\Service\ConnectorBase::postProcessOperations()
+ * being called. It receives a status information, the nature of which depends on the
+ * code calling the post-process operations.
+ */
+final class PostProcessOperationsEvent
+{
+    protected mixed $status;
+    protected ConnectorServiceInterface $connectorService;
+
+    public function __construct(mixed $data, ConnectorServiceInterface $connectorService)
+    {
+        $this->status = $data;
+        $this->connectorService = $connectorService;
+    }
+
+    public function getConnectorService(): ConnectorServiceInterface
+    {
+        return $this->connectorService;
+    }
+
+    public function getStatus(): mixed
+    {
+        return $this->status;
+    }
+
+}

Classes/Event/ProcessArrayDataEvent.php

@@ -19,6 +19,10 @@
 
 use Cobweb\Svconnector\Service\ConnectorServiceInterface;
 
+/**
+ * Event for processing data in array format retrieved by connector services.
+ * Primarily meant for use in the fetchArray() method.
+ */
 final class ProcessArrayDataEvent
 {
     protected array $data;

Classes/Event/ProcessRawDataEvent.php

@@ -19,6 +19,10 @@
 
 use Cobweb\Svconnector\Service\ConnectorServiceInterface;
 
+/**
+ * Event for processing the raw data retrieved by connector services.
+ * Primarily meant for use in the fetchRaw() method.
+ */
 final class ProcessRawDataEvent
 {
     protected mixed $data;

Classes/Event/ProcessResponseEvent.php

@@ -19,6 +19,10 @@
 
 use Cobweb\Svconnector\Service\ConnectorServiceInterface;
 
+/**
+ * Event for processing the raw response received by the connector service when retrieving data.
+ * Primarily meant for use in the query() method.
+ */
 final class ProcessResponseEvent
 {
     protected mixed $response;

Classes/Event/ProcessXmlDataEvent.php

@@ -19,6 +19,10 @@
 
 use Cobweb\Svconnector\Service\ConnectorServiceInterface;
 
+/**
+ * Event for processing data in XML format retrieved by connector services.
+ * Primarily meant for use in the fetchXml() method.
+ */
 final class ProcessXmlDataEvent
 {
     protected string $data;

Classes/Service/ConnectorBase.php

@@ -20,6 +20,7 @@
 use Cobweb\Svconnector\Domain\Model\Dto\CallContext;
 use Cobweb\Svconnector\Domain\Model\Dto\ConnectionInformation;
 use Cobweb\Svconnector\Event\InitializeConnectorEvent;
+use Cobweb\Svconnector\Event\PostProcessOperationsEvent;
 use Cobweb\Svconnector\Event\ProcessParametersEvent;
 use Cobweb\Svconnector\Exception\ConnectorRuntimeException;
 use Cobweb\Svconnector\Utility\ParameterParser;
@@ -290,12 +291,19 @@ public function postProcessOperations(array $parameters, mixed $status): void
         }
 
         $hooks = $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS'][$this->extensionKey]['postProcessOperations'] ?? null;
-        if (is_array($hooks)) {
+        if (is_array($hooks) && count($hooks) > 0) {
+            trigger_error(
+                'Using the postProcessOperations hook is deprecated. Use the PostProcessOperationsEvent instead',
+                E_USER_DEPRECATED
+            );
             foreach ($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS'][$this->extensionKey]['postProcessOperations'] as $className) {
                 $processor = GeneralUtility::makeInstance($className);
                 $processor->postProcessOperations($this->parameters, $status, $this);
             }
         }
+        $this->eventDispatcher->dispatch(
+            new PostProcessOperationsEvent($status, $this)
+        );
     }
 
     /**

Documentation/Developers/Events/Index.rst

@@ -34,3 +34,49 @@ dynamic usage in the connector parameters.
 
 This event is fired after :ref`parameters have been parsed <developers-api-connection-information>`
 and allows for further manipulation of the connector parameters.
+
+
+.. _developers-events-rawdata:
+
+\Cobweb\Svconnector\Event\ProcessRawDataEvent
+"""""""""""""""""""""""""""""""""""""""""""""
+
+This event is fired after the service has retrieved data in raw format. It is designed
+for use in the :code:`fetchRaw()` method.
+
+
+.. _developers-events-arraydata:
+
+\Cobweb\Svconnector\Event\ProcessArrayDataEvent
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+This event is fired after the service has retrieved data in array format. It is designed
+for use in the :code:`fetchArray()` method.
+
+
+.. _developers-events-xmldata:
+
+\Cobweb\Svconnector\Event\ProcessXmlDataEvent
+""""""""""""""""""""""""""""""""""""""""""""""
+
+This event is fired after the service has retrieved data in XML format. It is designed
+for use in the :code:`fetchXml()` method.
+
+
+.. _developers-events-response:
+
+\Cobweb\Svconnector\Event\ProcessResponseEvent
+""""""""""""""""""""""""""""""""""""""""""""""
+
+This event is fired after the service has called the distant source and received a
+response from that source. It is designed for use in the :code:`query()` method.
+
+
+.. _developers-events-postprocess:
+
+\Cobweb\Svconnector\Event\PostProcessOperationsEvent
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This event is fired after all operations have been performed by the connector services.
+Actually, it will be triggered only if the code that used the service called the
+:code:`\Cobweb\Svconnector\Service\ConnectorServiceInterface::postProcessOperations()` method.

Documentation/Developers/Hooks/Index.rst

@@ -11,6 +11,12 @@
 Hooks
 ^^^^^
 
+.. warning::
+
+   Hooks are deprecated and will be removed in the next major version of all
+   official connector services. Please use the :ref:`events <developers-events>`
+   provided by svconnector instead.
+
 It doesn't really make sense to have hooks in the base connector
 class, since it cannot be instantiated directly. There are quite
 some examples in the existing connector services and here is a list