www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/migrate/src/Plugin/migrate/process/Substr.php

   1 <?php
   2
   3 namespace Drupal\migrate\Plugin\migrate\process;
   4
   5 use Drupal\migrate\ProcessPluginBase;
   6 use Drupal\migrate\MigrateExecutableInterface;
   7 use Drupal\migrate\Row;
   8 use Drupal\migrate\MigrateException;
   9
  10 /**
  11  * Returns a substring of the input value.
  12  *
  13  * The substr process plugin returns the portion of the input value specified by
  14  * the start and length parameters. This is a wrapper around mb_substr().
  15  *
  16  * Available configuration keys:
  17  * - start: (optional) The returned string will start this many characters after
  18  *   the beginning of the string, defaults to 0.
  19  * - length: (optional) The maximum number of characters in the returned
  20  *   string, defaults to NULL.
  21  *
  22  * If start is 0 and length is an integer, the start position is the
  23  * beginning of the string. If start is an integer and length is NULL, the
  24  * substring starting from the start position until the end of the string will
  25  * be returned. If start is 0 and length is NULL the entire string is returned.
  26  *
  27  * Example:
  28  *
  29  * @code
  30  * process:
  31  *   new_text_field:
  32  *     plugin: substr
  33  *     source: some_text_field
  34  *     start: 6
  35  *     length: 10
  36  * @endcode
  37  * If some_text_field was 'Marie Skłodowska Curie' then
  38  * $destination['new_text_field'] would be 'Skłodowska'.
  39  *
  40  * The PHP equivalent of this is:
  41  * @code
  42  * $destination['new_text_field'] = substr($source['some_text_field'], 6, 10);
  43  * @endcode
  44  *
  45  * The substr plugin requires that the source value is not empty. If empty
  46  * values are expected, combine skip_on_empty process plugin to the pipeline:
  47  * @code
  48  * process:
  49  *   new_text_field:
  50  *    -
  51  *      plugin: skip_on_empty
  52  *      method: process
  53  *      source: some_text_field
  54  *    -
  55  *      plugin: substr
  56  *      source: some_text_field
  57  *      start: 6
  58  *      length: 10
  59  * @endcode
  60  *
  61  * @see \Drupal\migrate\Plugin\MigrateProcessInterface
  62  *
  63  * @MigrateProcessPlugin(
  64  *   id = "substr"
  65  * )
  66  */
  67 class Substr extends ProcessPluginBase {
  68
  69   /**
  70    * {@inheritdoc}
  71    */
  72   public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
  73     $start = isset($this->configuration['start']) ? $this->configuration['start'] : 0;
  74     if (!is_int($start)) {
  75       throw new MigrateException('The start position configuration value should be an integer. Omit this key to capture from the beginning of the string.');
  76     }
  77     $length = isset($this->configuration['length']) ? $this->configuration['length'] : NULL;
  78     if (!is_null($length) && !is_int($length)) {
  79       throw new MigrateException('The character length configuration value should be an integer. Omit this key to capture from the start position to the end of the string.');
  80     }
  81     if (!is_string($value)) {
  82       throw new MigrateException('The input value must be a string.');
  83     }
  84
  85     // Use optional start or length to return a portion of $value.
  86     $new_value = mb_substr($value, $start, $length);
  87     return $new_value;
  88   }
  89
  90 }