* Returns a substring of the input value.
*
* The substr process plugin returns the portion of the input value specified by
- * the start and length parameters. This is a wrapper around the PHP substr()
- * function.
+ * the start and length parameters. This is a wrapper around
+ * \Drupal\Component\Utility\Unicode::substr().
*
* Available configuration keys:
* - start: (optional) The returned string will start this many characters after
- * the beginning of the string. Defaults to NULL.
+ * the beginning of the string, defaults to 0.
* - length: (optional) The maximum number of characters in the returned
- * string. Defaults to NULL.
+ * string, defaults to NULL.
*
- * If start is NULL and length is an integer, the start position is the
+ * If start is 0 and length is an integer, the start position is the
* beginning of the string. If start is an integer and length is NULL, the
* substring starting from the start position until the end of the string will
- * be returned. If both start and length are NULL the entire string is returned.
+ * be returned. If start is 0 and length is NULL the entire string is returned.
*
* Example:
*
* new_text_field:
* plugin: substr
* source: some_text_field
- * start: 6
- * length: 10
+ * start: 6
+ * length: 10
* @endcode
- *
* If some_text_field was 'Marie Skłodowska Curie' then
* $destination['new_text_field'] would be 'Skłodowska'.
*
* The PHP equivalent of this is:
- *
* @code
* $destination['new_text_field'] = substr($source['some_text_field'], 6, 10);
* @endcode
*
+ * The substr plugin requires that the source value is not empty. If empty
+ * values are expected, combine skip_on_empty process plugin to the pipeline:
+ * @code
+ * process:
+ * new_text_field:
+ * -
+ * plugin: skip_on_empty
+ * method: process
+ * source: some_text_field
+ * -
+ * plugin: substr
+ * source: some_text_field
+ * start: 6
+ * length: 10
+ * @endcode
+ *
* @see \Drupal\migrate\Plugin\MigrateProcessInterface
*
* @MigrateProcessPlugin(