(PHP 4, PHP 5, PHP 7)
preg_replace — Realiza uma pesquisa por uma expressão regular e a substitui.
$pattern
, mixed $replacement
, mixed $subject
[, int $limit
= -1
[, int &$count
]] ) : mixed
Pesquisa subject
para o correspondente
pattern
substituindo pelo
replacement
.
pattern
O padrão a ser pesquisado. Pode ser uma string ou um array com strings.
Diversas PCRE modifiers
também estão disponíveis, incluindo as obsoletas 'e
'
(PREG_REPLACE_EVAL), que é específica para esta função.
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 extra
pattern
s será substituído por uma string vazia.
replacement
pode conter referências na forma
\\n
ou (desde PHP 4.0.4)
$n
, com a última forma sendo
preferêncial. Toda referência será substituída pelo texto capturado pelo
padrão entre parentêsesn'th.
n pode ser de 0 to 99, e
\\0
ou $0
refere-se ao texto correspondente
por todo o pattern. A abertura de parentêses são contadas da esquerda para direita
(a partir de 1) para obter o número de subpattern de captura.
Para uso da contrabarra no replacement, deve ser duplicada
("\\\\"
string PHP ).
Quando se trabalha com uma padrão de substituição, onde a backreference
é imediatamente seguida por outro número (isto é.: inserido um número literal
imediatamento de um padrão correspondente), você não pode usar a habitual
notação \\1
para seu backreference.
\\11
, por exemplo, iria confundir a função
preg_replace() pois não saberá se quer o
\\1
backreference seguido por um literal
1
, ou o \\11
backreference
seguido por nada. Neste caso a solução é usar \${1}1
.
Isto cria um isolado $1
backreference, deixando-o
1
como um literal.
Ao usar um obsoleto e
modificador, esta função escapa
alguns caracteres (ou seja '
, "
,
\
and NULL) nas strings que substituem os
backreferences. Isto é feito para garantir que nenhum erro surja
do uso do backreference com aspas simples ou duplas (por exemplo,
'strlen(\'$1\')+strlen("$2")'
). Certifique-se da
sintaxe string do PHP
para saber exatamente como a string interpretada será considerada.
subject
String 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.
limit
O máximo possível de substituições para cada patern em cada
subject
string. O padrão é
-1
(sem limite).
count
Se especificado, 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 a correspondência for encontrada, o novo subject
será devolvido, caso contrário subject
será
devolvido inalterado ou null
se um erro ocorreu.
Um nível de erro E_DEPRECATED
é emitido quando passado
o modificador "\e".
Exemplo #1 Usando backreferences seguido 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 irá imprimir:
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 irá imprimir:
The bear black slow jumped over the lazy dog.
By ksorting patterns and replacements, we should get what we wanted.
<?php
ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);
?>
O exemplo acima irá imprimir:
The slow black bear jumped over the lazy dog.
Exemplo #3 Replacing several values
<?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 irá imprimir:
$startDate = 5/27/1999
Exemplo #4 Strip whitespace
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 irá imprimir:
xp***to 3
Nota:
Ao usar arrays com
pattern
ereplacement
, 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 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().