This section introduces PHP’s exception-handling feature. Specifically, we’ll touch upon the base exception class internals, and demonstrate how to extend this base class, define multiple catch blocks, and introduce other advanced handling tasks. Let’s begin with the basics: the base exception class.
PHP’s Base Exception Class
PHP’s base exception class is actually quite simple in nature, offering a default constructor consisting of no parameters, an overloaded constructor consisting of two optional parameters, and six methods. Each of these parameters and methods is introduced in this section.
The Default Constructor
The default exception constructor is called with no parameters. For example, you can invoke the exception class like so:
throw new Exception();
Once the exception has been instantiated, you can use any of the six methods introduced later in this section. However, only four will be of any use; the other two are useful only if you instantiate the class with the overloaded constructor, introduced next.
The Overloaded Constructor
The overloaded constructor offers additional functionality not available to the default constructor through the acceptance of two optional parameters:
• message: Intended to be a user-friendly explanation that presumably will be passed to the user via the getMessage() method, introduced in the following section.
• error code: Intended to hold an error identifier that presumably will be mapped to some identifier-to-message table. Error codes are often used for reasons of internationalization and localization. This error code is made available via the getCode() method, introduced in the next section. Later, you’ll learn how the base exception class can be extended to compute identifier-to-message table lookups.
You can call this constructor in a variety of ways, each of which is demonstrated here:
throw new Exception("Something bad just happened", 4) throw new Exception("Something bad just happened");
throw new Exception("",4);
Of course, nothing actually happens to the exception until it’s caught, as demonstrated later in this section.
Methods
Six methods are available to the exception class:
• getMessage(): Returns the message if it was passed to the constructor.
• getCode(): Returns the error code if it was passed to the constructor.
• getLine(): Returns the line number for which the exception is thrown.
• getFile(): Returns the name of the file throwing the exception.
• getTrace(): Returns an array consisting of information pertinent to the context in which the error occurred. Specifically, this array includes the file name, line, function, and function parameters.
• getTraceAsString(): Returns all of the same information as is made available by getTrace(), except that this information is returned as a string rather than as an array.
■ Caution Although you can extend the exception base class, you cannot override any of the preceding methods, because they are all declared as final. See Chapter 6 more for information about the final scope.
Listing 8-1 offers a simple example that embodies the use of the overloaded base class constructor, as well as several of the methods.
Listing 8-1. Raising an Exception
try {
$fh = fopen("contacts.txt", "r");
if (! $fh) {
throw new Exception("Could not open the file!");
} }
catch (Exception $e) {
echo "Error (File: ".$e->getFile().", line ".
$e->getLine()."): ".$e->getMessage();
}
If the exception is raised, something like the following would be output:
Error (File: /usr/local/apache2/htdocs/read.php, line 6): Could not open the file!
Extending the Exception Class
Although PHP’s base exception class offers some nifty features, in some situations, you’ll likely want to extend the class to allow for additional capabilities. For example, suppose you want to internationalize your application to allow for the translation of error messages. These messages reside in an array located in a separate text file. The extended exception class will read from this flat file, mapping the error code passed into the constructor to the appropriate message (which presumably has been localized to the appropriate language). A sample flat file follows:
1,Could not connect to the database!
2,Incorrect password. Please try again.
3,Username not found.
4,You do not possess adequate privileges to execute this command.
When MyException is instantiated with a language and error code, it will read in the appro- priate language file, parsing each line into an associative array consisting of the error code and its corresponding message. The MyException class and a usage example are found in Listing 8-2.
Listing 8-2. The MyException Class in Action class MyException extends Exception {
function __construct($language,$errorcode) { $this->language = $language;
$this->errorcode = $errorcode;
}
function getMessageMap() {
$errors = file("errors/".$this->language.".txt");
foreach($errors as $error) {
list($key,$value) = explode(",",$error,2);
$errorArray[$key] = $value;
}
return $errorArray[$this->errorcode];
}
} # end MyException try {
throw new MyException("english",4);
}
catch (MyException $e) { echo $e->getMessageMap();
}
Catching Multiple Exceptions
Good programmers must always ensure that all possible scenarios are taken into account.
Consider a scenario in which your site offers an HTML form from which the user could
subscribe to a newsletter by submitting his or her e-mail address. Several outcomes are possible. For example, the user could do one of the following:
• Provide a valid e-mail address
• Provide an invalid e-mail address
• Neglect to enter any e-mail address at all
• Attempt to mount an attack such as a SQL injection
Proper exception handling will account for all such scenarios. However, in order to do so, you need to provide a means for catching each exception. Thankfully, this is easily possible with PHP. Listing 8-3 shows the code that satisfies this requirement.
Listing 8-3. Catching Multiple Exceptions
<?php
/* The InvalidEmailException class is responsible for notifying the site administrator in the case that the e-mail is deemed invalid. */
class InvalidEmailException extends Exception { function __construct($message, $email) { $this->message = $message;
$this->notifyAdmin($email);
}
private function notifyAdmin($email) {
mail("admin@example.org","INVALID EMAIL",$email,"From:web@example.com");
} }
/* The subscribe class is responsible for validating an e-mail address and adding the user e-mail address to the database. */
class subscribe {
function validateEmail($email) { try {
if ($email == "") {
throw new Exception("You must enter an e-mail address!");
} else {
list($user,$domain) = explode("@", $email);
if (! checkdnsrr($domain, "MX")) {
throw new InvalidEmailException("Invalid e-mail address!", $email);
} else { return 1;
} }
} catch (Exception $e) { echo $e->getMessage();
} catch (InvalidEmailException $e) { echo $e->getMessage();
} }
/* This method would presumably add the user's e-mail address to a database. */
function subscribeUser() {
echo $this->email." added to the database!";
}
} #end subscribe class
/* Assume that the e-mail address came from a subscription form. */
$_POST['email'] = "someuser@example.com";
/* Attempt to validate and add address to database. */
if (isset($_POST['email'])) { $subscribe = new subscribe();
if($subscribe->validateEmail($_POST['email'])) $subscribe->subscribeUser($_POST['email']);
}
?>
You can see that it’s possible for two different exceptions to fire, one derived from the base class and one extended from the base class, InvalidEmailException.
Summary
The topics covered in this chapter touch upon many of the core error-handling practices used in today’s programming industry. While the implementation of such features unfortunately remains more preference than policy, the introduction of capabilities such as logging and error handling has contributed substantially to the ability of programmers to detect and respond to otherwise unforeseen problems in their code.
In the next chapter, we’ll take an in-depth look at PHP’s string-parsing capabilities, covering the language’s powerful regular expression features, and offering insight into many of the powerful string-manipulation functions.
191
■ ■ ■
Strings and
Regular Expressions
As programmers, we build applications that are based on established rules regarding the classification, parsing, storage, and display of information, whether that information consists of gourmet recipes, store sales receipts, poetry, or some other collection of data. In this chapter, we examine many of the PHP functions that you’ll undoubtedly use on a regular basis when performing such tasks.
This chapter covers the following topics:
• PHP 5’s new string offset syntax: In an effort to remove ambiguity and pave the way for potential optimization of run-time string processing, a change to the string offset syntax was made in PHP 5.
• Regular expressions: A brief introduction to regular expressions touches upon the features and syntax of PHP’s two supported regular expression implementations: POSIX and Perl. Following that is a complete introduction to PHP’s respective function libraries.
• String manipulation: It’s conceivable that throughout your programming career, you’ll somehow be required to modify every conceivable aspect of a string. Many of the powerful PHP functions that can help you to do so are introduced in this chapter.
• The PEAR Validate_US package: In this and subsequent chapters, various PEAR packages are introduced that are relevant to the respective chapter’s subject matter. This chapter introduces Validate_US, a PEAR package that is useful for validating the syntax for items of information commonly used in applications of all types, including phone numbers, social security numbers, ZIP codes, and state abbreviations. (If you’re not familiar with PEAR, it’s introduced in Chapter 11.)