PHP Manual
Prev |  | Next

# preg_replace

(PHP 3>= 3.0.9, PHP 4 )

preg_replace -- Perform a regular expression search and replace

## Description

mixed preg_replace ( mixed pattern, mixed replacement, mixed subject [, int limit])

Searches `subject` for matches to `pattern` and replaces them with `replacement`. If `limit` is specified, then only `limit` matches will be replaced; if `limit` is omitted or is -1, then all matches are replaced.

`Replacement` may contain references of the form `\\`n`` or (since PHP 4.0.4) ``$n``, with the latter form being the preferred one. Every such reference will be replaced by the text captured by the `n`'th parenthesized pattern. `n` can be from 0 to 99, and `\\0` or `$0` refers to the text matched by the whole pattern. Opening parentheses are counted from left to right (starting from 1) to obtain the number of the capturing subpattern.

> Note: When working with a replacement pattern where a backreference is immediately followed by another number (i.e.: placing a literal number immediately after a matched pattern), you cannot use the familiar `\\1` notation for your backreference. `\\11`, for example, would confuse preg_replace() since it does not know whether you want the `\\1` backreference followed by a literal `1`, or the `\\11` backreference followed by nothing. In this case the solution is to use `\${1}1`. This creates an isolated `$1` backreference, leaving the `1` as a literal.

Example 1. Using backreferences followed by numeric literals.

    <?php
    $str = "April 15, 2003";
    $pattern = "/(\w+) (\d+), (\d+)/i";
    $replacement = "\${1}1,\$3";
    print preg_replace($pattern, $replacement, $string);

    /* Output
       ======

    April1,2003

     */
    ?>

If matches are found, the new `subject` will be returned, otherwise `subject` will be returned unchanged.

Every parameter to preg_replace() (except `limit`) can be an array.

> Note: When using arrays with `pattern` and `replacement`, the keys are processed in the order they appear in the array. This is not necessarily the same as the numerical index order. If you use indexes to identify which `pattern` should be replaced by which `replacement`, you should perform a ksort() on each array prior to calling preg_replace().

Example 2. Using indexed arrays with preg_replace()

    <?php
    $string = "The quick brown fox jumped over the lazy dog.";

    $patterns[0] = "/quick/";
    $patterns[1] = "/brown/";
    $patterns[2] = "/fox/";

    $replacements[2] = "bear";
    $replacements[1] = "black";
    $replacements[0] = "slow";

    print preg_replace($patterns, $replacements, $string);

    /* Output
       ======

    The bear black slow jumped over the lazy dog.

    */

    /* By ksorting patterns and replacements,
       we should get what we wanted. */

    ksort($patterns);
    ksort($replacements);

    print preg_replace($patterns, $replacements, $string);

    /* Output
       ======

    The slow black bear jumped over the lazy dog.

    */

    ?>

If `subject` is an array, then the search and replace is performed on every entry of `subject`, and the return value is an array as well.

If `pattern` and `replacement` are arrays, then preg_replace() takes a value from each array and uses them to do search and replace on `subject`. If `replacement` has fewer values than `pattern`, then empty string is used for the rest of replacement values. If `pattern` is an array and `replacement` is a string, then this replacement string is used for every value of `pattern`. The converse would not make sense, though.

`/e` modifier makes preg_replace() treat the `replacement` parameter as PHP code after the appropriate references substitution is done. Tip: make sure that `replacement` constitutes a valid PHP code string, otherwise PHP will complain about a parse error at the line containing preg_replace().

Example 3. Replacing several values

    $patterns = array ("/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/",
                       "/^\s*{(\w+)}\s*=/");
    $replace = array ("\\3/\\4/\\1\\2", "$\\1 =");
    print preg_replace ($patterns, $replace, "{startDate} = 1999-5-27");

This example will produce:

    $startDate = 5/27/1999

Example 4. Using /e modifier

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

This would capitalize all HTML tags in the input text.

Example 5. Convert HTML to text

    // $document should contain an HTML document.
    // This will remove HTML tags, javascript sections
    // and white space. It will also convert some
    // common HTML entities to their text equivalent.

    $search = array ("'<script[^>]*?>.*?</script>'si",  // Strip out javascript
                     "'<[\/\!]*?[^<>]*?>'si",           // Strip out html tags
                     "'([\r\n])[\s]+'",                 // Strip out white space
                     "'&(quot|#34);'i",                 // Replace html entities
                     "'&(amp|#38);'i",
                     "'&(lt|#60);'i",
                     "'&(gt|#62);'i",
                     "'&(nbsp|#160);'i",
                     "'&(iexcl|#161);'i",
                     "'&(cent|#162);'i",
                     "'&(pound|#163);'i",
                     "'&(copy|#169);'i",
                     "'&#(\d+);'e");                    // evaluate as php

    $replace = array ("",
                      "",
                      "\\1",
                      "\"",
                      "&",
                      "<",
                      ">",
                      " ",
                      chr(161),
                      chr(162),
                      chr(163),
                      chr(169),
                      "chr(\\1)");

    $text = preg_replace ($search, $replace, $document);

> Note: Parameter `limit` was added after PHP 4.0.1pl2.

See also preg_match(), preg_match_all(), and preg_split().

Prev | Home | Next
preg_replace_callback | Up | preg_split