Variable Interpolation

When you define a string literal using double quotes or a heredoc, the string is subject to variable interpolation. Interpolation is the process of replacing variable names in the string with their contained values. There are two ways to interpolate variables into strings.

The simpler of the two ways is to put the variable name in a double-quoted string or in a heredoc:

$who = 'Kilroy';
$where = 'here';
echo "$who was $where";
Kilroy was here

The other way is to surround the variable being interpolated with curly braces. Using this syntax ensures the correct variable is interpolated. The classic use of curly braces is to disambiguate the variable name from any surrounding text:

$n = 12;
echo "You are the {$n}th person";
You are the 12th person

Without the curly braces, PHP would try to print the value of the $nth variable.

Unlike in some shell environments, in PHP, strings are not repeatedly processed for interpolation. Instead, any interpolations in a double-quoted string are processed first and the result is used as the value of the string:

$bar = 'this is not printed';
$foo = '$bar'; // single quotes
print("$foo");
$bar

Single-Quoted Strings

Single-quoted strings and nowdocs do not interpolate variables. Thus, the variable name in the following string is not expanded because the string literal in which it occurs is single-quoted:

$name = 'Fred';
$str = 'Hello, $name'; // single-quoted
echo $str;
Hello, $name

The only escape sequences that work in single-quoted strings are ', which puts a single quote in a single-quoted string, and \, which puts a backslash in a single-quoted string. Any other occurrence of a backslash is interpreted simply as a backslash:

$name = 'Tim O'Reilly';// escaped single quote
echo $name;
$path = 'C:\WINDOWS'; // escaped backslash
echo $path;
$nope = '
'; // not an escape
echo $nope;
Tim O'Reilly
C:WINDOWS

Double-Quoted Strings

Double-quoted strings interpolate variables and expand the many PHP escape sequences. Table 4-1 lists the escape sequences recognized by PHP in double-quoted strings.

If an unknown escape sequence (i.e., a backslash followed by a character that is not one of those in Table 4-1) is found in a double-quoted string literal, it is ignored (if you have the warning level E_NOTICE set, a warning is generated for such unknown escape sequences):

$str = "What is c this?";// unknown escape sequence
echo $str;
What is c this?

Here Documents

You can easily put multiline strings into your program with a heredoc, as follows:

$clerihew = <<< EndOfQuote
Sir Humphrey Davy
Abominated gravy.
He lived in the odium
Of having discovered sodium.

EndOfQuote;
echo $clerihew;
Sir Humphrey Davy
Abominated gravy.
He lived in the odium
Of having discovered sodium.

The <<< identifier token tells the PHP parser that you’re writing a heredoc. You get to pick the identifier (EndOfQuote in this case), and you can put it in double quotes if you wish (e.g., "EndOfQuote"). The next line starts the text being quoted by the heredoc, which continues until it reaches a line containing only the identifier. To ensure the quoted text is displayed in the output area exactly as you’ve laid it out, turn on plain-text mode by adding this command at the top of your code file:

header('Content-Type: text/plain;');

Alternately, if you have control of your server settings, you could set default_mimetype to plain in the php.ini file:

default_mimetype = "text/plain"

This is not recommended, however, as it puts all output from the server in plain-text mode, which would affect the layout of most of your web code.

If you do not set plain-text mode for your heredoc, the default is typically HTML mode, which simply displays the output all on one line.

When using a heredoc for a simple expression, you can put a semicolon after the terminating identifier to end the statement (as shown in the first example). If you are using a heredoc in a more complex expression, however, you’ll need to continue the expression on the next line, as shown here:

printf(<<< Template
%s is %d years old.
Template
, "Fred", 35);

Single and double quotes in a heredoc are preserved:

$dialogue = <<< NoMore
"It's not going to happen!" she fumed.
He raised an eyebrow. "Want to bet?"
NoMore;
echo $dialogue;
"It's not going to happen!" she fumed.
He raised an eyebrow. "Want to bet?"

As is whitespace:

$ws = <<< Enough
 boo
 hoo
Enough;
// $ws = " boo
 hoo";

New to PHP 7.3 is the indentation of the heredoc terminator. This allows for more legible formatting in the case of embedded code, as in the following function:

function sayIt() {
 $ws = <<< "StufftoSay"
 The quick brown fox 
 Jumps over the lazy dog.
 StufftoSay;
return $ws;
}

echo sayIt() ;

    The quick brown fox 
    Jumps over the lazy dog.

The newline before the trailing terminator is removed, so these two assignments are identical:

$s = 'Foo';
// same as
$s = <<< EndOfPointlessHeredoc
Foo
EndOfPointlessHeredoc;

If you want a newline to end your heredoc-quoted string, you’ll need to add one yourself:

$s = <<< End
Foo

End;

echo

To put a string into the HTML of a PHP-generated page, use echo. While it looks—and for the most part behaves—like a function, echo is a language construct. This means that you can omit the parentheses, so the following expressions are equivalent:

echo "Printy";
echo("Printy"); // also valid

You can specify multiple items to print by separating them with commas:

echo "First", "second", "third";
Firstsecondthird

It is a parse error to use parentheses when trying to echo multiple values:

// this is a parse error
echo("Hello", "world");

Because echo is not a true function, you can’t use it as part of a larger expression:

// parse error
if (echo("test")) {
 echo("It worked!");
}

You can easily remedy such errors by using the print() or printf() functions.

print()

The print() function sends one value (its argument) to the browser:

if (print("test
")) {
 print("It worked!");
}
test
It worked!

printf()

The printf() function outputs a string built by substituting values into a template (the format string). It is derived from the function of the same name in the standard C library. The first argument to printf() is the format string. The remaining arguments are the values to be substituted. A % character in the format string indicates a substitution.

$date = sprintf("%02d/%02d/%04d", $month, $day, $year);
// now we can interpolate $date wherever we need a date

print_r() and var_dump()

The print_r() function intelligently displays what is passed to it, rather than casting everything to a string, as echo and print() do. Strings and numbers are simply printed. Arrays appear as parenthesized lists of keys and values, prefaced by Array:

$a = array('name' => 'Fred', 'age' => 35, 'wife' => 'Wilma');
print_r($a);
Array
(
 [name] => Fred
 [age] => 35
 [wife] => Wilma)

Using print_r() on an array moves the internal iterator to the position of the last element in the array. See Chapter 5 for more on iterators and arrays.

When you print_r() an object, you see the word Object, followed by the initialized properties of the object displayed as an array:

class P {
 var $name = 'nat';
 // ...
}

$p = new P;
print_r($p);
Object
(
 [name] => nat)

Boolean values and NULL are not meaningfully displayed by print_r():

print_r(true); // prints "1";
1
print_r(false); // prints "";

print_r(null); // prints "";

For this reason, var_dump() is preferred over print_r() for debugging. The var_dump() function displays any PHP value in a human-readable format:

var_dump(true);
var_dump(false);
var_dump(null);
var_dump(array('name' => "Fred", 'age' => 35));
class P {
 var $name = 'Nat';
 // ...
}
$p = new P;
var_dump($p);
bool(true)
bool(false)
bool(null)
array(2) {
 ["name"]=>
 string(4) "Fred"
 ["age"]=>
 int(35)
}
object(p)(1) {
 ["name"]=>
 string(3) "Nat"
}

Beware of using print_r() or var_dump() on a recursive structure such as $GLOBALS (which has an entry for GLOBALS that points back to itself). The print_r() function loops infinitely, while var_dump() cuts off after visiting the same element three times.

Removing Whitespace

You can remove leading or trailing whitespace with the trim(), ltrim(), and rtrim() functions:

$trimmed = trim(string [, charlist ]);
$trimmed = ltrim(string [, charlist ]);
$trimmed = rtrim(string [, charlist ]);

trim() returns a copy of string with whitespace removed from the beginning and the end. ltrim() (the l is for left) does the same, but removes whitespace only from the start of the string. rtrim() (the r is for right) removes whitespace only from the end of the string. The optional charlist argument is a string that specifies all the characters to strip. The default characters to strip are given in Table 4-3.

For example:

$title = " Programming PHP 
";
$str1 = ltrim($title); // $str1 is "Programming PHP 
"
$str2 = rtrim($title); // $str2 is " Programming PHP"
$str3 = trim($title); // $str3 is "Programming PHP"

Given a line of tab-separated data, use the charlist argument to remove leading or trailing whitespace without deleting the tabs:

$record = " Fred	Flintstone	35	Wilma	 
";
$record = trim($record, " 
x0B");
// $record is "Fred	Flintstone	35	Wilma"

Changing Case

PHP has several functions for changing the case of strings: strtolower() and strtoupper() operate on entire strings, ucfirst() operates only on the first character of the string, and ucwords() operates on the first character of each word in the string. Each function takes a string to operate on as an argument and returns a copy of that string, appropriately changed. For example:

$string1 = "FRED flintstone";
$string2 = "barney rubble";
print(strtolower($string1));
print(strtoupper($string1));
print(ucfirst($string2));
print(ucwords($string2));
fred flintstone
FRED FLINTSTONE
Barney rubble
Barney Rubble

If you’ve got a mixed-case string that you want to convert to “title case,” where the first letter of each word is in uppercase and the rest of the letters are in lowercase (and you’re not sure what case the string is in to begin with), use a combination of strtolower() and ucwords():

print(ucwords(strtolower($string1)));
Fred Flintstone

HTML

Special characters in HTML are represented by entities such as & (&) and < (<). There are two PHP functions that turn special characters in a string into their entities: one for removing HTML tags, and one for extracting only meta tags.

$string = htmlentities("Einstürzende Neubauten");
echo $string;
Einstürzende Neubauten

$output = htmlentities(input, flags, encoding);

$input = <<< End
"Stop pulling my hair!" Jane's eyes flashed.<p>
End;

$double = htmlentities($input);
// &quot;Stop pulling my hair!&quot; Jane's eyes flashed.&lt;p&gt;

$both = htmlentities($input, ENT_QUOTES);
// &quot;Stop pulling my hair!&quot; Jane&#039;s eyes flashed.&lt;p&gt;

$neither = htmlentities($input, ENT_NOQUOTES);
// "Stop pulling my hair!" Jane's eyes flashed.&lt;p&gt;

$output = htmlspecialchars(input, [flags, [encoding]]);

$table = get_html_translation_table(HTML_ENTITIES);

$table = get_html_translation_table(HTML_SPECIALCHARS, ENT_NOQUOTES);

$str = htmlentities("Einstürzende Neubauten"); // now it is encoded

$table = get_html_translation_table(HTML_ENTITIES);
$revTrans = array_flip($table);

echo strtr($str, $revTrans); // back to normal
Einstürzende Neubauten

$table = get_html_translation_table(HTML_ENTITIES);
$table[' '] = ' ';
$encoded = strtr($original, $table);

$input = '<p>Howdy, &quot;Cowboy&quot;</p>';
$output = strip_tags($input);
// $output is 'Howdy, &quot;Cowboy&quot;'

$input = 'The <b>bold</b> tags will <i>stay</i><p>';
$output = strip_tags($input, '<b>');
// $output is 'The <b>bold</b> tags will stay'

$metaTags = get_meta_tags('http://www.example.com/');
echo "Web page made by {$metaTags['author']}";
Web page made by John Doe

$array = get_meta_tags(filename [, use_include_path]);

URLs

PHP provides functions to convert to and from URL encoding, which allows you to build and decode URLs. There are actually two types of URL encoding, which differ in how they treat spaces. The first (specified by RFC 3986) treats a space as just another illegal character in a URL and encodes it as %20. The second (implementing the application/x-www-form-urlencoded system) encodes a space as a + and is used in building query strings.

Note that you don’t want to use these functions on a complete URL, such as http://www.example.com/hello, as they will escape the colons and slashes to produce:

http%3A%2F%2Fwww.example.com%2Fhello

Encode only partial URLs (the bit after http://www.example.com/) and add the protocol and domain name later.

$output = rawurlencode(input);

$name = "Programming PHP";
$output = rawurlencode($name);
echo "http://localhost/{$output}";
http://localhost/Programming%20PHP

$encoded = 'Programming%20PHP';
echo rawurldecode($encoded);
Programming PHP

$baseUrl = 'http://www.google.com/q=';
$query = 'PHP sessions -cookies';
$url = $baseUrl . urlencode($query);
echo $url;

http://www.google.com/q=PHP+sessions+-cookies

SQL

Most database systems require that string literals in your SQL queries be escaped. SQL’s encoding scheme is pretty simple—single quotes, double quotes, NUL-bytes, and backslashes need to be preceded by a backslash. The addslashes() function adds these slashes, and the stripslashes() function removes them:

$string = <<< EOF
"It's never going to work," she cried,
as she hit the backslash () key.
EOF;
$string = addslashes($string);
echo $string;
echo stripslashes($string);
"It's never going to work," she cried,
as she hit the backslash (\) key.
"It's never going to work," she cried,
as she hit the backslash () key.

C-String Encoding

The addcslashes() function escapes arbitrary characters by placing backslashes before them. With the exception of the characters in Table 4-4, characters with ASCII values less than 32 or above 126 are encoded with their octal values (e.g., "02"). The addcslashes() and stripcslashes() functions are used with nonstandard database systems that have their own ideas of which characters need to be escaped.

Call addcslashes() with two arguments—the string to encode and the characters to escape:

$escaped = addcslashes(string, charset);

Specify a range of characters to escape with the ".." construct:

echo addcslashes("hello	world
", "x00..x1fz..xff");
hello	world

Beware of specifying '0', 'a', 'b', 'f', 'n', 'r', 't', or 'v' in the character set, as they will be turned into '', 'a', and so on. These escapes are recognized by C and PHP and may cause confusion.

stripcslashes() takes a string and returns a copy with the escapes expanded:

$string = stripcslashes(escaped);

For example:

$string = stripcslashes('hello	world
');
// $string is "hello	world
"

Exact Comparisons

You can compare two strings for equality with the == and === operators. These operators differ in how they deal with nonstring operands. The == operator casts string operands to numbers, so it reports that 3 and "3" are equal. Due to the rules for casting strings to numbers, it would also report that 3 and "3b" are equal, as only the portion of the string up to a non-number character is used in casting. The === operator does not cast, and returns false if the data types of the arguments differ:

$o1 = 3;
$o2 = "3";

if ($o1 == $o2) {
 echo("== returns true<br>");
}
if ($o1 === $o2) {
 echo("=== returns true<br>");
}
== returns true

The comparison operators (<, <=, >, >=) also work on strings:

$him = "Fred";
$her = "Wilma";

if ($him < $her) {
 print "{$him} comes before {$her} in the alphabet.
";
}
Fred comes before Wilma in the alphabet

However, the comparison operators give unexpected results when comparing strings and numbers:

$string = "PHP Rocks";
$number = 5;

if ($string < $number) {
 echo("{$string} < {$number}");
}
PHP Rocks < 5

When one argument to a comparison operator is a number, the other argument is cast to a number. This means that "PHP Rocks" is cast to a number, giving 0 (since the string does not start with a number). Because 0 is less than 5, PHP prints "PHP Rocks < 5".

To explicitly compare two strings as strings, casting numbers to strings if necessary, use the strcmp() function:

$relationship = strcmp(string_1, string_2);

The function returns a number less than 0 if string_1 sorts before string_2, greater than 0 if string_2 sorts before string_1, or 0 if they are the same:

$n = strcmp("PHP Rocks", 5);
echo($n);
1

A variation on strcmp() is strcasecmp(), which converts strings to lowercase before comparing them. Its arguments and return values are the same as those for strcmp():

$n = strcasecmp("Fred", "frED"); // $n is 0

Another variation on string comparison is to compare only the first few characters of the string. The strncmp() and strncasecmp() functions take an additional argument, the initial number of characters to use for the comparisons:

$relationship = strncmp(string_1, string_2, len);
$relationship = strncasecmp(string_1, string_2, len);

The final variation on these functions is natural-order comparison with strnatcmp() and strnatcasecmp(), which take the same arguments as strcmp() and return the same kinds of values. Natural-order comparison identifies numeric portions of the strings being compared and sorts the string parts separately from the numeric parts.

Table 4-5 shows strings in natural order and ASCII order.

Approximate Equality

PHP provides several functions that let you test whether two strings are approximately equal—soundex(), metaphone(), similar_text(), and levenshtein():

$soundexCode = soundex($string);
$metaphoneCode = metaphone($string);
$inCommon = similar_text($string_1, $string_2 [, $percentage ]);
$similarity = levenshtein($string_1, $string_2);
$similarity = levenshtein($string_1, $string_2 [, $cost_ins, $cost_rep, $cost_del ]);

The Soundex and Metaphone algorithms each yield a string that represents roughly how a word is pronounced in English. To see whether two strings are approximately equal with these algorithms, compare their pronunciations. You can compare Soundex values only to Soundex values and Metaphone values only to Metaphone values. The Metaphone algorithm is generally more accurate, as the following example demonstrates:

$known = "Fred";
$query = "Phred";

if (soundex($known) == soundex($query)) {
 print "soundex: {$known} sounds like {$query}<br>";
}
else {
 print "soundex: {$known} doesn't sound like {$query}<br>";
}

if (metaphone($known) == metaphone($query)) {
 print "metaphone: {$known} sounds like {$query}<br>";
}
else {
 print "metaphone: {$known} doesn't sound like {$query}<br>";
}
soundex: Fred doesn't sound like Phred
metaphone: Fred sounds like Phred

The similar_text() function returns the number of characters that its two string arguments have in common. The third argument, if present, is a variable in which to store the commonality as a percentage:

$string1 = "Rasmus Lerdorf";
$string2 = "Razmus Lehrdorf";
$common = similar_text($string1, $string2, $percent);
printf("They have %d chars in common (%.2f%%).", $common, $percent);
They have 13 chars in common (89.66%).

The Levenshtein algorithm calculates the similarity of two strings based on how many characters you must add, substitute, or remove to make them the same. For instance, "cat" and "cot" have a Levenshtein distance of 1, because you need to change only one character (the "a" to an "o") to make them the same:

$similarity = levenshtein("cat", "cot"); // $similarity is 1

This measure of similarity is generally quicker to calculate than that used by the similar_text() function. Optionally, you can pass three values to the levenshtein() function to individually weight insertions, deletions, and replacements—for instance, to compare a word against a contraction.

This example excessively weights insertions when comparing a string against its possible contraction, because contractions should never insert characters:

echo levenshtein('would not', 'wouldn't', 500, 1, 1);

Substrings

If you know where the data that you are interested in lies in a larger string, you can copy it out with the substr() function:

$piece = substr(string, start [, length ]);

The start argument is the position in string at which to begin copying, with 0 meaning the start of the string. The length argument is the number of characters to copy (the default is to copy until the end of the string). For example:

$name = "Fred Flintstone";
$fluff = substr($name, 6, 4); // $fluff is "lint"
$sound = substr($name, 11); // $sound is "tone"

To learn how many times a smaller string occurs within a larger one, use substr_count():

$number = substr_count(big_string, small_string);

For example:

$sketch = <<< EndOfSketch
Well, there's egg and bacon; egg sausage and bacon; egg and spam;
egg bacon and spam; egg bacon sausage and spam; spam bacon sausage
and spam; spam egg spam spam bacon and spam; spam sausage spam spam
bacon spam tomato and spam;
EndOfSketch;
$count = substr_count($sketch, "spam");
print("The word spam occurs {$count} times.");
The word spam occurs 14 times.

The substr_replace() function permits many kinds of string modifications:

$string = substr_replace(original, new, start [, length ]);

The function replaces the part of original indicated by the start (0 means the start of the string) and length values with the string new. If no fourth argument is given, substr_replace() removes the text from start to the end of the string.

For instance:

$greeting = "good morning citizen";
$farewell = substr_replace($greeting, "bye", 5, 7);
// $farewell is "good bye citizen"

Use a length of 0 to insert without deleting:

$farewell = substr_replace($farewell, "kind ", 9, 0);
// $farewell is "good bye kind citizen"

Use a replacement of "" to delete without inserting:

$farewell = substr_replace($farewell, "", 8);
// $farewell is "good bye"

Here’s how you can insert at the beginning of the string:

$farewell = substr_replace($farewell, "now it's time to say ", 0, 0);
// $farewell is "now it's time to say good bye"'

A negative value for start indicates the number of characters from the end of the string from which to start the replacement:

$farewell = substr_replace($farewell, "riddance", −3);
// $farewell is "now it's time to say good riddance"

A negative length indicates the number of characters from the end of the string at which to stop deleting:

$farewell = substr_replace($farewell, "", −8, −5);
// $farewell is "now it's time to say good dance"

Miscellaneous String Functions

The strrev() function takes a string and returns a reversed copy of it:

$string = strrev(string);

For example:

echo strrev("There is no cabal");
labac on si erehT

The str_repeat() function takes a string and a count and returns a new string consisting of the argument string repeated count times:

$repeated = str_repeat(string, count);

For example, to build a crude wavy horizontal rule:

echo str_repeat('_.-.', 40);

The str_pad() function pads one string with another. Optionally, you can say what string to pad with, and whether to pad on the left, right, or both:

$padded = str_pad(to_pad, length [, with [, pad_type ]]);

The default is to pad on the right with spaces:

$string = str_pad('Fred Flintstone', 30);
echo "{$string}:35:Wilma";
Fred Flintstone :35:Wilma

The optional third argument is the string to pad with:

$string = str_pad('Fred Flintstone', 30, '. ');
echo "{$string}35";
Fred Flintstone. . . . . . . .35

The optional fourth argument can be STR_PAD_RIGHT (the default), STR_PAD_LEFT, or STR_PAD_BOTH (to center). For example:

echo '[' . str_pad('Fred Flintstone', 30, ' ', STR_PAD_LEFT) . "]
";
echo '[' . str_pad('Fred Flintstone', 30, ' ', STR_PAD_BOTH) . "]
";
[ Fred Flintstone]
[ Fred Flintstone ]

Decomposing a String

PHP provides several functions to let you break a string into smaller components. In increasing order of complexity, they are explode(), strtok(), and sscanf().

$array = explode(separator, string [, limit]);

$input = 'Fred,25,Wilma';
$fields = explode(',', $input);
// $fields is array('Fred', '25', 'Wilma')
$fields = explode(',', $input, 2);
// $fields is array('Fred', '25,Wilma')

$string = implode(separator, array);

$fields = array('Fred', '25', 'Wilma');
$string = implode(',', $fields); // $string is 'Fred,25,Wilma'

$firstChunk = strtok(string, separator);

$nextChunk = strtok(separator);

$string = "Fred,Flintstone,35,Wilma";
$token = strtok($string, ",");

while ($token !== false) {
 echo("{$token}<br />");
 $token = strtok(",");
}
Fred
Flintstone
35
Wilma

$array = sscanf(string, template);
$count = sscanf(string, template, var1, ... );

$string = "Fred	Flintstone (35)";
$a = sscanf($string, "%s	%s (%d)");
print_r($a);
Array
(
 [0] => Fred
 [1] => Flintstone
 [2] => 35)

$string = "Fred	Flintstone (35)";
$n = sscanf($string, "%s	%s (%d)", $first, $last, $age);
echo "Matched {$n} fields: {$first} {$last} is {$age} years old";
Matched 3 fields: Fred Flintstone is 35 years old

String-Searching Functions

Several functions find a string or character within a larger string. They come in three families: strpos() and strrpos(), which return a position; strstr(), strchr(), and friends, which return the string they find; and strspn() and strcspn(), which return how much of the start of the string matches a mask.

In all cases, if you specify a number as the “string” to search for, PHP treats that number as the ordinal value of the character to search for. Thus, these function calls are identical because 44 is the ASCII value of the comma:

$pos = strpos($large, ","); // find first comma
$pos = strpos($large, 44); // also find first comma

All the string-searching functions return false if they can’t find the substring you specified. If the substring occurs at the beginning of the string, the functions return 0. Because false casts to the number 0, always compare the return value with === when testing for failure:

if ($pos === false) {
 // wasn't found
}
else {
 // was found, $pos is offset into string
}

$position = strpos(large_string, small_string);

$record = "Fred,Flintstone,35,Wilma";
$pos = strrpos($record, ","); // find last comma
echo("The last comma in the record is at position {$pos}");
The last comma in the record is at position 18

$record = "Fred,Flintstone,35,Wilma";
$rest = strstr($record, ","); // $rest is ",Flintstone,35,Wilma"

$length = strspn(string, charset);

function isOctal($str)
{
 return strspn($str, '01234567') == strlen($str);
}

function hasBadChars($str)
{
 return strcspn($str, "
	") != strlen($str);
}

$array = parse_url(url);

$bits = parse_url("http://me:[email protected]/cgi-bin/board?user=fred");
print_r($bits);

Array
(
 [scheme] => http
 [host] => example.com
 [user] => me
 [pass] => secret
 [path] => /cgi-bin/board
 [query] => user=fred)

The Basics

Most characters in a regular expression are literal characters, meaning that they match only themselves. For instance, if you search for the regular expression "/cow/" in the string "Dave was a cowhand", you get a match because "cow" occurs in that string.

Some characters have special meanings in regular expressions. For instance, a caret (^) at the beginning of a regular expression indicates that it must match the beginning of the string (or, more precisely, anchors the regular expression to the beginning of the string):

preg_match("/^cow/", "Dave was a cowhand"); // returns false
preg_match("/^cow/", "cowabunga!"); // returns true

Similarly, a dollar sign ($) at the end of a regular expression means that it must match the end of the string (i.e., anchors the regular expression to the end of the string):

preg_match("/cow$/", "Dave was a cowhand"); // returns false
preg_match("/cow$/", "Don't have a cow"); // returns true

A period (.) in a regular expression matches any single character:

preg_match("/c.t/", "cat"); // returns true
preg_match("/c.t/", "cut"); // returns true
preg_match("/c.t/", "c t"); // returns true
preg_match("/c.t/", "bat"); // returns false
preg_match("/c.t/", "ct"); // returns false

If you want to match one of these special characters (called a metacharacter), you have to escape it with a backslash:

preg_match("/$5.00/", "Your bill is $5.00 exactly"); // returns true
preg_match("/$5.00/", "Your bill is $5.00 exactly"); // returns false

Regular expressions are case-sensitive by default, so the regular expression "/cow/" doesn’t match the string "COW". If you want to perform a case-insensitive match, you specify a flag to indicate that (as you’ll see later in this chapter).

So far, we haven’t done anything we couldn’t have done with the string functions we’ve already seen, like strstr(). The real power of regular expressions comes from their ability to specify abstract patterns that can match many different character sequences. You can specify three basic types of abstract patterns in a regular expression:

• A set of acceptable characters that can appear in the string (e.g., alphabetic characters, numeric characters, specific punctuation characters)

• A set of alternatives for the string (e.g., "com", "edu", "net", or "org")

• A repeating sequence in the string (e.g., at least one but not more than five numeric characters)

These three kinds of patterns can be combined in countless ways to create regular expressions that match such things as valid phone numbers and URLs.

Character Classes

To specify a set of acceptable characters in your pattern, you can either build a character class yourself or use a predefined one. You can build your own character class by enclosing the acceptable characters in square brackets:

preg_match("/c[aeiou]t/", "I cut my hand"); // returns true
preg_match("/c[aeiou]t/", "This crusty cat"); // returns true
preg_match("/c[aeiou]t/", "What cart?"); // returns false
preg_match("/c[aeiou]t/", "14ct gold"); // returns false

The regular expression engine finds a "c", then checks that the next character is one of "a", "e", "i", "o", or "u". If it isn’t a vowel, the match fails and the engine goes back to looking for another "c". If a vowel is found, the engine checks that the next character is a "t". If it is, the engine is at the end of the match and returns true. If the next character isn’t a "t", the engine goes back to looking for another "c".

You can negate a character class with a caret (^) at the start:

preg_match("/c[^aeiou]t/", "I cut my hand"); // returns false
preg_match("/c[^aeiou]t/", "Reboot chthon"); // returns true
preg_match("/c[^aeiou]t/", "14ct gold"); // returns false

In this case, the regular expression engine is looking for a "c" followed by a character that isn’t a vowel, followed by a "t".

You can define a range of characters with a hyphen (-). This simplifies character classes like “all letters” and “all digits”:

preg_match("/[0-9]%/", "we are 25% complete"); // returns true
preg_match("/[0123456789]%/", "we are 25% complete"); // returns true
preg_match("/[a-z]t/", "11th"); // returns false
preg_match("/[a-z]t/", "cat"); // returns true
preg_match("/[a-z]t/", "PIT"); // returns false
preg_match("/[a-zA-Z]!/", "11!"); // returns false
preg_match("/[a-zA-Z]!/", "stop!"); // returns true

When you are specifying a character class, some special characters lose their meaning, while others take on new meanings. In particular, the $ anchor and the period lose their meaning in a character class, while the ^ character is no longer an anchor but negates the character class if it is the first character after the open bracket. For instance, [^]] matches any nonclosing bracket character, while [$.^] matches any dollar sign, period, or caret.

The various regular expression libraries define shortcuts for character classes, including digits, alphabetic characters, and whitespace.

Alternatives

You can use the vertical pipe (|) character to specify alternatives in a regular expression:

preg_match("/cat|dog/", "the cat rubbed my legs"); // returns true
preg_match("/cat|dog/", "the dog rubbed my legs"); // returns true
preg_match("/cat|dog/", "the rabbit rubbed my legs"); // returns false

The precedence of alternation can be a surprise: "/^cat|dog$/" selects from "^cat" and "dog$", meaning that it matches a line that either starts with "cat" or ends with "dog". If you want a line that contains just "cat" or "dog", you need to use the regular expression "/^(cat|dog)$/".

You can combine character classes and alternation to, for example, check for strings that don’t start with a capital letter:

preg_match("/^([a-z]|[0-9])/", "The quick brown fox"); // returns false
preg_match("/^([a-z]|[0-9])/", "jumped over"); // returns true
preg_match("/^([a-z]|[0-9])/", "10 lazy dogs"); // returns true

Repeating Sequences

To specify a repeating pattern, you use a quantifier. The quantifier goes after the pattern that’s repeated and says how many times to repeat that pattern. Table 4-6 shows the quantifiers that are supported by PHP’s regular expressions.

To repeat a single character, simply put the quantifier after the character:

preg_match("/ca+t/", "caaaaaaat"); // returns true
preg_match("/ca+t/", "ct"); // returns false
preg_match("/ca?t/", "caaaaaaat"); // returns false
preg_match("/ca*t/", "ct"); // returns true

With quantifiers and character classes, we can actually do something useful, like matching valid US telephone numbers:

preg_match("/[0-9]{3}-[0-9]{3}-[0-9]{4}/", "303-555-1212"); // returns true
preg_match("/[0-9]{3}-[0-9]{3}-[0-9]{4}/", "64-9-555-1234"); // returns false

Subpatterns

You can use parentheses to group bits of a regular expression together to be treated as a single unit called a subpattern:

preg_match("/a (very )+big dog/", "it was a very very big dog"); // returns true
preg_match("/^(cat|dog)$/", "cat"); // returns true
preg_match("/^(cat|dog)$/", "dog"); // returns true

The parentheses also cause the substring that matches the subpattern to be captured. If you pass an array as the third argument to a match function, the array is populated with any captured substrings:

preg_match("/([0-9]+)/", "You have 42 magic beans", $captured);
// returns true and populates $captured

The zeroth element of the array is set to the entire string being matched against. The first element is the substring that matched the first subpattern (if there is one), the second element is the substring that matched the second subpattern, and so on.

Delimiters

Perl-style regular expressions emulate the Perl syntax for patterns, which means that each pattern must be enclosed in a pair of delimiters. Traditionally, the forward slash (/) character is used; for example, /pattern/. However, any nonalphanumeric character other than the backslash character () can be used to delimit a Perl-style pattern. This is useful for matching strings containing slashes, such as filenames. For example, the following are equivalent:

preg_match("//usr/local//", "/usr/local/bin/perl"); // returns true
preg_match("#/usr/local/#", "/usr/local/bin/perl"); // returns true

Parentheses (()), curly braces ({}), square brackets ([]), and angle brackets (<>) can be used as pattern delimiters:

preg_match("{/usr/local/}", "/usr/local/bin/perl"); // returns true

The section “Trailing Options” discusses the single-character modifiers you can put after the closing delimiter to modify the behavior of the regular expression engine. A very useful one is x, which makes the regular expression engine strip whitespace and #-marked comments from the regular expression before matching. These two patterns are the same, but one is much easier to read:

'/([[:alpha:]]+)s+1/'
'/( # start capture
[[:alpha:]]+ # a word
s+ # whitespace
1 # the same word again
 ) # end capture
/x'

Match Behavior

The period (.) matches any character except for a newline ( ). The dollar sign ($) matches at the end of the string or, if the string ends with a newline, just before that newline:

preg_match("/is (.*)$/", "the key is in my pants", $captured);
// $captured[1] is 'in my pants'

Character Classes

As shown in Table 4-7, Perl-compatible regular expressions define a number of named sets of characters that you can use in character classes. The expansions in Table 4-7 are for English. The actual letters vary from locale to locale.

Each [: something :] class can be used in place of a character in a character class. For instance, to find any character that’s a digit, an uppercase letter, or an “at” sign (@), use the following regular expression:

[@[:digit:][:upper:]]

However, you can’t use a character class as the endpoint of a range:

preg_match("/[A-[:lower:]]/", "string");// invalid regular expression

Some locales consider certain character sequences as if they were a single character—these are called collating sequences. To match one of these multicharacter sequences in a character class, enclose it with [. and .]. For example, if your locale has the collating sequence ch, you can match s, t, or ch with this character class:

[st[.ch.]]

The final extension to character classes is the equivalence class, which you specify by enclosing the character within [= and =]. Equivalence classes match characters that have the same collating order, as defined in the current locale. For example, a locale may define a, á, and ä as having the same sorting precedence. To match any one of them, the equivalence class is [=a=].

Anchors

An anchor limits a match to a particular location in the string (anchors do not match actual characters in the target string). Table 4-8 lists the anchors supported by regular expressions.

A word boundary is defined as the point between a whitespace character and an identifier (alphanumeric or underscore) character:

preg_match("/[[:<:]]gun[[:>:]]/", "the Burgundy exploded"); // returns false
preg_match("/gun/", "the Burgundy exploded"); // returns true

Note that the beginning and end of a string also qualify as word boundaries.

Quantifiers and Greed

Regular expression quantifiers are typically greedy. That is, when faced with a quantifier, the engine matches as much as it can while still satisfying the rest of the pattern. For instance:

preg_match("/(<.*>)/", "do <b>not</b> press the button", $match);
// $match[1] is '<b>not</b>'

The regular expression matches from the first less-than sign to the last greater-than sign. In effect, the .* matches everything after the first less-than sign, and the engine backtracks to make it match less and less until finally there’s a greater-than sign to be matched.

This greediness can be a problem. Sometimes you need minimal (nongreedy) matching—that is, quantifiers that match as few times as possible to satisfy the rest of the pattern. Perl provides a parallel set of quantifiers that match minimally. They’re easy to remember, because they’re the same as the greedy quantifiers, but with a question mark (?) appended. Table 4-9 shows the corresponding greedy and nongreedy quantifiers supported by Perl-style regular expressions.

Here’s how to match a tag using a nongreedy quantifier:

preg_match("/(<.*?>)/", "do <b>not</b> press the button", $match);
// $match[1] is "<b>"

Another, faster way is to use a character class to match every non-greater-than character up to the next greater-than sign:

preg_match("/(<[^>]*>)/", "do <b>not</b> press the button", $match);
// $match[1] is '<b>'

Noncapturing Groups

If you enclose a part of a pattern in parentheses, the text that matches that subpattern is captured and can be accessed later. Sometimes, though, you want to create a subpattern without capturing the matching text. In Perl-compatible regular expressions, you can do this using the (?: subpattern ) construct:

preg_match("/(?:ello)(.*)/", "jello biafra", $match);
// $match[1] is " biafra"

Backreferences

You can refer to text captured earlier in a pattern with a backreference: 1 refers to the contents of the first subpattern, 2 refers to the second, and so on. If you nest subpatterns, the first begins with the first opening parenthesis, the second begins with the second opening parenthesis, and so on.

For instance, this identifies doubled words:

preg_match("/([[:alpha:]]+)s+1/", "Paris in the the spring", $m);
// returns true and $m[1] is "the"

The preg_match() function captures at most 99 subpatterns; subpatterns after the 99th are ignored.

Trailing Options

Perl-style regular expressions let you put single-letter options (flags) after the regular expression pattern to modify the interpretation, or behavior, of the match. For instance, to match case-insensitively, simply use the i flag:

preg_match("/cat/i", "Stop, Catherine!"); // returns true

Table 4-10 shows the modifiers from Perl that are supported in Perl-compatible regular expressions.

PHP’s Perl-compatible regular expression functions also support other modifiers that aren’t supported by Perl, as listed in Table 4-11.

It’s possible to use more than one option in a single pattern, as demonstrated in the following example:

$message = <<< END
To: you@youcorp
From: me@mecorp
Subject: pay up

Pay me or else!
END;

preg_match("/^subject: (.*)/im", $message, $match);

print_r($match);

// output: Array ( [0] => Subject: pay up [1] => pay up )

Inline Options

In addition to specifying pattern-wide options after the closing pattern delimiter, you can specify options within a pattern to have them apply only to part of the pattern. The syntax for this is:

(?flags:subpattern)

For example, only the word “PHP” is case-insensitive in this example:

echo preg_match('/I like (?i:PHP)/', 'I like pHp', $match);
print_r($match) ;
// returns true (echo: 1)
// $match[0] is 'I like pHp'

The i, m, s, U, x, and X options can be applied internally in this fashion. You can use multiple options at once:

preg_match('/eat (?ix:foo d)/', 'eat FoOD'); // returns true

Prefix an option with a hyphen (-) to turn it off:

echo preg_match('/I like (?-i:PHP)/', 'I like pHp', $match);
print_r($matche) ;
// returns false (echo: 0)
// $match[0] is ''

An alternative form enables or disables the flags until the end of the enclosing subpattern or pattern:

preg_match('/I like (?i)PHP/', 'I like pHp'); // returns true
preg_match('/I (like (?i)PHP) a lot/', 'I like pHp a lot', $match);
// $match[1] is 'like pHp'

Inline flags do not enable capturing. You need an additional set of capturing parentheses to do that.

Lookahead and Lookbehind

In patterns it’s sometimes useful to be able to say “match here if this is next.” This is particularly common when you are splitting a string. The regular expression describes the separator, which is not returned. You can use lookahead to make sure (without matching it, thus preventing it from being returned) that there’s more data after the separator. Similarly, lookbehind checks the preceding text.

Lookahead and lookbehind come in two forms: positive and negative. A positive lookahead or lookbehind says “the next/preceding text must be like this.” A negative lookahead or lookbehind indicates “the next/preceding text must not be like this.” Table 4-12 shows the four constructs you can use in Perl-compatible patterns. None of these constructs captures text.

A simple use of positive lookahead is splitting a Unix mbox mail file into individual messages. The word "From" starting a line by itself indicates the start of a new message, so you can split the mailbox into messages by specifying the separator as the point where the next text is "From" at the start of a line:

$messages = preg_split('/(?=^From )/m', $mailbox);

A simple use of negative lookbehind is to extract quoted strings that contain quoted delimiters. For instance, here’s how to extract a single-quoted string (note that the regular expression is commented using the x modifier):

$input = <<< END
name = 'Tim O'Reilly';
END;

$pattern = <<< END
' # opening quote
( # begin capturing
 .*? # the string
 (?<! \\ ) # skip escaped quotes
) # end capturing
' # closing quote
END;
preg_match( "($pattern)x", $input, $match);
echo $match[1];
Tim O'Reilly

The only tricky part is that to get a pattern that looks behind to see if the last character was a backslash, we need to escape the backslash to prevent the regular expression engine from seeing ), which would mean a literal close parenthesis. In other words, we have to backslash that backslash: \). But PHP’s string-quoting rules say that \ produces a literal single backslash, so we end up requiring four backslashes to get one through the regular expression! This is why regular expressions have a reputation for being hard to read.

Perl limits lookbehind to constant-width expressions. That is, the expressions cannot contain quantifiers, and if you use alternation, all the choices must be the same length. The Perl-compatible regular expression engine also forbids quantifiers in lookbehind, but does permit alternatives of different lengths.

Cut

The rarely used once-only subpattern, or cut, prevents worst-case behavior by the regular expression engine on some kinds of patterns. The subpattern is never backed out of once matched.

The common use for the once-only subpattern is when you have a repeated expression that may itself be repeated:

/(a+|b+)*.+/

This code snippet takes several seconds to report failure:

$p = '/(a+|b+)*.+$/';
$s = 'abababababbabbbabbaaaaaabbbbabbababababababbba..!';

if (preg_match($p, $s)) {
 echo "Y";
}
else {
 echo "N";
}

This is because the regular expression engine tries all the different places to start the match, but has to backtrack out of each one, which takes time. If you know that once something is matched it should never be backed out of, you should mark it with (?> subpattern ):

$p = '/(?>a+|b+)*.+$/';

The cut never changes the outcome of the match; it simply makes it fail faster.

Conditional Expressions

A conditional expression is like an if statement in a regular expression. The general form is:

(?(condition)yespattern)
(?(condition)yespattern|nopattern)

If the assertion succeeds, the regular expression engine matches the yespattern. With the second form, if the assertion doesn’t succeed, the regular expression engine skips the yespattern and tries to match the nopattern.

The assertion can be one of two types: either a backreference, or a lookahead or lookbehind match. To reference a previously matched substring, the assertion is a number from 1 to 99 (the most backreferences available). The condition uses the pattern in the assertion only if the backreference was matched. If the assertion is not a backreference, it must be a positive or negative lookahead or lookbehind assertion.

Functions

There are five classes of functions that work with Perl-compatible regular expressions: matching, replacing, splitting, filtering, and a utility function for quoting text.

$found = preg_match(pattern, string [, captured ]);

preg_match('/y.*e$/', 'Sylvie'); // returns true
preg_match('/y(.*)e$/', 'Sylvie', $m); // $m is array('ylvie', 'lvi')

preg_match('y.*e$/i', 'SyLvIe'); // returns true

$found = preg_match_all(pattern, string, matches [, order ]);

$string = <<< END
13 dogs
12 rabbits
8 cows
1 goat
END;
preg_match_all('/(d+) (S+)/', $string, $m1, PREG_PATTERN_ORDER);
preg_match_all('/(d+) (S+)/', $string, $m2, PREG_SET_ORDER);

<?php
if (getenv('REQUEST_METHOD') == 'POST') {
 $url = $_POST['url'];
}
else {
 $url = $_GET['url'];
}
?>

<form action="<?php echo $_SERVER['PHP_SELF']; ?>" method="POST">
 <p>URL: <input type="text" name="url" value="<?php echo $url ?>" /><br />
 <input type="submit">
</form>

<?php
if ($url) {
 $remote = fopen($url, 'r'); {
 $html = fread($remote, 1048576); // read up to 1 MB of HTML
 }
 fclose($remote);

 $urls = '(http|telnet|gopher|file|wais|ftp)';
 $ltrs = 'w';
 $gunk = '/#~:.?+=&%@!-';
 $punc = '.:?-';
 $any = "{$ltrs}{$gunk}{$punc}";

 preg_match_all("{
  # start at word boundary
 {$urls}: # need resource and a colon
 [{$any}] +? # followed by one or more of any valid
 # characters—but be conservative
 # and take only what you need
 (?= # the match ends at
 [{$punc}]* # punctuation
 [^{$any}] # followed by a non-URL character
 | # or
 $ # the end of the string
 )
 }x", $html, $matches);

 printf("I found %d URLs<P>
", sizeof($matches[0]));

 foreach ($matches[0] as $u) {
 $link = $_SERVER['PHP_SELF'] . '?url=' . urlencode($u);
 echo "<a href="{$link}">{$u}</a><br />
";
 }
}

$new = preg_replace(pattern, replacement, subject [, limit ]);

$better = preg_replace('/<.*?>/', '!', 'do <b>not</b> press the button');
// $better is 'do !not! press the button'

$names = array('Fred Flintstone',
 'Barney Rubble',
 'Wilma Flintstone',
 'Betty Rubble');
$tidy = preg_replace('/(w)w* (w+)/', '1 2', $names);
// $tidy is array ('F Flintstone', 'B Rubble', 'W Flintstone', 'B Rubble')

$contractions = array("/don't/i", "/won't/i", "/can't/i");
$expansions = array('do not', 'will not', 'can not');
$string = "Please don't yell—I can't jump while you won't speak";
$longer = preg_replace($contractions, $expansions, $string);
// $longer is 'Please do not yell—I can not jump while you will not speak';

$htmlGunk = array('/<.*?>/', '/&.*?;/');
$html = '&eacute; : <b>very</b> cute';
$stripped = preg_replace($htmlGunk, array(), $html);
// $stripped is ' : very cute'

$stripped = preg_replace($htmlGunk, '', $html);

echo preg_replace('/(w)w+s+(w+)/', '$2, $1.', 'Fred Flintstone')
Flintstone, F.

$string = 'It was 5C outside, 20C inside';
echo preg_replace('/(d+)C/e', '$1*9/5+32', $string);
It was 41 outside, 68 inside

$name = 'Fred';
$age = 35;
$string = '$name is $age';
preg_replace('/$(w+)/e', '$$1', $string);

function titlecase($s)
{
 return ucfirst(strtolower($s[0]));
}

$string = 'goodbye cruel world';
$new = preg_replace_callback('/w+/', 'titlecase', $string);
echo $new;

Goodbye Cruel World

$chunks = preg_split(pattern, string [, limit [, flags ]]);

$ops = preg_split('{[+*/−]}', '3+5*9/2');
// $ops is array('3', '5', '9', '2')

$ops = preg_split('{([+*/−])}', '3+5*9/2', −1, PREG_SPLIT_DELIM_CAPTURE);
// $ops is array('3', '+', '5', '*', '9', '/', '2')

$array = preg_split('//', $string);

$matching = preg_grep(pattern, array);

$textfiles = preg_grep('/.txt$/', $filenames);

$re = preg_quote(string [, delimiter ]);

echo preg_quote('$5.00 (five bucks)');
$5.00 (five bucks)

$toFind = '/usr/local/etc/rsync.conf';
$re = preg_quote($toFind, '/');

if (preg_match("/{$re}/", $filename)) {
 // found it!
}

Differences from Perl Regular Expressions

Although very similar, PHP’s implementation of Perl-style regular expressions has a few minor differences from actual Perl regular expressions:

• The NULL character (ASCII 0) is not allowed as a literal character within a pattern string. You can reference it in other ways, however (00, x00, etc.).

• The E, G, L, l, Q, u, and U options are not supported.

• The (?{ some perl code }) construct is not supported.

• The /D, /G, /U, /u, /A, and /X modifiers are supported.

• The vertical tab v counts as a whitespace character.

• Lookahead and lookbehind assertions cannot be repeated using *, +, or ?.

• Parenthesized submatches within negative assertions are not remembered.

• Alternation branches within a lookbehind assertion can be of different lengths.