(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 a uma string exata, e não a uma expressão, considere usar str_replace() ou str_ireplace() no lugar desta função.
pattern
A expressão a ser pesquisada. 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 for uma string
e o parâmetro pattern
for um array, todas as expressões do array
serão substituídos por esta string. Se ambos os parâmetros
pattern
e replacement
forem arrays, cada expressão correspondida de pattern
será
substituída pelo seu replacement
correspondente. Se
houver menos elementos no array replacement
que no array 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
à expressão inteira. Parênteses de abertura são contados da esquerda para direita
(iniciando em 1) para obter o número da sub-expressão de captura.
Note que a barra invertida em strings literais pode precisar ser escapada.
Quando se trabalha com uma expressão de substituição, onde a referência retroativa
é imediatamente seguida por outro número (isto é, inserido um número literal
imediatamente após uma expressão correspondente), não se pode usar a habitual
notação \1
para a referência retroativa.
\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 retroativas. Isto é feito para garantir que nenhum erro de sintaxe surja
pelo uso de referência retroativa 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.
subject
String ou um array com strings para pesquisar e substituir.
Se subject
for um array, então a pesquisa e
a substituição serão executadas em cada entrada de subject
,
e o valor de retorno será 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 expressão em cada string de
subject
. O padrão é
-1
(sem limite).
count
Se especificada, essa variável será preenchida com o número de substiuições realizadas.
preg_replace() retorna um array se o
parâmetro subject
for 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 tiver ocorrido.
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 retroativas 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 arrays 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 expressõ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);
// O resultado será 'foo o'
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
pattern
ereplacement
, as chaves são processadas na ordem em que aparecem no array. Isto não é necessariamente o mesmo que a ordem dos índices numéricos. Se os índices forem utilizados para indentificar qualpattern
deve 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
pattern
ereplacement
forem arrays, as regras de correspondência irão operar sequencialmente. Isto é, o segundo parpattern
/replacement
irá operar na string que resulta do primeiro parpattern
/replacement
, e não na string original. Se for desejado simular substituições operando em paralelo, como inversão de dois valores, substitua uma expressã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
?>