preg_replace_callback

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

preg_replace_callback — Executa uma busca por expressão regular e substitui usando uma chamada de retorno

Descrição

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

O comportamento desta função é quase idêntico ao da preg_replace(), exceto pelo fato de que ao invés do parâmetro replacement, deve-se especificar o parâmetro callback.

Parâmetros

pattern

A padrão usado para a busca. Pode ser tanto uma string como um array de strings.

callback

Uma função de retorno que será chamada e passado um array dos elementos correspondentes na string subject. A função deve retornar a string substituta. Esta é a assinatura da função de retorno:

handler(array $matches): string

Normalmente será necessária uma função callback para preg_replace_callback() em apenas um lugar. Neste caso pode-se usar uma função anônima para declarar a função de retorno dentro da chamada a preg_replace_callback(). Desta forma, todas as informações para a chamada estarão no mesmo lugar e não poluem o espaço de nomes com um nome de função que não é usado em nenhum outro lugar.

Example #1 preg_replace_callback() e função anônima

<?php
/* um filtro de linha de comando em estilo Unix para converter maiúsculas
 * no início de parágrafos para letras minúsculas */
$fp = fopen("php://stdin", "r") or die("não foi possível ler a entrada padrão");
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

A string ou array com strings para procurar e modificar.

limit

O máximo de possíveis substituições para cada expressão em cada string de subject. O padrão é -1 (sem limite).

count

Se especificado, esta variável será preenchida com o número de substituições feitas.

flags

flags pode ser uma combinação das opções PREG_OFFSET_CAPTURE e PREG_UNMATCHED_AS_NULL, que influenciam o formato do array de correspondências. Veja a descrição em preg_match() para mais detalhes.

Valor Retornado

preg_replace_callback() retorna um array se o parâmetro subject for um array, ou uma string caso contrário. Em caso de erro o valor de retorno é null.

Se ocorrer correspondência, a nova string será retornada, caso contrário subject será retornada inalterada.

Erros/Exceções

Se o padrão de expressão regular passado não for compilado para uma expressão regular válida, um E_WARNING será emitido.

Registro de Alterações

Versão Descrição
7.4.0 O parâmetro flags foi adicionado.

Exemplos

Example #2 Exemplo de preg_replace_callback()

<?php
// este texto foi usado em 2002
// se quisermos atualizá-lo para 2003
$text = "Dia da mentira é em 01/04/2002\n";
$text.= "Último Natal foi em 25/12/2001\n";
// a chamada de retorno
function next_year($matches)
{
    // como sempre: $matches[0] é a correspondência completa
    // $matches[1] é a correspondência da primeira sub-expressão
    // envolvida por '(...)' e assim por diante
    return $matches[1].($matches[2]+1);
}
echo preg_replace_callback(
            "|(\d{2}/\d{2}/)(\d{4})|",
            "next_year",
            $text);

?>

O exemplo acima produzirá:

Dia da mentira é em 01/04/2003
Último Natal foi em 25/12/2002

Example #3 preg_replace_callback() usando estrutura recursiva para manipular código BB encapsulado

<?php
$input = "plain [indent] deep [indent] deeper [/indent] deep [/indent] plain";

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;
?>

Veja Também