Funções da PCRE
PHP Manual

preg_replace

(PHP 4, PHP 5)

preg_replaceRealiza uma pesquisa por uma expressão regular e a substitui.

Descrição

mixed preg_replace ( mixed $pattern , mixed $replacement , mixed $subject [, int $limit = -1 [, int &$count ]] )

Pesquisa subject para o correspondente pattern substituindo pelo replacement.

Parâmetros

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 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.

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.

Valor Retornado

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.

Erros

Um nível de erro E_DEPRECATED é emitido quando passado o modificador "\e".

Changelog

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

Exemplos

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', -$count);
echo 
$count//3
?>

O exemplo acima irá imprimir:

xp***to
3

Notas

Nota:

Ao usar arrays com pattern e replacement, 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 qual pattern deve ser substituído por qual replacement, é necessário executar a função ksort() em cada array antes de chamar a função preg_replace().

Veja Também


Funções da PCRE
PHP Manual