Regular Expressions (PHP Cookbook)

13.1. Introduction

Regular expressions are a powerful tool for matching and manipulating text. While not as fast as plain-vanilla string matching, regular expressions are extremely flexible; they allow you to construct patterns to match almost any conceivable combination of characters with a simple, albeit terse and somewhat opaque syntax.

In PHP, you can use regular expression functions to find text that matches certain criteria. Once located, you can choose to modify or replace all or part of the matching substrings. For example, this regular expression turns text email addresses into mailto: hyperlinks:

$html = preg_replace('/[^@\s]+@([-a-z0-9]+\.)+[a-z]{2,}/i',
                     '<a href="mailto:$0">$0</a>', $text);

As you can see, regular expressions are handy when transforming plain text into HTML and vice versa. Luckily, since these are such popular subjects, PHP has many built-in functions to handle these tasks. Recipe 9.9 tells how to escape HTML entities, Recipe 11.12 covers stripping HTML tags, and Recipe 11.10 and Recipe 11.11 show how to convert ASCII to HTML and HTML to ASCII, respectively. For more on matching and validating email addresses, see Recipe 13.7.

Over the years, the functionality of regular expressions has grown from its basic roots to incorporate increasingly useful features. As a result, PHP offers two different sets of regular-expression functions. The first set includes the traditional (or POSIX) functions, all beginning with ereg (for extended regular expressions; the ereg functions themselves are already an extension of the original feature set). The other set includes the Perl family of functions, prefaced with preg (for Perl-compatible regular expressions).

The preg functions use a library that mimics the regular expression functionality of the Perl programming language. This is a good thing because Perl allows you to do a variety of handy things with regular expressions, including nongreedy matching, forward and backward assertions, and even recursive patterns.

In general, there's no longer any reason to use the ereg functions. They offer fewer features, and they're slower than preg functions. However, the ereg functions existed in PHP for many years prior to the introduction of the preg functions, so many programmers still use them because of legacy code or out of habit. Thankfully, the prototypes for the two sets of functions are identical, so it's easy to switch back and forth from one to another in your mind without too much confusion. (We list how to do this while avoiding the major gotchas in Recipe 13.2.)

The basics of regular expressions are simple to understand. You combine a sequence of characters to form a pattern. You then compare strings of text to this pattern and look for matches. In the pattern, most characters represent themselves. So, to find if a string of HTML contains an image tag, do this:

if (preg_match('/<img /', $html)) {
    // found an opening image tag
}

The preg_match( ) function compares the pattern of "<img " against the contents of $html. If it finds a match, it returns 1; if it doesn't, it returns 0. The / characters are called pattern delimiters ; they set off the start and end of the pattern.

A few characters, however, are special. The special nature of these characters are what transforms regular expressions beyond the feature set of strstr( ) and strpos( ). These characters are called metacharacters. The most frequently used metacharacters include the period (.), asterisk (*), plus (+), and question mark (?). To match an actual metacharacter, precede the character with a backslash(\).

The period matches any character, so the pattern /.at/ matches bat, cat, and even rat.
The asterisk means match 0 or more of the preceding object. (Right now, the only objects we know about are characters.)
The plus is similar to asterisk, but it matches 1 or more instead of or more. So, /.+at/ matches brat, sprat, and even catastrophe, but not at. To match at, replace the + with a *.
The question mark matches 0 or 1 objects.

To apply * and + to objects greater than one character, place the sequence of characters inside parentheses. Parentheses allow you to group characters for more complicated matching and also capture the part of the pattern that falls inside them. A captured sequence can be referenced in preg_replace( ) to alter a string, and all captured matches can be stored in an array that's passed as a third parameter to preg_match( ) and preg_match_all( ). The preg_match_all( ) function is similar to preg_match( ), but it finds all possible matches inside a string, instead of stopping at the first match. Here are some examples:

if (preg_match('/<title>.+<\/title>/', $html)) {
    // page has a title
}

if (preg_match_all('/<li>/', $html, $matches)) {
    print 'Page has ' . count($matches[0]) . " list items\n";
}

// turn bold into italic
$italics = preg_replace('/(<\/?)b(>)/', '$1i$2', $bold);

If you want to match strings with a specific set of letters, create a character class with the letters you want. A character class is a sequence of characters placed inside square brackets. The caret (^) and the dollar sign ($) anchor the pattern at the beginning and the end of the string, respectively. Without them, a match can occur anywhere in the string. So, to match only vowels, make a character class containing a, e, i, o, and u; start your pattern with ^; and end it with $:

preg_match('/^[aeiou]+$/', $string); // only vowels

If it's easier to define what you're looking for by its complement, use that. To make a character class match the complement of what's inside it, begin the class with a caret. A caret outside a character class anchors a pattern at the beginning of a string; a caret inside a character class means "match everything except what's listed in the square brackets":

preg_match('/^[^aeiou]+$/', $string) // only non-vowels

Note that the opposite of [aeiou] isn't [bcdfghjklmnpqrstvwxyz]. The character class [^aeiou] also matches uppercase vowels such as AEIOU, numbers such as 123, URLs such as http://www.cnpq.br/, and even emoticons such as :).

The vertical bar (|), also known as the pipe, specifies alternatives. For example:

// find a gif or a jpeg
preg_match('/(gif|jpeg)/', $images);

Beside metacharacters, there are also metasymbols. Metasymbols are like metacharacters, but are longer than one character in length. Some useful metasymbols are \w (match any word character, [a-zA-Z0-9_]); \d (match any digit, [0-9]); \s (match any whitespace character), and \b (match a word boundary). Here's how to find all numbers that aren't part of another word:

// find digits not touching other words
preg_match_all('/\b\d+\b/', $html, $matches);

This matches 123, 76!, and 38-years-old, but not 2nd.

Here's a pattern that is the regular expression equivalent of trim( ) :

// delete leading whitespace or trailing whitespace
$trimmed = preg_replace('/(^\s+)|(\s+$)/', '', $string);

Finally, there are pattern modifiers. Modifiers effect the entire pattern, not just a character or group of characters. Pattern modifiers are placed after the trailing pattern delimiter. For example, the letter i makes a regular expression pattern case-insensitive:

// strict match lower-case image tags only (XHTML compliant)
if (preg_match('/<img[^>]+>/', $html)) {
   ...
}

// match both upper and lower-case image tags
if (preg_match('/<img[^>]+>/i', $html)) {
   ...
}

We've covered just a small subset of the world of regular expressions. We provide some additional details in later recipes, but the PHP web site also has some very useful information on POSIX regular expressions at http://www.php.net/regex and on Perl-compatible regular expressions at http://www.php.net/pcre. The links from this last page to "Pattern Modifiers" and "Pattern Syntax" are especially detailed and informative.

The best books on this topic are Mastering Regular Expressions by Jeffrey Friedl, and Programming Perl by Larry Wall, Tom Christiansen, and Jon Orwant, both published by O'Reilly. (Since the Perl-compatible regular expressions are based on Perl's regular expressions, we don't feel too bad suggesting a book on Perl.)

Chapter 13. Regular Expressions

Contents:

13.1. Introduction


12.12. Reading RSS Feeds		13.2. Switching From ereg to preg