preg_replace

(PHP 4, PHP 5, PHP 7)

preg_replaceRealiza una búsqueda y sustitución de una expresión regular

Descripción

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

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 hay disponibles varios modificadores de PCRE.

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 $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 retroreferencia 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 retroreferencias. \\11, por ejemplo, confundiría a preg_replace() ya que no sabe si quiere que la retroreferencia \\1 esté seguida por un literal 1, o que la retroreferencia \\11 esté seguida de nada. En este caso la solución es usar ${1}1. Esto crea una retroreferencia $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 retroreferencias. Esto está hecho para asegurarse de que no surjan errores de sintaxis en el uso de retroreferencias 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 devuelto 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, de lo contrario, una cadena.

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

Errores/Excepciones

A partir de PHP 5.5.0 se emite un error de nivel E_DEPRECATED al pasar el modificador "\e". A partir de PHP 7.0.0, en este caso se emite un E_WARNING y el modificador "\e" no tiene efecto.

Historial de cambios

Versión Descripción
7.0.0 Se ha eliminado el soporte para el modificador /e. Emplee preg_replace_callback() en su lugar.
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 retroreferencias 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', -$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