(PHP 4, PHP 5)
preg_replace — Realiza una búsqueda y sustitución de una expresión regular
$pattern
, mixed $replacement
, mixed $subject
[, int $limit = -1
[, int &$count
]] )
Busca en subject coincidencias de
pattern y las reemplaza con
replacement.
pattern
El patrón de búsqueda. Puede ser tanto una cadena como una matriz de cadenas.
También están disponibles varios modificadores de PCRE, incluyendo 'e' (PREG_REPLACE_EVAL), que es específico de esta función.
replacement
La cadena o matriz de cadenas a reemplazar. Si este parámetro es una
cadena y el parámetro pattern es una matriz,
todos los patrones serán sustituidos por esa cadena. Si ambos parámetros,
pattern y replacement,
son matrices, cada pattern será reemplazado
por el replacement equivalente. Si
hay menos elementos en la matriz replacement
que en la matriz 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 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 matriz de cadenas a buscar y sustituir.
Si subject es una matriz, entonces la búsqueda y
sustitución se llevan a cabo para cada entrada de subject,
y el valor devuleto también es una matriz.
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.
preg_replace() devuelve una matriz si el
parámetro subject es una matriz, 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.
| Versión | Descripción |
|---|---|
| 5.5.0 | El modificador /e está obsoleto. Utilice preg_replace_callback() en su lugar. |
| 5.1.0 |
Añadido el parámetro count
|
| 4.0.4 |
Añadida la forma '$n' para el parámetro replacement
|
| 4.0.2 |
Añadido el parámetro limit
|
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 Usar matrices indexadas 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 matrices con
patternyreplacement, las claves se procesan en el orden en que aparecen en la matriz. É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 matriz antes de llamar a preg_replace().