Added linked data

Author: rimi-itk

.github/workflows/pr.yaml

@@ -105,6 +105,10 @@ jobs:
           # Restore Drupal composer repository.
           composer --no-interaction --working-dir=drupal config repositories.drupal composer https://packages.drupal.org/8
 
+          composer --no-interaction --working-dir=drupal config --no-plugins allow-plugins.cweagans/composer-patches true
+          # @see https://getcomposer.org/doc/03-cli.md#modifying-extra-values
+          composer --no-interaction --working-dir=drupal config --no-plugins --json extra.enable-patching true
+
           # Require our module.
           composer --no-interaction --working-dir=drupal require 'os2forms/os2forms_rest_api:*'
 

README.md

@@ -144,3 +144,35 @@ details.
 In order to make documents accessible for api users the Key auth
 `authentication_provider` service has been overwritten to be global. See
 [os2forms_rest_api.services](os2forms_rest_api.services.yml).
+
+## Linked data
+
+To make using the REST API easier we add linked data to `GET` responses:
+
+```json
+{
+  …
+  "data": {
+    "file": "87",
+    "name": "The book",
+    "linked": {
+      "file": {
+        "87": {
+          "id": "87",
+          "url": "http://os2forms.example.com/system/files/webform/os2forms/1/cover.jpg",
+          "mime_type": "image/jpeg",
+          "size": "96757"
+        }
+      }
+    }
+  }
+}
+```
+
+### Technical details on linked data
+
+In order to add linked data, we apply a patch,
+[webform_rest_submission.patch](patches/webform_rest_submission.patch), to the
+Webform REST module and implement an event subscriber,
+[WebformSubmissionDataEventSubscriber](src/EventSubscriber/WebformSubmissionDataEventSubscriber.php),
+to add the linked data.

composer.json

@@ -18,6 +18,7 @@
         }
     ],
     "require": {
+        "cweagans/composer-patches": "^1.7",
         "drupal/key_auth": "^2.0",
         "drupal/webform_rest": "^4.0"
     },
@@ -49,7 +50,16 @@
     "config": {
         "sort-packages": true,
         "allow-plugins": {
-            "dealerdirect/phpcodesniffer-composer-installer": true
+            "dealerdirect/phpcodesniffer-composer-installer": true,
+            "cweagans/composer-patches": true
+        }
+    },
+    "extra": {
+        "enable-patching": true,
+        "patches": {
+            "drupal/webform_rest": {
+                "Added ability to modify response data sent from Webform Submission endpoint": "https://raw.githubusercontent.com/itk-dev/os2forms_rest_api/feature/linked-data/patches/webform_rest_submission.patch"
+            }
         }
     }
 }

os2forms_rest_api.services.yml

@@ -1,19 +1,30 @@
 services:
+  logger.channel.os2forms_rest_api:
+    parent: logger.channel_base
+    arguments: [ 'os2forms_rest_api' ]
+
   Drupal\os2forms_rest_api\WebformHelper:
     arguments:
       - '@entity_type.manager'
       - '@current_user'
       - '@key_auth.authentication.key_auth'
       - '@request_stack'
 
-  Drupal\os2forms_rest_api\EventSubscriber\EventSubscriber:
+  Drupal\os2forms_rest_api\EventSubscriber\WebformAccessEventSubscriber:
     arguments:
       - '@current_route_match'
       - '@current_user'
       - '@Drupal\os2forms_rest_api\WebformHelper'
     tags:
       - { name: 'event_subscriber' }
 
+  Drupal\os2forms_rest_api\EventSubscriber\WebformSubmissionDataEventSubscriber:
+    arguments:
+      - '@entity_type.manager'
+      - '@logger.channel.os2forms_rest_api'
+    tags:
+      - { name: 'event_subscriber' }
+
   # Overwrite, adding global tag
   # @see https://www.drupal.org/docs/drupal-apis/services-and-dependency-injection/altering-existing-services-providing-dynamic-services
   key_auth.authentication.key_auth:

patches/webform_rest_submission.patch

@@ -0,0 +1,107 @@
+diff --git a/src/Event/WebformSubmissionDataEvent.php b/src/Event/WebformSubmissionDataEvent.php
+new file mode 100644
+index 0000000..c378f45
+--- /dev/null
++++ b/src/Event/WebformSubmissionDataEvent.php
+@@ -0,0 +1,52 @@
++<?php
++
++namespace Drupal\webform_rest\Event;
++
++use Drupal\Component\EventDispatcher\Event;
++use Drupal\webform\WebformSubmissionInterface;
++
++/**
++ * Class WebformSubmissionDataEvent, an event to modify the data part of the response sent from calling GET webform submission.
++ */
++class WebformSubmissionDataEvent extends Event
++{
++  /**
++   * @var WebformSubmissionInterface
++   */
++  private WebformSubmissionInterface $webformSubmission;
++
++  /**
++   * @var array
++   */
++  private array $data;
++
++  /**
++   * Construct for injection dependency.
++   *
++   * @param array $data
++   * @param WebformSubmissionInterface $webformSubmission
++   */
++  public function __construct(WebformSubmissionInterface $webformSubmission, array $data) {
++    $this->webformSubmission = $webformSubmission;
++    $this->setData($data);
++  }
++
++  /**
++   * @return WebformSubmissionInterface
++   */
++  public function getWebformSubmission(): WebformSubmissionInterface
++  {
++        return $this->webformSubmission;
++  }
++
++  public function getData(): array
++  {
++          return $this->data;
++  }
++
++  public function setData(array $data)
++  {
++        $this->data = $data;
++        return $this;
++  }
++}
+diff --git a/src/Plugin/rest/resource/WebformSubmissionResource.php b/src/Plugin/rest/resource/WebformSubmissionResource.php
+index d2e08c5..a9cacf7 100644
+--- a/src/Plugin/rest/resource/WebformSubmissionResource.php
++++ b/src/Plugin/rest/resource/WebformSubmissionResource.php
+@@ -5,6 +5,7 @@ namespace Drupal\webform_rest\Plugin\rest\resource;
+ use Drupal\webform\WebformSubmissionForm;
+ use Drupal\rest\Plugin\ResourceBase;
+ use Drupal\rest\ModifiedResourceResponse;
++use Drupal\webform_rest\Event\WebformSubmissionDataEvent;
+ use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+ use Symfony\Component\DependencyInjection\ContainerInterface;
+ 
+@@ -35,6 +36,13 @@ class WebformSubmissionResource extends ResourceBase {
+    */
+   protected $request;
+ 
++  /**
++   * An event dispatcher instance to use for dispatching events.
++   *
++   * @var \Symfony\Contracts\EventDispatcher\EventDispatcherInterface
++   */
++  protected $eventDispatcher;
++
+   /**
+    * {@inheritdoc}
+    */
+@@ -42,6 +50,7 @@ class WebformSubmissionResource extends ResourceBase {
+     $instance = parent::create($container, $configuration, $plugin_id, $plugin_definition);
+     $instance->entityTypeManager = $container->get('entity_type.manager');
+     $instance->request = $container->get('request_stack');
++    $instance->eventDispatcher = $container->get('event_dispatcher');
+     return $instance;
+   }
+ 
+@@ -91,9 +100,13 @@ class WebformSubmissionResource extends ResourceBase {
+         // Grab submission data.
+         $data = $webform_submission->getData();
+ 
++        // Dispatch WebformSubmissionDataEvent to allow modification of data.
++        $event = new WebformSubmissionDataEvent($webform_submission, $data);
++        $this->eventDispatcher->dispatch($event);
++
+         $response = [
+           'entity' => $webform_submission,
+-          'data' => $data,
++          'data' => $event->getData(),
+         ];
+ 
+         // Return the submission.

src/EventSubscriber/EventSubscriber.php renamed to src/EventSubscriber/WebformAccessEventSubscriber.php

@@ -12,9 +12,9 @@
 use Symfony\Component\HttpKernel\KernelEvents;
 
 /**
- * Event subscriber.
+ * Webform access event subscriber.
  */
-class EventSubscriber implements EventSubscriberInterface {
+class WebformAccessEventSubscriber implements EventSubscriberInterface {
   /**
    * The route match.
    *

src/EventSubscriber/WebformSubmissionDataEventSubscriber.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace Drupal\os2forms_rest_api\EventSubscriber;
+
+use Drupal\Core\Entity\EntityTypeManagerInterface;
+use Drupal\file\FileInterface;
+use Drupal\webform\WebformInterface;
+use Drupal\webform_rest\Event\WebformSubmissionDataEvent;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+/**
+ * WebformSubmissionEventSubscriber, for updating Webform Submission GET data.
+ */
+class WebformSubmissionDataEventSubscriber implements EventSubscriberInterface {
+  use LoggerAwareTrait;
+
+  /**
+   * Entity type manager.
+   *
+   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
+   */
+  private EntityTypeManagerInterface $entityTypeManager;
+
+  /**
+   * Map from entity type to webform element types.
+   */
+  private const LINKED_ELEMENT_TYPES = [
+    'file' => [
+      'webform_image_file',
+      'webform_document_file',
+      'webform_video_file',
+      'webform_audio_file',
+      'managed_file',
+    ],
+  ];
+
+  /**
+   * Constructor.
+   */
+  public function __construct(EntityTypeManagerInterface $entityTypeManager, LoggerInterface $logger) {
+    $this->entityTypeManager = $entityTypeManager;
+    $this->setLogger($logger);
+  }
+
+  /**
+   * Event handler.
+   */
+  public function onWebformSubmissionDataEvent(WebformSubmissionDataEvent $event): void {
+    $linkedData = $this->buildLinked($event->getWebformSubmission()->getWebform(), $event->getData());
+
+    if (!empty($linkedData)) {
+      $event->setData($event->getData() + ['linked' => $linkedData]);
+    }
+  }
+
+  /**
+   * Builds linked entity data.
+   *
+   * @see https://support.deskpro.com/en/guides/developers/deskpro-api/basics/sideloading
+   *
+   * @phpstan-param array<string, mixed> $data
+   * @phpstan-return array<string, mixed>
+   */
+  private function buildLinked(WebformInterface $webform, array $data): array {
+    $linked = [];
+    $elements = $webform->getElementsDecodedAndFlattened();
+
+    foreach ($elements as $name => $element) {
+      if (!isset($data[$name])) {
+        continue;
+      }
+
+      $linkedEntityType = NULL;
+      if (isset($element['#target_type'])) {
+        $linkedEntityType = $element['#target_type'];
+      }
+      else {
+        foreach (self::LINKED_ELEMENT_TYPES as $entityType => $elementTypes) {
+          if (in_array($element['#type'], $elementTypes, TRUE)) {
+            $linkedEntityType = $entityType;
+            break;
+          }
+        }
+      }
+
+      if (NULL !== $linkedEntityType) {
+        // $data[$name] is either a string id i.e. '127',
+        // or an array of string ids i.e. ['127', '128'].
+        // Casting to array allow us to handle both cases the same way.
+        $values = (array) $data[$name];
+        $entities = $this->entityTypeManager->getStorage($linkedEntityType)->loadMultiple($values);
+
+        foreach ($entities as $value => $entity) {
+          $link = [];
+          if ($entity instanceof FileInterface) {
+            $link = [
+              'id' => $entity->id(),
+              'url' => $entity->createFileUrl(FALSE),
+              'mime_type' => $entity->getMimeType(),
+              'size' => $entity->getSize(),
+            ];
+          }
+          else {
+            $this->logger->warning(sprintf('Unhandled linked entity type %s', $linkedEntityType));
+          }
+          if (!empty($link)) {
+            $linked[$name][$value] = $link;
+          }
+        }
+      }
+    }
+    return $linked;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function getSubscribedEvents() {
+    return [
+      WebformSubmissionDataEvent::class => ['onWebformSubmissionDataEvent'],
+    ];
+  }
+
+}

src/WebformHelper.php

@@ -251,7 +251,9 @@ private function getAllowedUsers(WebformInterface $webform): array {
    *   True if user has access to the webform.
    */
   public function hasWebformAccess(WebformInterface $webform, $user): bool {
-    $userId = $user instanceof AccountInterface ? $user->id() : $user;
+    // AccountInterface::id() should return an `int` but actually returns a
+    // `string`.
+    $userId = (int) ($user instanceof AccountInterface ? $user->id() : $user);
     assert(is_int($userId));
 
     $allowedUsers = $this->getAllowedUsers($webform);