(PHP 4, PHP 5, PHP 7, PHP 8)
preg_replace — Realiza uma pesquisa por uma expressão regular e substitui
$pattern,$replacement,$subject,$limit = -1,&$count = null Pesquisa subject por correspondências a pattern e substitui-as por replacement.
Para procurar correspondência por uma string exata, e não por um padrão, considere usar str_replace() ou str_ireplace() no lugar desta função.
patternO padrão a ser pesquisado. Pode ser uma string ou um array com strings.
Diversos modificadores PCRE também estão disponíveis.
replacement A string ou array com strings para substituir. Se este parâmetro é uma string e o parâmetro pattern é um array, todos patterns vão ser substituídos por esta string. Se ambos pattern e replacement parâmetros são arrays, cada pattern vai ser substituído pelo seureplacement correspondente. Se houver menos elementos no replacement array do que no pattern array, qualquer pattern extra será substituído por uma string vazia.
replacement pode conter referências na forma \n ou $n, com a última forma sendo a preferível. Cada referência desse tipo será substituída pelo texto capturado pelo n-ésimo padrão entre parentêses. n pode ser de 0 to 99, e \0 ou $0 referem-se ao texto correspondente ao padrão inteiro. Parênteses de abertura são contados da esquerda para direita (iniciando em 1) para obter o número do sub-padrão de captura. Note que barra invertida em strings literais podem precisar ser escapados.
Quando se trabalha com uma padrão de substituição, onde a referência passada é imediatamente seguida por outro número (isto é, inserido um número literal imediatamente após um padrão correspondente), não se pode usar a habitual notação \1 para a referência passada. \11, por exemplo, iria confundir a função preg_replace() pois ela não saberá se o desejado é a referência \1 seguida por um literal 1, ou a referência \11 seguida por nada. Neste caso, a solução é usar ${1}1. Isto cria uma referência $1 isolada, deixando o 1 como um literal.
Ao usar o modificador e que está defasado, esta função escapa alguns caracteres (nomeadamente ', ", \ e NULL) nas strings que substituem as referências passadas. Isto é feito para garantir que nenhum erro de sintaxe surja de uso de referência passada com aspas simples ou duplas (por exemplo, 'strlen(\'$1\')+strlen("$2")'). Certifique-se de estar ciente da sintaxe string do PHP para ter uma visão exata de como será a string interpretada.
subjectString ou um array com strings para pesquisar e substituir.
Se subject é um array, então a pesquisa e a substituição são executadas em cada entrada do subject, e o valor de retorno é um array também.
Se o array subject for associativo, as chaves são preservadas no valor de retorno.
limit O máximo possível de substituições para cada padrão em cada string de subject. O padrão é -1 (sem limite).
countSe especificada, essa variável será preenchida com o número de substiuições realizadas.
preg_replace() retorna um array se o parâmetro subject é um array, caso contrário retorna uma string.
Se correspondências forem encontradas, o novo subject será devolvido, caso contrário subject será devolvido inalterado ou null se um erro ocorreu.
Usar o modificador "\e" é um erro; um erro de nível E_WARNING é emitido neste caso.
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.
Exemplo #1 Usando referências passadas seguidas por literais numéricos
<?php
$string = 'April 15, 2003';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);
?>O exemplo acima produzirá:
April1,2003
Exemplo #2 Usando array indexados com preg_replace()
<?php
$string = 'The quick brown fox jumped over the lazy dog.';
$patterns = array();
$patterns[0] = '/quick/';
$patterns[1] = '/brown/';
$patterns[2] = '/fox/';
$replacements = array();
$replacements[2] = 'bear';
$replacements[1] = 'black';
$replacements[0] = 'slow';
echo preg_replace($patterns, $replacements, $string);
?>O exemplo acima produzirá:
The bear black slow jumped over the lazy dog.
Ao ordenar padrões e substituições com ksort, obtém-se o desejado.
<?php
ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);
?>O exemplo acima produzirá:
The slow black bear jumped over the lazy dog.
Exemplo #3 Substituindo vários valores
<?php
$patterns = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
'/^\s*{(\w+)}\s*=/');
$replace = array ('\3/\4/\1\2', '$\1 =');
echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');
?>O exemplo acima produzirá:
$startDate = 5/27/1999
Exemplo #4 Removendo espaços
Este exemplo retira o excesso de espaçoes em branco de uma string.
<?php
$str = 'foo o';
$str = preg_replace('/\s\s+/', ' ', $str);
// This will be 'foo o' now
echo $str;
?>Exemplo #5 Usando o parâmetro count
<?php
$count = 0;
echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
echo $count; //3
?>O exemplo acima produzirá:
xp***to 3
Nota:
Ao usar arrays com
patternereplacement, as chaves são processadas na ordem que aparecem no array. Isto não é necessariamente o mesmo que a ordem de índice numérico. Se é feito o uso dos índices para indentificar qualpatterndeve ser substituído por qualreplacement, é necessário executar a função ksort() em cada array antes de chamar a função preg_replace().
Nota:
Quando ambos
patternereplacementforem arrays, as regras de correspondência irão operar sequancialmente. Isto é, o segundo parpattern/replacementirá operar na string que resulta do primeiro parpattern/replacement, e não da string original. Se for desejado simular substituições operando em paralelo, como inversão de dois valores, substitua um padrão por uma referência intermediária, e então em um par posterior substitua a referência intermediária pelo substituto desejado.<?php
$p = array('/a/', '/b/', '/c/');
$r = array('b', 'c', 'd');
print_r(preg_replace($p, $r, 'a'));
// prints d
?>