(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
]] )
Pesquisa subject para o correspondente
pattern substituindo pelo
replacement.
patternO 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
patterns 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 \\1para 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.
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.
limit
O máximo possível de substituições para cada patern em cada
subject string. O padrão é
-1 (sem limite).
countSe 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".
| Versão | Descrição |
|---|---|
| 5.5.0 | O modificador /e está obsoleto. Use preg_replace_callback() como alternativa. Veja a documentação PREG_REPLACE_EVAL para adicionais informações sobre riscos de segurança. |
| 5.1.0 |
Adicinado o parâmetro count
|
| 4.0.4 |
Adicionado a forma '$n' para o parâmetro replacement
|
| 4.0.2 |
Adicionado o parâmetro limit
|
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
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().