brapi.module

<?php

/**
 * @file
 * Contains brapi.module.
 */

use Drupal\brapi\Entity\BrapiDatatype;
use Drupal\brapi\Entity\BrapiToken;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\Core\Routing\RouteMatchInterface;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

const BRAPI_PERMISSION_USE      = 'use brapi';
const BRAPI_PERMISSION_EDIT     = 'edit brapi content';
const BRAPI_PERMISSION_SPECIFIC = 'use restricted brapi';
const BRAPI_PERMISSION_ADMIN    = 'administer brapi';
const BRAPI_DEFAULT_PAGE_SIZE  = 40;
const BRAPI_DEFAULT_PAGE_SIZE_MAX  = 200;
const BRAPI_DATATYPE_ID_REGEXP = '/^(v[\d])-([^\-]+)-([^\-]+)-?(.*)$/';
const BRAPI_MIME_JSON = 'application/json';
const BRAPI_DEFAULT_TOKEN_LIFETIME   = 86400; // 1 day.
const BRAPI_DEFAULT_SEARCH_LIFETIME  = 604800; // 1 week.
const BRAPI_TO_PLURAL = [
  'entity'    => 'entities',
  'Entity'    => 'Entities',
  'ENTITY'    => 'ENTITIES',
  'germplasm' => 'germplasm',
  'Germplasm' => 'Germplasm',
  'GERMPLASM' => 'GERMPLASM',
];
const BRAPI_TO_SINGULAR = [
  'entities'  => 'entity',
  'Entities'  => 'Entity',
  'ENTITIES'  => 'ENTITY',
  'germplasm' => 'germplasm',
  'Germplasm' => 'Germplasm',
  'GERMPLASM' => 'GERMPLASM',
];

/**
 * Implements hook_help().
 */
function brapi_help($route_name, RouteMatchInterface $route_match) {
  switch ($route_name) {
    // Main module help for the brapi module.
    case 'help.page.brapi':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('Plant Breeding API server implementation for Drupal.') . '</p>';
      return $output;

    default:
  }
}


/**
 * Implements hook_theme().
 */
function brapi_theme($existing, $type, $theme, $path) {
  return [
    'brapi_main' => [
      'template' => 'brapi-main',
      'variables' => [],
    ],
    'brapi_documentation' => [
      'template' => 'brapi-documentation',
      'variables' => [],
    ],
    'brapi_token' => [
      'template' => 'brapi-token',
      'variables' => ['tokens', 'all_tokens'],
    ],
  ];
}

/**
 * Implements hook_preprocess_TEMPLATE().
 */
function brapi_preprocess_brapi_token(&$variables){
  $user = \Drupal::currentUser();
  $tokens = BrapiToken::getUserTokens($user, TRUE);
  $variables['tokens'] = $tokens;

  // Check if admin and add all available tokens if so.
  if ($user->hasPermission(BRAPI_PERMISSION_ADMIN)) {
    $token_storage = \Drupal::entityTypeManager()->getStorage('brapi_token');
    $query = $token_storage->getQuery()
      ->accessCheck(FALSE)
      ->condition('user_id', $user->id(), '!=')
      ->sort('expiration', 'DESC');
    ;
    // Only display unexpired tokens.
    $group = $query
      ->orConditionGroup()
      ->condition('expiration', time(), '>')
      ->condition('expiration', 0, '<')
    ;
    $query->condition($group);
    $ids = $query->execute();
    if (count($ids)) {
      // Load tokens.
      $variables['all_tokens'] = $token_storage->loadMultiple($ids);
    }
  }
}

/**
 * Returns available BrAPI versions.
 *
 * @return array
 *   An array which keys are BrAPI major versions (either 'v1' or 'v2') and
 *   values are arrays which keys are subversions (ex. ['2.0', '2.1']) and
 *   values are booleans (set to TRUE).
 */
function brapi_available_versions() :array {
  static $versions = [];

  if (empty($versions)) {
    // Get version definition directory.
    $module_handler = \Drupal::service('module_handler');
    $module_path = $module_handler->getModule('brapi')->getPath();
    $version_path = \Drupal::service('file_system')->realpath(
      $module_path . '/definitions'
    );
    $files = scandir($version_path);
    // Process version files.
    foreach ($files as $file) {
      $file_path = "$version_path/$file";
      // Limit to version files.
      if (is_file($file_path)
          && preg_match('#^brapi_(v[12])_([\w\.\-]+)\.json$#', $file, $matches)
      ) {
        $versions[$matches[1]] = $versions[$matches[1]] ?? [];
        $versions[$matches[1]][$matches[2]] = TRUE;
      }
    }
  }

  return $versions;
}

/**
 * Generates a data type identifier used in configs.
 *
 * @return string
 *   A data type identifier.
 */
function brapi_generate_datatype_id($datatype_name, $version, $active_def) :string {
  $datatype_id = $version . '-' . $active_def . '-' . $datatype_name;
  return $datatype_id;
}

/**
 * Returns a BrAPI fields, data types and calls definition for a given version.
 *
 * @param string $version
 *   BrAPI version. Currently either 'v1' or 'v2'
 *
 * @param string $subversion
 *   BrAPI version with subversion number. Example: '2.0'.
 *
 * @return array
 *   An array as described below or an empty array if the version definition is
 *   not available:
 *   ```
 *   [
 *     'modules' => [
 *       "<MODULE NAME1>" => [
 *         "<CATEGORY NAME1>" => [
 *           "calls" => [
 *             "<API CALL PATH1>" => TRUE,
 *             "<API CALL PATH2>" => TRUE,
 *             ...
 *           ],
 *           "data_types" => [
 *             "<DATA TYPE NAME1>" => TRUE,
 *             "<DATA TYPE NAME2>" => TRUE,
 *             ...
 *           ],
 *         ],
 *         "<CATEGORY NAME2>" => [
 *           ...
 *         ],
 *         ...
 *       ],
 *       "<MODULE NAME2>" => [
 *         ...
 *       ],
 *       ...
 *     ],
 *     'calls' => [
 *       "<API CALL PATH1>" => [
 *         "definition" => [
 *           "<METHOD1>" => [
 *             "summary" => "...",
 *             "description" => "...",
 *             "fields" => [
 *               "<FIELD NAME1>" => [
 *                 "description" => "...",
 *                 "required" => TRUE/FALSE,
 *                 "type" => "<TYPE>",
 *                 "is_array" => TRUE/FALSE,
 *               ],
 *               ...
 *             ],
 *           ],
 *           "<METHOD2>" => [
 *             ...
 *           ],
 *           ...
 *         ],
 *         'data_types' => [
 *           "<DATA TYPE NAME1>" => TRUE,
 *           ...
 *         ],
 *       ],
 *     ],
 *     'data_types' => [
 *       "<DATA TYPE NAME1>" => [
 *         "description" => "...",
 *         "fields" => [
 *           "<FIELD NAME1>" => [
 *             "type"     => <DATA TYPE NAME or basic type name followed by '[]' if array>
 *             "required" => TRUE/FALSE,
 *           ],
 *           ...
 *         ],
 *         "as_field_in" => [
 *           "<DATA TYPE NAME1>" => TRUE,
 *           ...
 *         ],
 *         "calls" => [
 *           "<API CALL PATH1>" => TRUE,
 *           ...
 *         ],
 *       ],
 *       "<DATA TYPE NAME2>" => [
 *         ...
 *       ],
 *       ...
 *     ],
 *     'fields' => [
 *       "<FIELD NAME1>" => [
 *         "type" => "<TYPE>",
 *         "description" => "...",
 *         "example" => "...",
 *         "calls" => [
 *           "<API CALL PATH1>" => TRUE,
 *           ...
 *         ],
 *         "data_types" => [
 *           "<DATA TYPE NAME1>" => TRUE,
 *           ...
 *         ],
 *       ],
 *       "<FIELD NAME2>" => [
 *         ...
 *       ],
 *       ...
 *     ],
 *   ];
 *   ```
 */
function brapi_get_definition(string $version, string $subversion) :array {
  static $versions = [];

  // Sanitize parameters.
  $version = preg_replace('/[^\w\.\-]/', '', $version);
  $subversion = preg_replace('/[^\w\.\-]/', '', $subversion);
  // Generate a static cache key.
  $version_key = $version . '#' . $subversion;
  if (!array_key_exists($version_key, $versions)) {
    // Default to empty definition.
    $versions[$version_key] = [];

    // Get definition directory.
    $module_handler = \Drupal::service('module_handler');
    $module_path = $module_handler->getModule('brapi')->getPath();
    $definition_path = \Drupal::service('file_system')->realpath(
      $module_path . '/definitions'
    );
    $file_path = "$definition_path/brapi_" . $version . '_' . $subversion . '.json';
    // Limit to definition files.
    if (is_file($file_path)) {
      // Try to get file content.
      $json_raw = file_get_contents($file_path);
      if (empty($json_raw)) {
        // Log error.
        \Drupal::logger('brapi')->error("Unable to get JSON file content for file '$file_path'.");
      }
      else {
        $definition = json_decode($json_raw, TRUE);
        if (NULL == $definition) {
          \Drupal::logger('brapi')->error(
            "Failed to parse JSON file '$file_path': "
            . json_last_error_msg()
          );
        }
        $versions[$version_key] = $definition;
      }
    }
    $module_handler = \Drupal::moduleHandler();
    $module_handler->alter('brapi_definition', $versions, $version_key);
  }

  return $versions[$version_key];
}

/**
 * Converts an Open API JSON into a definition.
 *
 * This function is used "manually" to parse OpenAPI output and generate
 * definitions files stored in module's "definitions" directory.
 * Example of use:
 * ```
 *   $f1 = file_get_contents('versions/openapi_brapi_1.2.json');
 *   $def = brapi_open_api_to_definition([json_decode($f1, TRUE),]);
 *   $json = json_encode($def, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES );
 *   $fj = fopen('definitions/brapi_v1_1.2.json', 'w');
 *   fwrite($fj, $json);
 *   fclose($fj);
 * ```
 *
 * @param array $openapis
 *   An array of Open API data structures.
 *
 * @return array
 *   A definition array as describbed in brapi_get_definition().
 *
 * @see brapi_get_definition
 * @see https://swagger.io/specification/
 */
function brapi_open_api_to_definition(array $openapis) :array {
  $definition = [
    'modules'    => [],
    'calls'      => [],
    'data_types' => [],
    'fields'     => [],
  ];

  $ref_resolutions = [];

  foreach ($openapis as $openapi_index => $openapi) {
    // Init module data if needed.
    $module = $openapi['info']['title'] ?? 'BrAPI';
    $definition['modules'][$module] = $definition['modules'][$module] ?? [];
    $module_definition =& $definition['modules'][$module];
    // Add missing categories.
    foreach ($openapi['tags'] ?? [['name' => '']] as $category) {
      $module_definition[$category['name']] =
        $module_definition[$category['name']]
        ?? []
      ;
    }

    // Process data types.
    foreach ($openapi['components']['schemas'] ?? [] as $datatype => $datatype_definition) {
      $ref =
        $datatype_definition['$ref']
        ?? $datatype_definition['properties']['result']['$ref']
        // ?? $datatype_definition['properties']['data']['$ref']
        ?? $datatype_definition['properties']['data']['items']['$ref']
        ?? ''
      ;
      if (!empty($ref)) {
        // Check for reference.
        if (preg_match('%^#/components/schemas/(\w+)$%', $ref, $matches)) {
          $ref_resolutions[$datatype] = $matches[1];
        }
        else {
          \Drupal::logger('brapi')->warning("Unsuppoted \$ref: components>schemas>$datatype: " . $ref . '.');
        }
        continue 1;
      }

      // Check for response wrapper.
      if (!empty($datatype_definition['properties']['metadata'])
          && !empty($datatype_definition['properties']['result'])
      ) {
        // Check for reference.
        $ref =
          $datatype_definition['properties']['result']['$ref']
          ?? ''
        ;
        if (!empty($ref)) {
          if (preg_match('%^#/components/schemas/(\w+)$%', $ref, $matches)) {
            $ref_resolutions[$datatype] = $matches[1];
          }
          else {
            \Drupal::logger('brapi')->warning("Unsuppoted \$ref: components>schemas>$datatype>properties>result: " . $ref . '.');
          }
        }
        continue 1;
      }

      // Process data type fields.
      $fields = [];
      foreach ($datatype_definition['properties'] ?? [] as $field => $field_definition) {
        $fields[$field] = ['type' => $field_definition['type'] ?? ''];
        if (!empty($field_definition['$ref'])) {
          // Get type from reference.
          if (preg_match('%^#/components/schemas/(\w+)$%', $field_definition['$ref'], $matches)) {
            $fields[$field] = ['type' => $matches[1]];
          }
          else {
            \Drupal::logger('brapi')->warning("Unsuppoted \$ref: components>schemas>$datatype>properties>$field.");
          }
        }
        // Check for array of values.
        if (!empty($field_definition['items']['$ref'])) {
          if ((!empty($fields[$field]['type'])) && ('array' != $fields[$field]['type'])) {
            \Drupal::logger('brapi')->warning("Check components>schemas>$datatype>properties>$field definition (invalid type: " . $fields[$field]['type'] . ").");
          }
          if (preg_match('%^#/components/schemas/(\w+)$%', $field_definition['items']['$ref'], $matches)) {
            $fields[$field] = ['type' => $matches[1] . '[]'];
          }
          else {
            \Drupal::logger('brapi')->warning("Unsuppoted \$ref: components>schemas>$datatype>properties>$field>items.");
          }
        }
        elseif (!empty($field_definition['items']['type'])) {
          if ((!empty($fields[$field]['type'])) && ('array' != $fields[$field]['type'])) {
            \Drupal::logger('brapi')->warning("Check components>schemas>$datatype>properties>$field definition (invalid type: " . $fields[$field]['type'] . ").");
          }
          $fields[$field] = ['type' => $field_definition['items']['type'] . '[]'];
        }
        // Check if field is required by datatype.
        $fields[$field]['required'] = in_array(
          $field, $datatype_definition['required'] ?? []
        );

        // Fill field definitions.
        if (empty($definition['fields'][$field])
            || empty($definition['fields'][$field]['type'])
        ) {
          // New or incomplete field.
          $definition['fields'][$field] = [
            'type' => $fields[$field]['type'],
            'description' => $field_definition['description'] ?? '',
            'example' => $field_definition['example'] ?? '',
            'calls' => $definition['fields'][$field]['calls'] ?? [],
            'data_types' => [$datatype => TRUE],
          ];
        }
        else {
          // Field redefinition. Check for inconsistency.
          $current_type = $definition['fields'][$field]['type'];
          $new_type = $fields[$field]['type'];
          if (!empty($current_type)
              && !empty($new_type)
              && ($current_type != $new_type)
          ) {
            \Drupal::logger('brapi')->warning("components>schemas>$datatype>properties>$field: inconsistent field redefinition (" . $current_type . ' vs ' . $new_type . ").");
          }
          // Register new data type dependency.
          $definition['fields'][$field]['data_types'][$datatype] = TRUE;
        }
      }
      $datatype_details = [
        'type'          => $datatype_definition['type'] ?? '',
        'description'   => $datatype_definition['description'] ?? '',
        'fields'        => $fields,
        'calls'         => [],
        'as_field_in'   => [],
      ];
      if (!empty($definition['data_types'][$datatype])) {
        \Drupal::logger('brapi')->warning("components>schemas>$datatype: data type already defined before. Completing definition.");
        $definition['data_types'][$datatype]['type'] ?: $datatype_details['type'];
        $definition['data_types'][$datatype]['description'] ?: $datatype_details['description'];
        foreach ($datatype_details['fields'] as $field_name => $field_def) {
          $definition['data_types'][$datatype]['fields'][$field_name] ??= $field_def;
        }
      }
      else {
        $definition['data_types'][$datatype] = $datatype_details;
      }
    }

    // Process responses.
    foreach ($openapi['components']['responses'] ?? [] as $response => $response_definition) {
      $ref = $response_definition['content']['application/json']['schema']['$ref'] ?? '';
      if (preg_match('%^#/components/schemas/(\w+)$%', $ref, $matches)) {
        $ref_resolutions['response>' . $response] = $matches[1];
      }
      elseif (!empty($ref)) {
        \Drupal::logger('brapi')->warning("Unsupported response components>respones>$response.");
      }
    }

    // Process $ref_resolutions to update resolutions to final objects.
    foreach ($ref_resolutions as $ref => $resolution) {
      $circular_check = [];
      while (
        array_key_exists($resolution, $ref_resolutions)
        && empty($circular_check[$ref_resolutions[$resolution]])
      ) {
        $circular_check[$resolution] = TRUE;
        $resolution = $ref_resolutions[$resolution];
      }
      if (!empty($circular_check[$resolution])) {
        \Drupal::logger('brapi')->warning("Unresolved circular references for $ref.");
      }
      if (empty($definition['data_types'][$resolution])) {
        \Drupal::logger('brapi')->warning("Missing data type definition '$resolution' for $ref.");
      }
      $ref_resolutions[$ref] = $resolution;
    }

    // Fill 'as_field_in'.
    foreach ($definition['data_types'] as $datatype => $datatype_definition) {
      foreach ($datatype_definition['fields'] as $field => $def) {
        $type = $def['type'];
        // We don't care if it is an array, we just need the type name.
        $type = rtrim($type, '[]');
        if (array_key_exists($type, $definition['data_types'])) {
          $definition['data_types'][$type]['as_field_in'][$datatype] = TRUE;
        }
      }
    }

    // Process calls.
    foreach ($openapi['paths'] ?? [] as $call => $call_definition) {
      $call_details = [
        'definition' => $call_definition,
        'data_types'  => [],
      ];
      $categories = [];
      if (!empty($call_definition['$ref'])) {
        // @todo: Get methods from reference.
        \Drupal::logger('brapi')->warning("Unsuppoted \$ref: paths>$call.");
      }
      foreach ($call_definition as $method => $method_definition) {
        foreach ($method_definition['parameters'] ?? [] as $parameter) {
          if (!empty($parameter['$ref'])) {
            // @todo: Get schema from ref.
            \Drupal::logger('brapi')->warning("Unsuppoted \$ref: paths>$call>$method>parameters.");
          }
          // Fill data type dependencies.
          if (!empty($parameter['schema'])) {
            if (!empty($parameter['schema']['$ref'])) {
              if (preg_match('%^#/components/schemas/(\w+)$%', $parameter['schema']['$ref'], $matches)) {
                // Resolve reference ro real data type name.
                $datatype = $matches[1];
                if (array_key_exists($datatype, $ref_resolutions)) {
                  $datatype = $ref_resolutions[$datatype];
                }
                $call_details['data_types'][$datatype] = TRUE;
              }
              else {
                \Drupal::logger('brapi')->warning("Unsuppoted \$ref: paths>$call>$method>parameters>schema.");
              }
            }
            else {
              $field = $parameter['name'] ?? '';
              if (!array_key_exists($field, $definition['fields'])) {
                $definition['fields'][$field] = [
                  'type' => $parameter['type'] ?? '',
                  'description' => $parameter['description'] ?? '',
                  'example' => $parameter['example'] ?? '',
                  'calls' => [$call => TRUE,],
                  'data_types' => [],
                ];
                if (!empty($parameter['items'])) {
                  $definition['fields'][$field]['type'] = $parameter['items']['type'] . '[]';
                }
              }
              $definition['fields'][$field]['calls'][$call] = TRUE;
            }
          }
        }
        // Add response data type dependencies.
        // Resolve references to a real data type name.
        $ref =
          $method_definition['responses']['200']['$ref']
          ?? $method_definition['responses']['200']['content']['application/json']['schema']['$ref']
          ?? $method_definition['responses']['200']['content']['application/json']['schema']['properties']['result']['$ref']
          ?? $method_definition['responses']['200']['content']['application/json']['schema']['properties']['result']['properties']['data']['$ref']
          ?? $method_definition['responses']['200']['content']['application/json']['schema']['properties']['result']['properties']['data']['items']['$ref']
          ?? ''
        ;
        // Check if we have a reference.
        if (!empty($ref)
            && (preg_match('%^#/components/schemas/(\w+)$%', $ref, $matches))
        ) {
          // Resolve reference ro real data type name.
          $datatype = $matches[1];
          if (array_key_exists($datatype, $ref_resolutions)) {
            $datatype = $ref_resolutions[$datatype];
          }
          $call_details['data_types'][$datatype] = TRUE;
        }
        else {
          // No reference, maybe a simple type defined.
          $type =
            $method_definition['responses']['200']['content']['application/json']['schema']['properties']['result']['properties']['data']['items']['type']
            ?? $method_definition['responses']['200']['content']['application/json']['schema']['properties']['result']['properties']['data']['type']
            ?? $method_definition['responses']['200']['content']['application/json']['schema']['properties']['result']['properties']['status']['type']
            ?? ''
          ;
          if (empty($type)) {
            // No type either, report as warning.
            \Drupal::logger('brapi')->warning("No response data type identified for paths>$call>$method>responses.");
          }
        }

        // Add call to categories.
        foreach ($method_definition['tags'] ?? [['name' => '']] as $category) {
          $module_definition[$category]['calls'][$call] = TRUE;
          $categories[$category] = TRUE;
        }
      }

      // Add call details to BrAPI definition.
      if (!empty($definition['calls'][$call])) {
        \Drupal::logger('brapi')->warning("Redefinition of call $call in " . $module . '(array ' . $openapi_index . ').');
      }
      $definition['calls'][$call] = $call_details;

      // Add call to data types and data types to categories.
      foreach (array_keys($call_details['data_types']) as $datatype) {
        if (empty($definition['data_types'][$datatype])) {
          \Drupal::logger('brapi')->warning("Missing data type '$datatype' definition for call $call in " . $module . '(array ' . $openapi_index . ') (note: it may be defined later in other modules).');
        }
        $definition['data_types'][$datatype]['calls'][$call] = TRUE;
        foreach ($categories as $category) {
          $module_definition[$category]['data_types'][$datatype] = TRUE;
        }
      }
    }
  }

  return $definition;
}

/**
 * Tells if a field references another BrAPI datatype.
 *
 * @param string $field
 *   The current datatype field name to check.
 * @param string $current_datatype
 *   The current datatype that holds the potential reference field to check.
 * @param array $brapi_def
 *   The BrAPI definition to use.
 *
 * @return FALSE if the field is not a reference, the referenced datatype name
 *   otherwise (evaluated as a TRUE value).
 */
function brapi_is_reference_to_datatype(
  string $field,
  string $current_datatype,
  array $brapi_def
) {
  $referenced_datatype = FALSE;
  $field_datatype =
    $brapi_def['data_types'][$current_datatype]['fields'][$field]['type']
    ?? ''
  ;

  // Adjust field datatype to match real datatypes.
  // Ex.: field datatype "GermplasmAttribute_trait" should be in fact
  // treated as "Trait".
  // @todo: Maybe use a more generic way to get existing mappings: maybe use
  // BrAPI git YAML files as source instead of Swagger?
  $field_datatype = ucfirst(
    str_replace($current_datatype . '_', '', $field)
  );
  if (array_key_exists($field_datatype, $brapi_def['data_types'])) {
    $referenced_datatype = $field_datatype;
  }

  return $referenced_datatype;
}

/**
 * Tells if a field references another BrAPI datatype.
 *
 * @param string $field
 *   The current datatype field name to check.
 * @param BrapiDatatype $current_datatype_mapping
 *   The current datatype mapping containing the field to check.
 * @param array $brapi_def
 *   The BrAPI definition to use.
 *
 * @return the BrapiDatatype instance used to load field data, FALSE if there is
 *   no corresponding mapping object.
 */
function brapi_get_referenced_datatype_mapping(
  string $field,
  BrapiDatatype $current_datatype_mapping,
  array $brapi_def
) {
  $brapi_mapping = FALSE;
  $current_datatype = $current_datatype_mapping->getBrapiDatatype();
  $ref_datatype = brapi_is_reference_to_datatype(
    $field,
    $current_datatype,
    $brapi_def
  );
  if ($ref_datatype) {
    $drupal_mapping = $current_datatype_mapping->mapping[$field] ?? ['field' => '',];
    if ('_submapping' == $drupal_mapping['field']) {
      // Get data type mapping entities.
      $mapping_loader = \Drupal::service('entity_type.manager')
        ->getStorage('brapidatatype')
      ;
      if ('custom' == $drupal_mapping['submapping']) {
        $submapping = $current_datatype_mapping->id . '-' . lcfirst($ref_datatype);
        $brapi_mapping = $mapping_loader->load($submapping);
      }
      else {
        $brapi_mapping = $mapping_loader->load($drupal_mapping['submapping']);
      }
    }
  }
  return $brapi_mapping;
}

/**
 * Returns a given term plural as defined in BrAPI.
 *
 * This function supports lower case, uppercase, camelCase and CamelCase.
 *
 * @param string $term
 *   Term to pluralize.
 *
 * @return string
 *   Pluralized term.
 */
function brapi_get_term_plural(string $term) :string {
  if (array_key_exists($term, BRAPI_TO_PLURAL)) {
    $plural = BRAPI_TO_PLURAL[$term];
  }
  elseif (preg_match('#[a-z]#', $term)) {
    $plural = $term . 's';
  }
  else {
    // All upper case.
    $plural = $term . 'S';
  }
  return $plural;
}

/**
 * Returns a given term singular as defined in BrAPI.
 *
 * This function supports lower case, uppercase, camelCase and CamelCase.
 *
 * @param string $term
 *   Term to singularize.
 *
 * @return string
 *   Singularized term.
 */
function brapi_get_term_singular(string $term) :string {
  if (array_key_exists($term, BRAPI_TO_SINGULAR)) {
    $singular = BRAPI_TO_SINGULAR[$term];
  }
  elseif (('s' == substr($term, -1)) || ('S' == substr($term, -1))) {
    $singular = substr($term, 0, -1);
  }
  else {
    $singular = $term;
  }
  return $singular;
}


/**
 * Implements hook_brapi_call_CALL_SIGNATURE_result_alter().
 *
 * This implementation alters the 'data' result of list details. By default, it
 * is mapped to a Drupal array of string fields which is turned into an array
 * containing 'value' keys. The implementation removes the 'value' keys and
 * flatten the array.
 *
 * It also turns dates into the appropriate format.
 */
function brapi_brapi_call_get_v2_lists_listdbid_result_alter(&$json_array, array &$context) {
  // Flatten data.
  if (!empty($json_array['result']['data'])) {
    $json_array['result']['data'] = array_map(
      function ($d) {
        return $d['value'] ?? $d;
      },
      $json_array['result']['data']
    );
  }
  // Adjust date format.
  if (!empty($json_array['result']['dateCreated'])
    && is_numeric($json_array['result']['dateCreated'])
  ) {
    $json_array['result']['dateCreated'] = date(DATE_ATOM, $json_array['result']['dateCreated']);
  }
  if (!empty($json_array['result']['dateModified'])
    && is_numeric($json_array['result']['dateModified'])
  ) {
    $json_array['result']['dateModified'] = date(DATE_ATOM, $json_array['result']['dateModified']);
  }

  // Manage externalReferences.
  if (!empty($json_array['result']['externalReferences'])
    && is_array($json_array['result']['externalReferences'])
  ) {
    $new_extref_values = [];
    foreach ($json_array['result']['externalReferences'] as $extref) {
      if (is_array($extref) && !empty($extref['value'])) {
        $extref = json_decode($extref['value']) ?: $extref;
      }
      $new_extref_values[] = $extref;
    }
    $json_array['result']['externalReferences'] = $new_extref_values;
  }

}

/**
 * Implements hook_brapi_call_CALL_SIGNATURE_result_alter().
 */
function brapi_brapi_call_put_v2_lists_listdbid_result_alter(&$json_array, array &$context) {
  brapi_brapi_call_get_v2_lists_listdbid_result_alter($json_array, $context);
}

/**
 * Implements hook_brapi_call_CALL_SIGNATURE_result_alter().
 */
function brapi_brapi_call_post_v2_lists_listdbid_data_result_alter(&$json_array, array &$context) {
  brapi_brapi_call_get_v2_lists_listdbid_result_alter($json_array, $context);
}

/**
 * Implements hook_brapi_call_CALL_SIGNATURE_result_alter().
 */
function brapi_brapi_call_post_v2_lists_listdbid_items_result_alter(&$json_array, array &$context) {
  brapi_brapi_call_get_v2_lists_listdbid_result_alter($json_array, $context);
}

/**
 * Implements hook_brapi_BRAPI_DATA_TYPE_save_alter().
 */
function brapi_brapi_listdetails_save_alter(
  array &$data,
  BrapiDatatype &$data_type,
  EntityStorageInterface &$storage
) {
  // Convert dates.
  $date_created = strtotime($data['dateCreated'] ?? '');
  if ($date_created) {
    $data['dateCreated'] = $date_created;
  }
  $date_modified = strtotime($data['dateModified'] ?? '');
  if ($date_modified) {
    $data['dateModified'] = $date_modified;
  }
  // Manage externalReferences.
  if (!empty($data['externalReferences'])
    && is_array($data['externalReferences'])
  ) {
    $new_extref_values = [];
    foreach ($data['externalReferences'] as $extref) {
      if (!is_string($extref)) {
        $extref = json_encode($extref);
      }
      $new_extref_values[] = $extref;
    }
    $data['externalReferences'] = $new_extref_values;
  }
}

/**
 * Implements hook_brapi_call_CALL_SIGNATURE_result_alter().
 *
 * Handles specificities of the /lists/{listDbId}/data POST call.
 */
function brapi_brapi_call_post_v2_lists_listdbid_data_alter(&$json_array, array &$context) {
  // Variable aliases.
  $controller = &$context['controller'];
  $request = &$context['request'];
  $config = &$context['config'];
  $version = &$context['version'];
  $call = &$context['call'];
  $method = &$context['method'];

  // Load the list.
  $active_def = $config->get($version . 'def');
  $brapi_def = brapi_get_definition($version, $active_def);
  $datatype = 'ListDetails';
  $mapping_loader = \Drupal::service('entity_type.manager')->getStorage('brapidatatype');
  $datatype_id = brapi_generate_datatype_id($datatype, $version, $active_def);
  $datatype_mapping = $mapping_loader->load($datatype_id);
  if (empty($datatype_mapping)) {
    $message = "No mapping available for data type '$datatype_id'.";
    \Drupal::logger('brapi')->error($message);
    throw new NotFoundHttpException($message);
  }
  $filters = $request->attributes->get('_raw_variables')->all();
  $result = $datatype_mapping->getBrapiData($filters);
  if (!empty($result['entities'])) {
    $list_data = current($result['entities']);
  }

  // Get POST data.
  $parameters = $controller->getPostData($request);
  if (empty($parameters)) {
    throw new BadRequestHttpException('Missing input data to record.');
  }
  if (!is_array($parameters)) {
    throw new BadRequestHttpException('Invalid input data to record. Expecting a list of object identifiers.');
  }
  foreach ($parameters as $index => $object_id) {
    if (!is_string($object_id) && !is_int($object_id)) {
      throw new BadRequestHttpException('Invalid input data to record. Expecting a list of object identifiers but found an invalid identifier (at position ' . $index . ').');
    }
  }

  // Append new items to the list.
  $list_data['data'] = array_unique(
    array_merge($list_data['data'] ?? [], $parameters)
  );
  
  $status = [];
  $brapi_data = [];
  $id_field_name = $datatype_mapping->getBrapiIdField();
  try {
    // Save the list.
    $new_list_data = $datatype_mapping->saveBrapiData($list_data);
    $status[] = [
      'message'     => $datatype_mapping->getBrapiDatatype() . ' ' . ($new_list_data[$id_field_name] ?? '') . ' updated.',
      'messageType' => 'INFO',
    ];
    $brapi_data = $new_list_data;
  }
  catch (HttpException $e) {
    $status[] = [
      'message'     => 'Failed to update record. ' . $e->getMessage(),
      'messageType' => 'ERROR',
    ];
  }

  $result = ['result' => $brapi_data];
  $parameters = [
    'page_size'   =>  $brapi_data ? 1 : 0,
    'page'        =>  0,
    'total_count' =>  $brapi_data ? 1 : 0,
    'status'      =>  $status ?: NULL,
  ];
  $metadata = $controller->generateMetadata($request, $config, $parameters);

  // Returns the updated record.
  $json_array = $metadata + $result;
}

/**
 * Implements hook_brapi_definition_alter().
 *
 * Adds a delete method to /lists/{listDbId}.
 */
function brapi_brapi_definition_alter(
  array &$versions,
  string &$version_key,
) {
  if (empty($versions[$version_key]['calls']['/lists/{listDbId}']['definition']['delete'])) {
    $versions[$version_key]['calls']['/lists/{listDbId}']['definition']['delete'] = [
      "tags" => [
        "Lists",
      ],
      "summary" => "Removes a specific list",
      "description" => "Removes a specific list",
      "parameters" => [
        [
          "name" => "listDbId",
          "in" => "path",
          "description" => "The unique ID of this generic list",
          "required" => true,
          "style" => "simple",
          "explode" => false,
          "schema" => [
            "type" => "string",
          ],
        ],
        [
          "name" => "Authorization",
          "in" => "header",
          "description" => "HTTP HEADER - Token used for Authorization\n\n<strong> Bearer {token_string} </strong>",
          "required" => false,
          "style" => "simple",
          "explode" => false,
          "schema" => [
            "pattern" => "^Bearer .*\$",
            "type" => "string",
          ],
          "example" => "Bearer XXXX",
        ],
      ],
      "responses" => [
        200 => [
          "description" => "OK",
          "content" => [
            "application/json" => [
              "schema" => [
                "\$ref" => "#/components/schemas/ListsSingleResponse",
              ],
            ],
          ],
        ],
        400 => [
          "description" => "Bad Request",
          "content" => [
            "application/json" => [
              "schema" => [
                "type" => "string",
              ],
              "example" => "ERROR - 2018-10-08T18:15:11Z - Malformed JSON Request Object\n\nERROR - 2018-10-08T18:15:11Z - Invalid query parameter\n\nERROR - 2018-10-08T18:15:11Z - Required parameter is missing",
            ],
          ],
        ],
        401 => [
          "description" => "Unauthorized",
          "content" => [
            "application/json" => [
              "schema" => [
                "type" => "string",
              ],
              "example" => "ERROR - 2018-10-08T18:15:11Z - Missing or expired authorization token",
            ],
          ],
        ],
        403 => [
          "description" => "Forbidden",
          "content" => [
            "application/json" => [
              "schema" => [
                "type" => "string",
              ],
              "example" => "ERROR - 2018-10-08T18:15:11Z - User does not have permission to perform this action",
            ],
          ],
        ],
        404 => [
          "description" => "Not Found",
          "content" => [
            "application/json" => [
              "schema" => [
                "type" => "string",
              ],
              "example" => "ERROR - 2018-10-08T18:15:11Z - The requested object DbId is not found",
            ],
          ],
        ],
      ],
    ];
  }
}