Issue #3225569: Improve str_replace documentation.

src/Plugin/migrate/process/StrReplace.php

@@ -8,58 +8,60 @@ use Drupal\migrate\ProcessPluginBase;
 use Drupal\migrate\Row;
 
 /**
- * Uses the str_replace() method on a source string.
+ * Uses either str_replace() or preg_replace() function on a source string.
  *
- * @MigrateProcessPlugin(
- *   id = "str_replace"
- * )
+ * Available configuration keys:
+ * - search: The value or pattern being searched for. It can be either a string
+ *   or an array with strings.
+ * - replace: The replacement value that replaces found search values. It can be
+ *   either a string or an array with strings.
+ * - regex: (optional) If not empty, then preg_replace() function will be used
+ *   instead of str_replace(). Defaults to FALSE.
+ * - case_insensitive: (optional) If not empty, then str_ireplace() function
+ *   will be used instead of str_replace(). Defaults to FALSE. Ignored if
+ *   'regex' is enabled.
  *
- * @codingStandardsIgnoreStart
+ * Depending on the value of 'regex', the rules for
+ * @link http://php.net/manual/function.str-replace.php str_replace @endlink
+ * or
+ * @link http://php.net/manual/function.preg-replace.php preg_replace @endlink
+ * apply. This means that you can provide arrays as values, your replace string
+ * can include backreferences, etc.
  *
  * To do a simple hardcoded string replace, use the following:
  * @code
  * field_text:
  *   plugin: str_replace
  *   source: text
- *   search: foo
- *   replace: bar
+ *   search: et
+ *   replace: that
  * @endcode
- * If the value of text is "vero eos et accusam et justo vero" in source, foo is
- * "et" in search and bar is "that" in replace, field_text will be "vero eos
- * that accusam that justo vero".
+ * If the value of text is "vero eos et accusam et justo vero" in source,
+ * field_text will be "vero eos that accusam that justo vero".
  *
- * Case insensitive searches can be achieved using the following:
+ * Case-insensitive searches can be achieved using the following:
  * @code
  * field_text:
  *   plugin: str_replace
  *   case_insensitive: true
  *   source: text
- *   search: foo
- *   replace: bar
+ *   search: vero
+ *   replace: that
  * @endcode
- * If the value of text is "VERO eos et accusam et justo vero" in source, foo is
- * "vero" in search and bar is "that" in replace, field_text will be "that eos
- * et accusam et justo that".
+ * If the value of text is "VERO eos et accusam et justo vero" in source,
+ * field_text will be "that eos et accusam et justo that".
  *
- * Also regular expressions can be matched using:
+ * Also, regular expressions can be matched using:
  * @code
  * field_text:
  *   plugin: str_replace
  *   regex: true
  *   source: text
- *   search: foo
- *   replace: bar
+ *   search: /[0-9]{3}/
+ *   replace: the
  * @endcode
  * If the value of text is "vero eos et 123 accusam et justo 123 duo" in source,
- * foo is "/[0-9]{3}/" in search and bar is "the" in replace, field_text will be
- * "vero eos et the accusam et justo the duo".
- *
- * Depending on the value of 'regex', the rules for
- * @link http://php.net/manual/function.str-replace.php str_replace @endlink
- * or
- * @link http://php.net/manual/function.preg-replace.php preg_replace @endlink
- * apply. This means that you can provide arrays as values, your replace string
- * can include backreferences, etc.
+ * field_text will be "vero eos et the accusam et justo the duo".
  *
  * Multiple values can be matched like this:
  * @code
@@ -76,14 +78,14 @@ use Drupal\migrate\Row;
  *   plugin: str_replace
  *   regex: true
  *   source: text
- *   search: foo
- *   replace: bar
+ *   search: /@(\S+)/
+ *   replace: $1
  * @endcode
- * If the value of text is "@username" in source,
- * foo is "/@(\S+)/" in search and bar is "$1" in replace, field_text will be
- * "username".
+ * If the value of text is "@username" in source, field_text will be "username".
  *
- * @codingStandardsIgnoreEnd
+ * @MigrateProcessPlugin(
+ *   id = "str_replace"
+ * )
  */
 class StrReplace extends ProcessPluginBase {