preg_replace

(PHP 4, PHP 5)

preg_replace — Realiza una búsqueda y sustitución de una expresión regular

Descripción

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

Busca en subject coincidencias de pattern y las reemplaza con replacement.

Parámetros

pattern

El patrón de búsqueda. Puede ser tanto una cadena como un array de cadenas.

También están disponibles varios modificadores de PCRE, incluyendo el obsoleto 'e' (PREG_REPLACE_EVAL), que es específico de esta función.

replacement

La cadena o array de cadenas a reemplazar. Si este parámetro es una cadena y el parámetro pattern es un array, todos los patrones serán sustituidos por esa cadena. Si ambos parámetros, pattern y replacement, son arrays, cada pattern será reemplazado por el replacement equivalente. Si hay menos elementos en el array replacement que en el array pattern, cualquier pattern extra será reemplazado por una cadena vacía.

replacement puede contener referencias de la forma \\n o (desde PHP 4.0.4) $n, siendo preferida la última forma. Cada referencia de este tipo será sustituida por el texto capturado por el n-simo patrón entre paréntesis. n puede ser desde 0 a 99, y \\0 o $0 se refiere al texto coincidido por el patrón completo. Los paréntesis de apertura se cuentan de izquierda a derecha (comenzando por 1) para obtener el número de sub-patrones de captura. Se debe doblar la barra invertida para poder usarla en la sustitución (cadena PHP "\\\\").

Cuando se trabaja con un patrón de sustitución donde una retro-referencia es immediatamente seguida de otro número (p.ej.: colocar un número literal immediatamente después de un patrón coincidido), no puede usar la notación familiar \\1 para sus retro-referencias. \\11, por ejemplo, confundiría a preg_replace() ya que no sabe si quiere que la retro-referencia \\1 esté seguida por un literal 1, o que la retro-referencia \\11 esté seguida de nada. En este caso la solución es usar \${1}1. Esto crea una retro-referencia $1 aislada, dejando el 1 como un literal.

Cuando se usa el modificador obsoleto e, esta función escapa algunos caracteres (a saber, ', ", \ y NULL) en la cadena que sustituye a las retro-referencias. Esto está hecho para asegurarse de que no surjan errores de sintaxis en el uso de retro-referencias con comillas simples o dobles (p.ej. 'strlen(\'$1\')+strlen("$2")'). Asegúrese de que conoce la sintaxis de cadena para saber cómo se asemejarán las cadenas interpretadas.

subject

La cadena o array de cadenas a buscar y sustituir.

Si subject es un array, entonces la búsqueda y sustitución se llevan a cabo para cada entrada de subject, y el valor devuleto también es un array.

limit

Las sustituciones máximas posibles por cada patrón en cada cadena subject. Por defecto es -1 (sin límite).

count

Si se especifica, esta variable será rellenada con el número de sustituciones hechas.

Valores devueltos

preg_replace() devuelve un array si el parámetro subject es un array, o, por el contrario, una cadena.

Si se encuentran coincidencias, el nuevo subject será devuelto, de otro modo subject será devuelto sin cambios o NULL si se produjo un error.

Errores/Excepciones

Se emite un error de nivel E_DEPRECATED al pasar el modificador "\e".

Historial de cambios

Versión Descripción
5.5.0 El modificador /e está obsoleto. Utilice preg_replace_callback() en su lugar. Véase la documentación de PREG_REPLACE_EVAL para obtener información adicional sobre riesgos de seguridad.
5.1.0 Añadido el parámetro count

Ejemplos

Ejemplo #1 Usar retro-referencias seguidas de literales numéricos

<?php
$cadena = 'Abril 15, 2003';
$patrón = '/(\w+) (\d+), (\d+)/i';
$sustitución = '${1}1,$3';
echo preg_replace($patrón, $sustitución, $cadena);
?>

El resultado del ejemplo sería:

Abril1,2003

Ejemplo #2 Emplear arrays indexados con preg_replace()

<?php
$cadena = 'El veloz murciélago hindú comía feliz cardillo y kiwi.';
$patrones = array();
$patrones[0] = '/veloz/';
$patrones[1] = '/hindú/';
$patrones[2] = '/murciélago/';
$sustituciones = array();
$sustituciones[2] = 'galápago';
$sustituciones[1] = 'africano';
$sustituciones[0] = 'lento';
echo preg_replace($patrones, $sustituciones, $cadena);
?>

El resultado del ejemplo sería:

El galápago lento africano comía feliz cardillo y kiwi.

Al usar ksort en patrones y sustituciones, podríamos obtener lo que buscábamos.

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

El resultado del ejemplo sería:

El lento galápago africano comía feliz cardillo y kiwi.

Ejemplo #3 Sustituir varios valores

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

El resultado del ejemplo sería:

$fechaInicio = 27/5/1999

Ejemplo #4 Quitar los espacios en blanco

Este ejemplo quita los espacios en blanco en exceso de una cadena.

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

Ejemplo #5 Usar el parámetro count

<?php
$cuenta = 0;

echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $cuenta);
echo $cuenta; //3
?>

El resultado del ejemplo sería:

xp***to
3

Notas

Nota:

Cuando se usan arrays con pattern y replacement, las claves se procesan en el orden en que aparecen en el array. Éste no es necesariamente el mismo que el orden de índice numérico. Si usa índices para identificar qué pattern debería ser sustituido por cuál replacement, debería usar ksort() en cada array antes de llamar a preg_replace().

Ver también