preg_replace_callback
preg_split
PCRE Functions
PHP Manual

# preg_replace

(PHP 4, PHP 5)

preg_replace — Realizar una operación de búsqueda y reemplazo con expresiones regulares

### Descripción

mixed preg_replace ( mixed `$patron` , mixed `$reemplazo` , mixed `$asunto` [, int `$limite` [, int `&$conteo` ]] )

Busca en `asunto` por coincidencias con `patron` y las reemplaza con `reemplazo` .

### Lista de parámetros

`patron`

  El patrón a buscar. Puede ser una cadena o una matriz con cadenas.

  El modificador e hace que preg_replace() trate el parámetro `reemplazo` como código PHP después de que las sustituciones de referencias correspondientes son realizadas. Consejo: asegúrese de que `reemplazo` constituya una cadena de código PHP válido, de otra forma PHP se quejará sobre un error de análisis sintáctico en la línea que contiene la llamada a preg_replace().

`reemplazo`

  La cadena o una matriz con las cadenas de reemplazo. Si este parámetro es una cadena y el parámetro `patron` es una matriz, todos los patrones serán reemplazados por esa cadena. Si tanto `patron` como `reemplazo` son matrices, cada `patron` será reemplazado por su contraparte en `reemplazo` . Si hay menos claves en la matriz `reemplazo` que en la matriz `patron` , los patrones extra serán reemplazados con una cadena vacía.

  `reemplazo` puede contener referencias de la forma \\n o (desde PHP 4.0.4) $n, siendo este último estilo el más recomendable. Cada referencia de este tipo será reemplazada con el texto capturado por el nésimo patrón entre paréntesis. n puede ser un valor de 0 a 99, y \\0 o $0 hacen referencia al texto coincidente con el patrón completo. Los paréntesis de apertura son contados de izquierda a derecha (comenzando en 1) para obtener el número del sub-patrón de captura.

  Cuando se trabaja con un patrón de reemplazo en donde una referencia hacia atrás está inmediatamente seguida por otro número (es decir, se coloca un número literal inmediatamente después de un patrón coincidente), no es posible usar la familiar notación \\1 para la referencia hacia atrás. \\11, por ejemplo, confundiría a preg_replace() ya que no es claro si se desea la referencia hacia atrás \\1 seguida de un 1 literal, o la referencia hacia atrás \\11 seguida por nada. En este caso la solución es usar \${1}1. Esto crea una referencia hacia atrás separada $1, dejando el 1 como una secuencia literal.

  Cuando se usa el modificador e, esta función escapa algunos caracteres (a saber ', ", \ y NULL) en las cadenas que reemplazan las referencias hacia atrás. Esto es hecho para asegurarse de que no surjan errores de sintaxis por el uso de referencias hacia atrás con comillas simples o dobles (p.ej. 'strlen(\'$1\')+strlen("$2")'). Asegúrese de conocer la sintaxis de cadenas de PHP para saber exactamente cómo lucirá la cadena interpretada.

`asunto`

  La cadena o una matriz con cadenas para buscar y reemplazar.

  Si `asunto` es una matriz, entonces la operación de búsqueda y reemplazo se realiza sobre cada entrada de `asunto` , y el valor de retorno es una matriz también.

`limite`

  La cantidad máxima posible de reemplazos para cada patrón en cada cadena `asunto` . Su valor predeterminado es -1 (sin límite).

`conteo`

  Si se especifica, esta variables será llenada con el número de reemplazos realizados.

### Valores retornados

preg_replace() devuelve una matriz si el parámetro `asunto` es una matriz, o una cadena de lo contrario.

Si se encuentran coincidencias, el nuevo `asunto` será devuelto, de otra forma `asunto` será devuelto intacto.

### Registro de cambios

Versión | Descripción
--- | ---
5.1.0 | Se agregó el parámetro `conteo`
4.0.4 | Se agregó la forma '$n' para el parámetro `reemplazo`
4.0.2 | Se agregó el parámetro `limite`

### Ejemplos

Example #1 Uso de referencias hacia atrás seguidas de literales numéricos

`<?php
$cadena = 'April 15, 2003';
$patron = '/(\w+) (\d+), (\d+)/i';
$reemplazo = '${1}1,$3';
echo preg_replace($patron, $reemplazo, $cadena);
?>`

El resultado del ejemplo seria:

    April1,2003

Example #2 Uso de matrices indexadas con preg_replace()

`<?php
$cadena = 'The quick brown fox jumped over the lazy dog.';
$patrones[0] = '/quick/';
$patrones[1] = '/brown/';
$patrones[2] = '/fox/';
$reemplazos[2] = 'bear';
$reemplazos[1] = 'black';
$reemplazos[0] = 'slow';
echo preg_replace($patrones, $reemplazos, $cadena);
?>`

El resultado del ejemplo seria:

    The bear black slow jumped over the lazy dog.

Ordenando por clave los patrones y reemplazos, podemos obtener lo que queríamos.

`<?php
ksort($patrones);
ksort($reemplazos);
echo preg_replace($patrones, $reemplazos, $cadena);
?>`

El resultado del ejemplo seria:

    The slow black bear jumped over the lazy dog.

Example #3 Reemplazo de varios valores

`<?php
$patrones = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
'/^\s*{(\w+)}\s*=/');
$reemplazar = array ('\3/\4/\1\2', '$\1 =');
echo preg_replace($patrones, $reemplazar, '{fechaInicio} = 1999-5-27');
?>`

El resultado del ejemplo seria:

    $fechaInicio = 5/27/1999

Example #4 Uso del modificador 'e'

`<?php
preg_replace("/(<\/?)(\w+)([^>]*>)/e",
"'\\1'.strtoupper('\\2').'\\3'",
$cuerpo_html);
?>`

Esto pasaría a mayúsculas todas las etiquetas HTML en el texto de entrada.

Example #5 Eliminar espacios en blanco

Este ejemplo remueve espacios de más de una cadena.

`<?php
$cadena = 'foo o';
$cadena = preg_replace('/\s\s+/', ' ', $cadena);
// Ahora sera 'foo o'
echo $cadena;
?>`

Example #6 Uso del parámetro `conteo`

`<?php
$conteo = 0;
echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $conteo);
echo $conteo; //3
?>`

El resultado del ejemplo seria:

    xp***to
    3

### Notes

> Note: Cuando se usan matrices con `patron` y `reemplazo` , las claves son procesadas en el orden en que aparecen en la matriz. Esto no es necesariamente lo mismo que el orden de índices numéricos. Si usan índices para identificar cuál `patron` debería ser reemplazado por cuál `reemplazo` , debería usar ksort() sobre cada matriz antes de llamar preg_replace().

### Ver también

- preg_match() - Realizar una comparación de expresión regular
- preg_replace_callback() - Realizar una búsqueda con expresiones regulares y generar reemplazos usando una llamada de retorno
- preg_split() - Separar una cadena por una expresión regular

preg_replace_callback
preg_split
PCRE Functions
PHP Manual