(PHP 4, PHP 5, PHP 7)
preg_replace — Realiza una búsqueda y sustitución de una expresión regular
$pattern
, mixed $replacement
, mixed $subject
[, int $limit = -1
[, int &$count
]] ) : mixed
Busca en subject coincidencias de
pattern y las reemplaza con
replacement.
patternEl 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.
subjectLa 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).
countSi se especifica, esta variable será rellenada con el número de sustituciones hechas.
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.
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.
| 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
|
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', -1 , $cuenta);
echo $cuenta; //3
?>
El resultado del ejemplo sería:
xp***to 3
Nota:
Cuando se usan arrays con
patternyreplacement, 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épatterndebería ser sustituido por cuálreplacement, debería usar ksort() en cada array antes de llamar a preg_replace().