Выполняет поиск по регулярному выражению и заменяет совпадения callback-функцией

# preg_replace_callback

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

preg_replace_callback — Выполняет поиск по регулярному выражению и заменяет совпадения callback-функцией

### Описание

function preg_replace_callback(
string|array `$pattern`,
callable `$callback`,
string|array `$subject`,
int `$limit` = -1,
int `&$count` = `null`,
int `$flags` = 0
): string|array|null

Поведение функции во многом напоминает поведение функции preg_replace(), за исключением передачи `callback`-функции вместо параметра `replacement`.

### Список параметров

`pattern`

  Искомый шаблон: строка или массив строк.

`callback`

  Callback-функция для вызова и передачи массива совпадений, которые функция нашла в строке `subject`. Сигнатура callback-функции предусматривает возврат изменённой строки:

  function handler(array `$matches`): string

  При вызове функции preg_replace_callback() `callback`-функцию часто вызывают однократно, поэтому для объявления обратного вызова внутри вызова функции preg_replace_callback() объявляют анонимную функцию. При таком способе организации кода информация о вызове собирается в одном месте и не загромождает текущее пространство имён названием callback-функции, которая не вызывается в другом месте.

  Пример #1 Пример вызова функции preg_replace_callback() с анонимной callback-функцией

      <?php

      /* Фильтр командной строки в стиле Unix-систем
       * для преобразования заглавных букв в начале параграфа в строчные */
      $fp = fopen("php://stdin", "r") or die("не удалось прочесть stdin");
      while (!feof($fp)) {
          $line = fgets($fp);

          $line = preg_replace_callback(
              '|<p>\s*\w|',
              function ($matches) {
                  return strtolower($matches[0]);
              },
              $line
          );

          echo $line;
      }

      fclose($fp);

      ?>

`subject`

  Строка или массив строк для поиска и замены.

`limit`

  Максимально возможное количество замен для каждого шаблона в каждой строке `subject`. По умолчанию значение равно `-1` (без ограничений).

`count`

  При вызове с этим параметром переменная заполняется количеством замен, которые выполнила функция.

`flags`

  Параметр `flags` принимает комбинацию флагов `PREG_OFFSET_CAPTURE` и `PREG_UNMATCHED_AS_NULL`, которые влияют на формат массива совпадений. Дополнительную информацию даёт описание функции preg_match().

### Возвращаемые значения

Функция preg_replace_callback() возвращает массив, если в параметр `subject` передали массив, иначе возвращает строку. Функция возвращает значение `null`, если возникла ошибка.

Функция возвращает новую строку, если нашла совпадения, иначе возвращает строку `subject` без изменений.

### Ошибки

Если передали шаблон регулярного выражения, который не компилируется в допустимое регулярное выражение, выдаётся ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | Добавили параметр `flags`.

### Примеры

Пример #2 Пример использования preg_replace_callback()

    <?php

    // Текст написали в 2002 году
    // и требуется обновить даты на 2003 год
    $text = "День смеха отмечали 01/04/2002\n";
    $text.= "Последнее Рождество отмечали 24/12/2001\n";

    // Callback-функция
    function next_year($matches)
    {
        // Стандартно: $matches[0] — полное вхождение шаблона,
        // $matches[1] — вхождение первой подмаски
        // в круглых скобках '(...)' и так далее...
      return $matches[1].($matches[2]+1);
    }

    echo preg_replace_callback(
        "|(\d{2}/\d{2}/)(\d{4})|",
        "next_year",
        $text,
    );

    ?>

Результат выполнения приведённого примера:

    День смеха отмечали 01/04/2003
    Последнее Рождество отмечали 24/12/2002

Пример #3 Пример рекурсивной обработки BB-кода функцией preg_replace_callback()

    <?php

    $input = "верх [indent] глубже [indent] ещё глубже [/indent] глубже [/indent] верх";

    function parseTagsRecursive($input)
    {

        $regex = '#\[indent]((?:[^[]|\[(?!/?indent])|(?R))+)\[/indent]#';

        if (is_array($input)) {
            $input = '<div style="margin-left: 10px">'.$input[1].'</div>';
        }

        return preg_replace_callback($regex, 'parseTagsRecursive', $input);
    }

    $output = parseTagsRecursive($input);

    echo $output;

    ?>

### Смотрите также

- Регулярные PCRE-выражения
- preg_replace_callback_array() - Выполняет поиск и замену по регулярному выражению с использованием функций обратного вызова
- preg_quote() - Экранирует символы в регулярных выражениях
- preg_replace() - Выполняет поиск и замену по регулярному выражению
- preg_last_error() - Возвращает код ошибки выполнения последнего регулярного выражения PCRE
- Анонимные функции

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open