.. _developer:

================
Developer corner
================

Target group: **Developers**

.. contents:: Table of Contents
   :depth: 3
   :local:


.. _developer-variable-resolvers:

Writing own variable resolvers
==============================

With :ref:`variables <variable-resolvers>` it is possible to add
information to a process start which is resolved when submitting a form. This
extension ships some variable resolvers already, for example, for translation or
language information.

You can write your own variable resolvers dependent on your needs. Variable
resolvers are implemented as :ref:`PSR-14 event listeners
<t3coreapi:EventDispatcher>`.

The event listener receives the event
:php:`JobRouter\AddOn\Typo3Base\Event\ResolveFinisherVariableEvent`. It
provides the following methods:

.. confval:: getFieldType(): \JobRouter\AddOn\Typo3Base\Enumeration\FieldType

   Get the field type, like :php:`FieldType::Text` for text or
   :php:`FieldType::Integer` for int. Have a look in the class
   :php:`JobRouter\AddOn\Typo3Base\Enumeration\FieldType` for the available
   field types.

.. confval:: getValue(): string

   Get the current value of the field. One or more variables can be defined
   inside.

.. confval:: setValue(string $value): void

   Set the new value after resolving one or more variables.

.. confval:: getCorrelationId(): string

   Get the current correlation ID.

.. confval:: getFormValues(): array

   Get the form values, for example,
   :php:`['company' => 'Acme Ltd.', 'name' => 'John Smith']`.

.. confval:: getRequest(): \Psr\Http\Message\ServerRequestInterface

   Get the current request.

.. hint::

   Some variable resolvers are already shipped with the extension. Have a look
   into the folder :file:`Classes/Domain/VariableResolver` for implementation
   details.

Example
-------

As an example we want to resolve a variable to a cookie value with an event
listener:

.. code-block:: php

   <?php
   declare(strict_types=1);

   namespace YourVender\YourExtension\EventListener;

   use JobRouter\AddOn\Typo3Base\Event\ResolveFinisherVariableEvent;
   use Psr\Http\Message\ServerRequestInterface;
   use TYPO3\CMS\Core\Attribute\AsEventListener;

   #[AsEventListener(
      identifier: 'your-extension/cookie-variable-resolver',
   )]
   final readonly class TheCookieVariableResolver
   {
      private const COOKIE_NAME = 'the_cookie';
      private const VARIABLE = '{__theCookieValue}';

      public function __invoke(ResolveFinisherVariableEvent $event): void
      {
         $value = $event->getValue();

         if (str_contains($value, self::VARIABLE)) {
            // Variable is not available, do nothing
            return;
         }

         $cookies = $event->getRequest()->getCookieParams();

         $variableValue = $cookies[self::COOKIE_NAME] ?? '';
         $value = str_replace(self::VARIABLE, $variableValue, $value);

         $event->setValue($value);
      }
   }

.. important::

   Variables have to start with `{__`. Otherwise the variable resolver is not
   called for a value.