I have chosen this particular set of coding conventions because it comes from the source. Zend is the company founded by the creators of the core PHP scripting engine, Zeev Suraski and Andi Gutmans, who remain key contributors to PHP. The standard was developed for the Zend Framework, a vast library of advanced PHP classes that you should explore after finishing this book. The emphasis throughout is on making your code easy to read and understand. The full details are at http://framework.zend.com/manual/en/coding-standard.html, so I'll go through only the main points.

Even if you don't follow the Zend Framework guidelines to the letter, it's a good policy to use verbose, descriptive names for methods and properties. Descriptive names act as a reminder of the role played by a particular property or method and help make much of your code self-documenting. There can be little doubt, for example, what the checkTextLength() method in the Pos_Validator class does. Yes, it means more typing, but this isn't a problem if you use a dedicated PHP IDE, such as Zend Studio for Eclipse or PhpED, that automatically generates code hints. Since PHP code remains on the server, there's no advantage in obfuscating code to prevent others from stealing your brilliant ideas. The only people likely to be confused are yourself when, in six months' time, you come to review your code or your colleagues if you're working in a team.

A class normally contains both properties and methods. There are no rules about the order in which they should appear inside the class, but the normal convention is to declare all the properties first, followed by the methods. Throughout this chapter, I'm going to use examples based on an imaginary e-commerce application that sells a small range of products. So, this is how you define a class called Product:

class Product
{
  // properties defined here
  // methods defined here
}

That's actually a valid class. It doesn't do anything because it contains only comments, but it's perfectly valid.

There are no rules about where you should define classes, but it's considered best practice to define each class in a file of its own, as it makes it easier to redeploy classes in different projects. Unlike some languages, such as ActionScript, there's no restriction on what you call the file, but it makes life easier if you use the same name as the class. So, the Product class would be defined in Product.php. Since Product is likely to be a common class name, it's recommended to give it a three- or four-character prefix to avoid name clashes. I'm following the Zend Framework PHP Coding Standard, so I'll give it a name that maps to the Ch2 directory where all the examples for this chapter are stored: Ch2_Product. Figure 2-1 shows the structure of my site and the basic skeleton for the class in Zend Studio.

Figure 2.1. To prevent clashes, it's common practice to prefix a class name with the name of the directory it is stored in.

The class is no use without any properties or methods. These are the same as variables and functions, but before adding them, you need to understand visibility modifiers.

As I explained in Chapter 1, encapsulation is a key concept in OOP, so you need to control the visibility of a class's properties and methods. Visibility determines whether a property or method can be accessed directly by any part of a script that uses a class, or whether it remains internal to the class. This is the principle of the black box. To maintain the reliability of a finely tuned car engine, a mechanic doesn't want any Tom, Dick, or Harriet to tinker with the timing of the plugs. Equally, if a class is to produce reliable results, certain parts of its inner workings need to be hidden from sight. You do this by preceding the property or method definition with one of the following keywords: public, protected, or private. Table 2-1 explains the meaning of each keyword.

Although you can omit the visibility modifier for a method, in which case it will default to public, it's not considered good practice.

Properties must always be preceded by a visibility modifier. It's a common convention (and one followed by this book) to use an underscore as the first character of protected or private properties. This serves as a reminder to the developer that access is restricted.

So, which should you choose? At the risk of oversimplification, methods often serve as the interface to a class's functionality, so they need to be public. Properties, on the other hand, should almost always be hidden away as protected or private to prevent them from being changed accidentally. When you need to expose or change the value of a property, the normal way to do so is through a getter or setter method.

However, there are no hard and fast rules. It's often useful to create methods that solely perform a task inside the class. For example, in Chapter 4 you'll build a class to validate user input. You don't want anyone to be able to change the source of the input arbitrarily, so the method that retrieves the values from the $_POST or $_GET array needs to be hidden away inside the class as either protected or private.

If this sounds confusing, all should become clear through the following exercise.

The code for all the exercises in this chapter is in the Ch2 and ch2_exercises folders of the download files. Each file has a basic name, such as Product.php or product_test.php. To show the code at different stages of development, the download files are numbered in sequence (e.g., Product_01.php, Product_02.php, and so on). When doing the exercises yourself, I suggest that you use the basic name for each file, just updating the code in each step. If you need to check your code—or simply want to test the download versions—refer to the numbered versions listed at the appropriate point of each exercise.

Experimenting with visibility

This exercise shows what happens when you attempt to access a protected property outside the class definition and demonstrates how to create getter and setter methods.

As you can see, protecting properties comes at the expense of longer code. Newcomers to OOP (and some old hands, too) often find this tedious, but the ability to restrict access to properties and methods gives you much greater control over the integrity of your data.

At this stage, you're probably wondering, "What's the point? Why go to all the bother of protecting a property if it can be changed with a setter method?" In the preceding exercise, there is very little point, indeed, apart from demonstrating the basic syntax. However, once you start working with real classes, you'll see that most protected and private properties don't have getter and setter methods. They remain encapsulated within the class.

Some properties have only getter methods. This allows an external script to access the property's value, but the lack of a setter method means you cannot change it. For example, the class in Chapter 4 validates and filters user input and stores it in a property called $_filtered. By declaring $_filtered protected and creating only a getter method, the class gives access to the filtered values but prevents anyone from tampering with them. Setter methods tend to be used mainly for initializing the value of a property. Once the value has been set, the protected or private status of the property prevents the value from being changed accidentally.

In the preceding exercise, you gave the $_type property a default value. Although that's sometimes what you want, you gain more flexibility by specifying properties at the time of instantiating the object. You do this in exactly the same way as passing an argument to a function. When you create an instance of a class, PHP automatically looks for the class's constructor method (or constructor). As the name suggests, a constructor builds the object, applying default values and assigning to properties values passed to the class when an object is instantiated.

In many languages, the constructor is a method that shares the same name as the class. This is how PHP objects were built in PHP 3 and 4. However, since PHP 5, the constructor for all classes is called __construct() (with two leading underscores). As you saw from the previous exercise, using a constructor is optional, but most classes do use one.

The constructor works like a setter method, so any values passed to it as arguments can be assigned to properties by using $this to refer to the current object like this:

public function __construct($value)
{
   $this->_property = $value;
}

Let's update the Ch2_Product class to use a constructor.

Passing Values to a constructor

This exercise builds on the previous one by adding a constructor that takes two arguments: one to set the product type and the other to set its title. Continue working with the same files as before.

Admittedly, this isn't the most exciting result in the world, but the purpose at this stage is to understand basic PHP OOP syntax without introducing any distractions.

The code in the final step of the exercise created two independent objects: one a Book, the other a DVD. On the face of it, this might not seem any different from creating two associative arrays like this:

$product1 = array('type'  => 'Book',
                  'title' => 'PHP Object-Oriented Solutions'),
$product2 = array('type'  => 'DVD',
                  'title' => 'Atonement'),

However, the differences are enormous, namely:

The previous exercise used the constructor to assign values passed in from outside to the object's properties, but you can use the constructor to do any initial setup for all objects of the same class. So, for example, if all products are made by the same manufacturer, you could use the constructor to assign the default value to a protected property called $_manufacturer. If you want all objects to share the same value, there's no need to pass it to the constructor as an argument.

Using a constructor has made the Ch2_Product class more flexible, but it also introduces a problem. Although you can create objects to represent different types of products, books and DVDs have different features. Books have pages, but DVDs don't. DVDs have a duration or playing time, but books don't. You could get around this by creating a property called $_length and using conditional statements to determine whether this refers to the number of pages or the playing time, depending on the type of product. You could, but it's messy. A much better solution is to use inheritance and create specialized subclasses.

To define a child class, simply use the extends keyword together with the name of the parent class like this:

class ChildClassName extends ParentClassName
{
  // class definition goes here
}

The child class needs access to the file where the parent class is defined, so you need to include the parent file before defining the child class. Since the child class depends on it, you should normally use require_once to include the parent file.

So let's create two child classes that inherit from Ch2_Product.

Creating the Book and DVD child classes

This exercise creates two child classes from Ch2_Product and shows what happens when you add a new property to a child class. Continue working with Product.php and product_test.php from the preceding exercise. You can see the finished code in Book_02.php and DVD_01.php in the Ch2 folder and product_test_07.php in ch2_exercises.

Figure 2.5. The title is missing from the output.

The script doesn't generate any warnings, so there are no syntax errors. The getTitle() method of the parent class has been inherited by the child class, so it's legitimate to use it. However, it has produced no output. I expect that most readers will already be yelling, "Of course it hasn't, because you haven't assigned the value of $title to the object's $_title property."

That's true, but I also said that a child class inherits all its parent's properties and methods. So you would also be justified in wondering why it didn't use the Ch2_Product constructor. After all, it did so when you tested the child classes in step 4. The answer is that this is polymorphism in action: a child class inherits its parent's methods and properties, but you can also redefine (or override) them. You're no longer creating a Ch2_Product object, but a Ch2_Book object.

By defining a constructor in the child class, you have overridden the parent constructor. The child class does only what its own constructor tells it to do. It accepts three arguments but does nothing with the first two ($type and $title). To assign the value of these arguments to the $_type and $_title properties, you either need to do so explicitly in the child class's constructor or find some way of invoking the parent constructor.

First, let's take a look at this second option.

The ability to override a parent class's methods or properties is very convenient, but there are times when you want to access them in a child class. To do this, you need to use the scope resolution operator.

ClassName::methodOrPropertyName

Ch2_Product::__construct($type, $title);

parent::__construct($type, $title);

class ParentClass
{
  protected $_a;
  protected $_b;

  public function __construct($a, $b)

{
    $this->_a = $a;
    $this->_b = $b;
  }
}

class ChildClass extends ParentClass
{
  protected $_c;

  public function __construct($a, $b, $c)
  {
    parent::__construct($a, $b);
    $this->_c = $c;
  }
}

You can prevent a whole class from being overridden or apply restrictions to individual methods and properties. The way you handle individual properties is different, so I'll describe that after dealing with whole classes and individual methods.

final Ch2_Book extends Ch2_Product
{
  // class definition omitted
}

class Ch2_Book extends Ch2_Product
{
  protected $_pageCount;

  public function __construct($title, $pageCount)
  {
    $this->_title = $title;
    $this->_pageCount = $pageCount;
    $this->_type = 'book';
  }

  final public function getPageCount()
  {
    return $this->_pageCount;
  }
}

define('MILES_TO_KILOMETERS', 1.609344);

class Ch2_Product
{
  // properties defined here
  protected $_type;
  protected $_title;
  const POUNDS_TO_KILOGRAMS = 0.45359237;

  // rest of class omitted
}

self::POUNDS_TO_KILOGRAMS

Ch2_Product::POUNDS_TO_KILOGRAMS

class classA
{
  const FIXED_NUMBER = 4;
}

class classB extends classA
{
  const FIXED_NUMBER = 20;
}

echo classA::FIXED_NUMBER . '<br />';
echo classB::FIXED_NUMBER;

protected static $_lbToKg = 0.45359237;

self::$_lbToKg

public static $lbToKg = 0.45359237;
static $lbToKg = 0.45359237;

Ch2_Product::$lbToKg

class classC
{
  protected static $_counter = 0;
  public $num;

  public function __construct()
  {
    self::$_counter++;
    $this->num = self::$_counter;
  }
}

$object1 = new classC();
echo $object1->num . '<br />';
$object2 = new classC();
echo $object2->num;

public static function convertLbToKg($pounds)
{
  return $pounds * 0.4535923;
}

$weight = self::convertLbToKg(5); // $weight is 2.2679615

$weight = Ch2_Product::convertLbToKg(5); // $weight is 2.2679615

If you worked through the exercises from the beginning of this chapter, you might be wondering if the Ch2_Product class is really necessary. As a result of inheritance, you have specialized classes for books and DVDs. If further products are added to the range, you can create new child classes and would probably never create a Ch2_Product object on its own. In fact, to maintain control, it's a good idea to prevent generic products from being created. However, without the parent class, it would be necessary to declare the common properties and methods in each child class. By making the parent class abstract, you get all the benefits of inheritance but prevent the parent class from being instantiated.

To make a class abstract, add the keyword abstract in front of class and the class name in the class definition. So, the revised Ch2_Product class looks like this (the code is in Product_04.php):

abstract class Ch2_Product
{
  // properties defined here
  protected $_type;
  protected $_title;

  // methods defined here
  public function getProductType()
  {
    return $this->_type;
  }

  public function getTitle()
  {
    return $this->_title;
  }
}

The only differences are the addition of the abstract keyword in the first line and the removal of the constructor. I could have left the constructor if all child classes used the same one, but they don't. All that's left are the common properties and methods.

However, let's say you want all child classes to implement a particular method but know that the details of the method will be different for each class. Instead of defining a method in the abstract class and overriding it in each child class, you can define an abstract method. An abstract method simply names the method and sets its visibility but leaves the details to the child class. In our theoretical online store, you might want to create a method to display the details of each product. Because the details of each type of product are different, the implementation will differ. The following listing shows the Ch2_Product class with the addition of an abstract method called display() (the code is in Product_05.php):

abstract class Ch2_Product
{
  // properties defined here
  protected $_type;
  protected $_title;

  // methods defined here
  public function getProductType()
  {
    return $this->_type;
  }

  public function getTitle()
  {
    return $this->_title;
  }

  abstract public function display();
}

Declaring an abstract method like this forces all child classes to define the details of the method. Failure to do so triggers a fatal error. So, in essence, this says all classes in the Ch2_Product hierarchy must have a display() method, but acknowledges that the implementation will be different for each class. For the Ch2_Book class, it might look like this (the code is in Book_05.php):

public function display()
{
  echo "<p>Book: $this->_title ($this->_pageCount pages)</p>";
}

For Ch2_DVD, it might look like this (the code is in DVD_03.php):

public function display()
{
  echo "<p>DVD: $this->_title ($this->_duration)</p>";
}

You can then create instances of both classes and use the display() method to output the appropriate data for each type of object. The following code (in product_test_10.php) outputs the display shown in Figure 2-8:

$book = new Ch2_Book('PHP Object-Oriented Solutions', 300);
$movie = new Ch2_DVD('Atonement', '2 hr 10 min'),
$book->display();
$movie->display();

Figure 2.8. By declaring an abstract method, each child class is forced to implement its own version.

An interface is very similar to an abstract class, but it has no properties and cannot define how methods are to be implemented. Instead, it is simply a list of methods that must be implemented. Moreover, all methods must be public. While this sounds bizarre, it has two main purposes, namely:

This second characteristic is what makes interfaces very powerful. Let's say that the hypothetical e-commerce application in the examples throughout this chapter sells both downloadable products and ones that need to be delivered. It makes sense for all downloadable products to have a common set of features that won't be applicable to the deliverable goods. An interface offers a way of inheriting from a single parent while sharing an extra set of common features that don't necessarily apply to all child classes.

To create an interface, use the interface keyword followed by the name of the interface and a pair or curly braces. Inside the braces, declare the methods without defining their contents. A common convention is to prefix the name of an interface with an uppercase I, but the Zend Framework PHP coding standard that I'm following in this book ends the name with _Interface instead. Because the coding standard maps class and interface names to the directory structure, an interface called Ch2_Downloads_Interface would be stored as Interface.php in a folder called Ch2/Downloads. This can result in a large directory structure, but it has the advantage of consistency and clarity. However, you can choose whichever convention you like. An interface for downloadable items might look something like this:

interface Ch2_Downloads_Interface
{
  public function getFileLocation();
  public function createDownloadLink();
}

To use an interface, include it automatically with __autoload() or manually with require_once and follow the class name with the keyword implements and the name of the interface in the class definition like this (since I haven't implemented the methods, there are no download files for this example):

require_once 'Downloads/Interface.php';
class Ch2_Ebook extends Ch2_Product implements Ch2_Downloads_Interface
{
  // properties and other methods

  public function getFileLocation()
  {
    // details of method
  }

  public function createDownloadLink()
  {
    // details of method
  }
}

A class can implement multiple interfaces. Just list them as a comma-delimited list after the implements keyword. The big question is, "Why bother?" To understand that, we need to take another look at class hierarchy.

The obvious value of inheritance from a common class is that it avoids the need to repeat code in the child classes. But if that were the only advantage, inheritance and overriding would be little more than a glorified way of selectively including code from a common file. A fundamental aspect of OOP is exercising greater control over the way code works. Inheritance ensures that all related objects share common features and work in a similar way—just like all dogs bark and wag their tails when happy.

In the same way that a dachshund and a spaniel are instances of their own breeds (in object-oriented terms, classes), they are also both dogs. In turn, they are also animals, but they belong to a specialized branch of animals known as mammals. So, a dachshund can be classified as an instance of any of these particular types.

The same applies to objects in PHP. If you created an object from the Ch2_Ebook example in the preceding section, it would not only be an instance of the Ch2_Ebook class but also of Ch2_Downloads_Interface and Ch2_Product.

To find out which class an object belongs to, use the get_class() function like this:

$book = new Ch2_Book('PHP Object-Oriented Solutions', 300);
echo get_class($book);  // displays Ch2_Book

To find out its parent class, use get_parent_class() like this:

echo get_parent_class($book);  // displays Ch2_Product

There are two ways to find out whether a class is a subclass of another. The first is to use the is_subclass_of() function. This takes two arguments: the object you want to check and a string containing the name of the class that you want to know whether it's one of the object's parents, for example:

if (is_subclass_of($book, 'Ch2_Product'))  // equates to true

The other way is to use the instanceof operator like this (note that the name of the class is not in quotes):

if ($book instanceof Ch2_Product)  // equates to true

The important thing to note about instanceof is that it can also be used to determine whether an object implements a particular interface. The functions, get_class(), get_parent_class(), and is_subclass_of(), test only for direct inheritance.

Knowing whether an object is an instance of a particular class or interface is important in being able to control program flow. To go back to the animal analogy from earlier, you might be happy to let such animals as cats and dogs into your home, but few people are likely to welcome a crocodile. In object-oriented terms, checking whether an animal implements the Pet interface could save you from a nasty shock.

Restricting acceptable data with type hinting

Let's say that you have developed the simple examples in this chapter ready for deployment in an e-commerce application. Such an application is likely to have a class for the shopping cart and a method called addItem() to add the user's purchases to the cart. To avoid errors, you need to check that the item being added belongs to an acceptable data type. One way of doing so would be to use the instanceof operator like this:

public function addItem($item)
{
  if ($item instanceof Ch2_Product) {
    // It's OK, add it to the cart
  } else {
    // Reject it
  }
}

PHP also offers a limited version of type hinting, a common feature in OOP languages that restricts the type of acceptable data. PHP supports type hinting for objects and (since PHP 5.1) arrays when passed as arguments to methods or functions. You create type hints at the time of defining a function or method by preceding the argument with the type of data you require. If you want a particular type of object, use the class name; for an array, use the word array. The basic syntax looks like this:

function functionOrMethodName(TypeRequired $argumentName)

If an argument passed to the function or method is of the wrong type, it generates a fatal error.

The data type of a Ch2_Book object is not only Ch2_Book but also Ch2_Product. Figure 2-9 summarizes how to restrict the type of data accepted by the addItem() method of a shopping cart; and the following exercise shows the basic code involved.

Figure 2.9. Type hinting ensures that only the right data type is accepted.

Experimenting with type hinting

This exercise creates the world's least fully featured shopping cart to demonstrate how type hinting restricts the type of data that can be passed as an argument.

1. Create a file called ShoppingCart.php in the Ch2 folder, and define the Ch2_ShoppingCart class like this (the code is in ShoppingCart_01.php in the download files):

   class Ch2_ShoppingCart
   {
     public function addItem(Ch2_Book $item)
     {
       echo '<p>' . $item->getTitle() . ' added</p>';
     }
   }

   The class has a single method, addItem(), which displays the title of the item together with the word "added." To start off with, the method will accept only Ch2_Book objects, so the Ch2_Book class name is added as a type hint in front of the $item parameter. That's all there is to it. (I told you it was the world's least featured shopping cart).

2. Create a file called cart_test.php in the ch2_exercises folder, and insert the following code (it's in cart_test_01.php):

   require_once '../Ch2/Book.php';
   require_once '../Ch2/ShoppingCart.php';
   
   $book = new Ch2_Book('PHP Object-Oriented Solutions', 300);
   $cart = new Ch2_ShoppingCart();
   $cart->addItem($book);

   This includes the class files for the Ch2_Book and Ch2_ShoppingCart classes, creates an instance of each class, and adds the $book object to the cart.

   Note

   As explained earlier, the exercises refer to individual files by a basic name. If you have been doing the exercises yourself, Book.php should contain the correct code. However, the class definition has changed several times throughout the chapter, so the download files use numbers at the end of each filename to ensure the correct one is loaded.

3. Test the page, and you should see the result shown in Figure 2-10. No surprises: $book is a Ch2_Book object, and that's what the type hint in Ch2_ShoppingCart:: addItem() specifies.

   

   Figure 2.10. The book has been added to the cart.

4. Now let's try adding a DVD to the cart. You need to include the Ch2_DVD class file and create an instance of the class. Amend the code in cart_test.php like this (it's in cart_test_02.php):

   require_once '../Ch2/Book.php';
   require_once '../Ch2/ShoppingCart.php';
   require_once '../Ch2/DVD.php';
   
   $book = new Ch2_Book('PHP Object-Oriented Solutions', 300);
   $cart = new Ch2_ShoppingCart();
   $cart->addItem($book);
   $movie = new Ch2_DVD('Atonement', '2 hr 10 min'),
   $cart->addItem($movie);

5. Test the page again. This time you should see the error of your ways (well, mine since I told you to do it), as shown in Figure 2-11.

   

   Figure 2.11. The DVD is of the wrong data type and generates a fatal error.

6. To fix the problem, change the type hint in Ch2_ShoppingCart::addItem() like this (the code is in ShoppingCart_02.php):

   public function addItem(Ch2_Product $item)

7. Test the page again (the download file is cart_test_03.php because it needs to include the amended Ch2_ShoppingCart class). This time, both items are accepted, as shown in Figure 2-12, because the addItem() method expects an object of their parent class, Ch2_Product.

   

   Figure 2.12. Using the parent class for the type hint results in both the book and DVD objects being accepted.

When using type hints, you can specify only one type, so you need to be careful how you structure your class hierarchy. This is where interfaces can be handy. If you have a method that applies only to downloadable items, all of which implement an interface called Downloads_Interface, you can use Downloads_Interface as the type hint to prevent the wrong type of object being passed to it.

Type hinting is optional, so even if you provide a type hint for one argument, it's not necessary to provide one for every argument in the same method or function. In fact, you very often can't. Unlike other languages, there is no type hinting support for other data types, such as integers or strings; nor can you specify the type of data to be returned by the method or function. In spite of these limitations, the support for object type hinting means that you can easily test that the right type of object is being passed as an argument.

If you look closely at Figure 2-11, you'll see that the fatal error is described as "catchable." This refers to the error handling model known as exceptions introduced in PHP 5. Exceptions and how to catch them are explained In "Handling errors with exceptions" later in this chapter.

One of the first things you learn about working with arrays in PHP is that you can't use echo or print to display the contents of an array. All you see onscreen is the word Array. If you attempt to use echo or print with an object, the result is even less user friendly. Using an object in any situation where a string is expected results in a fatal error.

However, it's often useful to be able to display an object as a string, so the magic method __toString() lets you specify what to display in such a context. The method simply needs to return a string; what it contains is entirely up to you. For example, if you want the Ch2_Book class to display the title of the book when used with echo, define the __toString() method inside the class like this (you can see the full class definition in Book_06.php):

class Ch2_Book extends Ch2_Product
{
  // existing properties and methods

  public function __toString()
  {
    return $this->_title;
  }
}

You can test this by running product_test_11.php in Ch2_exercises. It simply displays the title of this book, but you could expand the definition of __toString() to display a much more detailed description of the object.

Since PHP 5, when you assign an object to another variable, you don't make a copy of it; instead, PHP creates a reference to the same object. Take this simple example:

$x = new MyObject();
$y = $x;

If you do this, $x and $y both point to the same object. Any changes you make to the properties of object $y will automatically be made to object $x. They are indivisible.

To make a copy of an object, you need to clone it with the clone keyword like this:

$y = clone $x;

This creates what is known as a shallow copy of the original object's properties. This means a copy is made of each property that contains a value, which can then be changed independently. However, any property that contains a reference to another object or resource remains a reference.

An example should make this clearer. I'm going to create a Ch2_Manufacturer class to store the details of a product's manufacturer. To keep things simple, the class has only one property, but in the real world, it would store many more: contact details, bank account, credit rating, and so on. The class looks like this (the code is in Manufacturer.php in the Ch2 folder of the download files):

class Ch2_Manufacturer
{
  protected $_name;

  public function setManufacturerName($name)
  {
    $this->_name = $name;
  }

  public function getManufacturerName()
  {
    return $this->_name;
  }
}

To associate the manufacturer with a particular product, you use a technique known as aggregation. This simply means that one object acts as a container for one or more other objects. To add a manufacturer to the Ch2_Book and Ch2_DVD classes, you need to amend the abstract Ch2_Product class like this (the code is in Product_06.php in the Ch2 folder):

require_once 'Manufacturer.php';

abstract class Ch2_Product
{
  protected $_type;
  protected $_title;
  protected $_manufacturer;

  public function __construct()
  {
    $this->_manufacturer = new Ch2_Manufacturer();
  }

  public function getProductType()
  {
    return $this->_type;
  }

public function getTitle()
  {
    return $this->_title;
  }

  abstract public function display();

  public function setManufacturerName($name)
  {
    $this->_manufacturer->setManufacturerName($name);
  }

  public function getManufacturerName()
  {
    return $this->_manufacturer->getManufacturerName();
  }
}

The changes to the Ch2_Product class are highlighted in bold. The constructor creates a new instance of the Ch2_Manufacturer class and assigns it to the $_manufacturer property. This property is an object, but it doesn't exist in its own right; it's wrapped inside a Ch2_Product. So, to set or get its name, getter and setter methods inside the Ch2_Product class use the $_manufacturer object (referred to as $this->_manufacturer) to call the equivalent Ch2_Manufacturer methods.

Because the Ch2_Product class now has a constructor, the child classes need to call the parent constructor like this (for simplicity, I'm showing just the Ch2_Book constructor; the full code is in Book_07.php):

public function __construct($title, $pageCount)
{
  parent::__construct();
  $this->_title = $title;
  $this->_pageCount = $pageCount;
  $this->_type = 'book';
}

With these changes to the classes, you can create a Ch2_Book object and assign the name of the manufacturer like this:

$book = new Ch2_Book('PHP Object-Oriented Solutions', 300);
$book->setManufacturerName('friends of ED'),

The problem arises if you decide to clone the $book object. To demonstrate the different way clone treats properties depending on whether they refer to an object or resource, the revised version of Ch2_Book in Book_07.php contains a method that lets you change the title of the book. The three lines of code highlighted in bold in the following script in product_test_12.php clone $book and give the cloned version a new title and manufacturer:

require_once '../Ch2/Book_07.php';

$book = new Ch2_Book('PHP Object-Oriented Solutions', 300);
$book->setManufacturerName('friends of ED'),
echo '<p>' . $book->getTitle() . ' is manufactured by '. 

  $book->getManufacturerName() . '</p>';
$book2 = clone $book;
$book2->setTitle('Website Disasters'),
$book2->setManufacturerName('enemies of ED'),
echo '<p>' . $book2->getTitle() . ' is manufactured by '. 

  $book2->getManufacturerName() . '</p>';
echo '<p>' . $book->getTitle() . ' is manufactured by '. 

  $book->getManufacturerName() . '</p>';

Figure 2-13 shows what happens when you run this script. The $_title property is a string, so changing the title of the cloned object doesn't affect the original. However, even though the manufacturer's name is also a string, it belongs to a Ch2_Manufacturer object inside $book. The shallow copy performed by the clone keyword results in the cloned object still pointing to the original Ch2_Manufacturer object. Changing the manufacturer's name for $book2 changes it for both books.

Figure 2.13. Cloning an object can have unexpected consequences when other objects are aggregated.

The __clone() magic method gets around this problem. Whenever you copy an object using the clone keyword, PHP checks if you have defined a __clone() method and calls it automatically. This magic method lets you specify any changes you want made to the object being cloned. If a property contains a reference to another object, you need to clone the property itself. Doing so breaks the reference by producing a copy of the object, which can then be changed without affecting the original. You define __clone() just like any other method. So, to break the reference to the original Ch2_Manufacturer object in the $_manufacturer property, you need to add the following to the Ch2_Product class definition (the full code is in Product_07.php):

public function __clone()
{
  $this->_manufacturer = clone $this->_manufacturer;
}

If you run the same script as before, the manufacturers' names are now independent of each other, as shown in Figure 2-14. You can test this in product_test_13.php in the download files. (product_test_13.php includes a different version of Ch2_Book, because Ch2_Book needs to inherit the revised version of Ch2_Product. The only difference in the code is the addition of the __clone() method in the Ch2_Product class.)

Figure 2.14. The __clone() magic method creates a clone of the aggregated object, making it independent of the original.

You can also use the __clone() magic method to change any other values when cloning an object. For instance, you might want to reset an ID property to zero, so the clone doesn't end up with the same ID as the original object.

Some developers find writing getter and setter methods for private and protected properties tedious, so PHP provides two magic methods, __get() and __set(), that handle everything automatically for you. Before you get too excited by this prospect, I should warn you that if you create both __get() and __set(), the value of any property handled this way is treated as public and can be changed arbitrarily by outside code. Although creating individual getter and setter methods is more time consuming, it gives you much greater control over how protected and private properties can be changed or inspected.

A common way of using __get() and __set() is to create a protected or private property to store the values of undeclared properties as an associative array. The __get() method checks whether the array element exists; if it does, it returns the value. The __set() method simply adds the value to the array. This behavior is not enabled by default, so you need to define the __get() and __set() methods explicitly in your class like this:

class Lazy
{
  // property to hold undeclared properties
  protected $_props;

  // magic methods
  public function __get($name)
  {
    if (isset($this->_props[$name])) {
      return $this->_props[$name];
    } else {
      return false;
    }
  }

  public function __set($name, $value)
  {
    $this->_props[$name] = $value;
  }
}

Using __get() isn't always bad. As you'll see in the next chapter, it's useful for creating read-only properties.

The __call() magic method is used to call methods that don't exist in the current class. While this might sound illogical, it's useful when using aggregation. In the section titled "Cloning an object" earlier in the chapter, I wrapped the getter and setter methods for the Ch2_Manufacturer class in methods of the same name in Ch2_Product. Doing this for just one or two methods is fine, but it becomes a burden in terms of code manageability when there are a lot of them.

Even though a Ch2_Product object can store a reference to a manufacturer object, it can't invoke any of the other class's methods. If you define the __call() magic method, though, PHP calls the other class's method as if it belonged to the Ch2_Product class.

The __call() magic method takes two arguments: the method name and an array of arguments to be passed to the method. You pass these in turn to call_user_func_array() and return the result. However, you need to tell call_user_func_array() which class the method belongs to. So, the first argument to call_user_func_array() must be an array that contains the aggregated object and the local variable containing the method name.

The code for the __call() magic method is always the same. The only thing that you need to change is the name of the property (highlighted in bold in the following script) that contains the object whose methods you want to call automatically. Taking the example of an object stored by aggregation in a protected property called $_manufacturer, this is how you would define the __call() magic method:

public function __call($method, $arguments)
{
  // check that the other object has the specified method
  if (method_exists($this->_manufacturer, $method)) {
    // invoke the method and return any result
    return call_user_func_array(array($this->_manufacturer, $method), 

$arguments);
  }
}

The download files contain a revised version of Ch2_Product in Product_08.php. The setManufacturerName() and getManufacturerName() methods have been deleted, and the __call() magic method has been defined.

If you run the script in product_test_14.php, you should see the same result as in Figure 2-14. Instead of using its own getter and setter methods for the manufacturer's name, the Ch2_Product class now directly accesses those defined in the Ch2_Manufacturer class.

Normally, PHP handles memory management through garbage collection—the automatic removal of variables and objects when they're no longer needed by a script. However, there are occasions when you might want to delete a resource, such as a database connection, when an object is no longer needed. Just as PHP calls the __construct() method whenever you create a new object, it looks for the __destruct() magic method immediately before removing an object from memory and runs the destructor automatically if it has been defined.

You define a destructor just like any other method:

public function __destruct()
{
  // code to clear up resources before object is deleted
}

A destructor cannot take any arguments. It's also advisable to avoid calls to other objects in a destructor, as there is no way to dictate the order in which objects are deleted, and the other object might already have been deleted by the time the destructor attempts to access it.

When writing scripts, it's normal practice to test the type of data passed to a function. This often results in complex conditional statements that determine what should happen if the data is of the wrong type. The advantage of using exceptions is that it reduces complexity by handling what should be done in a separate part of the script. This is particularly important with OOP, because classes should be designed to be as project neutral as possible. So, when a problem arises with data passed to a method, keep things simple by throwing an exception inside the method, and leave it to the main application script to determine how to handle it.

The way you throw an exception is with the throw keyword like this:

if (the sky falls in) {
  throw new Exception('Oops, the sky has fallen in!'),
}

Following the throw keyword, you instantiate a new Exception object, which takes one argument: a string that identifies the nature of the problem. Technically speaking, this argument is optional; if you omit it, PHP uses the default value, "Unknown exception." You can also pass a number as an optional second argument. The number has no significance other than to identify the exception. This allows you to set up your own system of error codes.

Once an exception has been thrown, it needs to be caught.

Whenever you use code that might throw exceptions, wrap the code in a try block and catch any exceptions in a catch block. This structure is similar to an if . . . else conditional statement, except that it uses try and catch instead of if and else. The basic structure looks like this:M

try {
  // code that might throw exceptions
} catch (Exception $e) {
  // handle the exception here
}

The try block could be dozens, even hundreds of lines long. If the code throws an exception, the script jumps immediately to the catch block, where the code decides how to handle the problem. In a development environment, you normally want to display a descriptive error message; but in a production environment, you could redirect the user to a custom error page, while sending an email with details of the problem to the server administrator.

The parentheses after the catch keyword should contain a variable to capture the details of the exception. It's also a good idea to use type hinting (see "Restricting acceptable data with type hinting" earlier in the chapter) to indicate what type of exception you want to deal with. In addition to the basic Exception class, the Standard PHP Library (SPL) defines a number of specialized exception classes that you can use in your class definitions (see Chapters 8 and 9). You can also create your own custom exceptions. Using different types of exceptions enables you to have multiple catch blocks that handle problems in different ways. For example, you might create custom exceptions called InvalidDataException and DatabaseErrorException. You could then handle them like this:

try {
  // script to be processed
} catch (InvalidDataException $e) {
  // redirect user to input page with appropriate error message
} catch (DatabaseErrorException $e) {
  // redirect user to database error page
} catch (Exception $e) {
  // handle any generic exceptions
}

The catch block for generic exceptions must come last. Otherwise the type hinting won't work, as custom exceptions need to extend the built-in Exception class, and therefore belong to the same data type.

Once you have caught an exception in a catch block, you can extract information about the error and where it occurred by using the Exception class's built-in methods. Table 2-2 lists the methods and the type of information they provide.

Because the Exception class has a built-in __toString() method, the simplest way to find out the details of the error is to use echo followed by the variable used to catch the exception like this:

echo $e;

It can't get much simpler than that.

As you can see from Table 2-2, all the built-in methods, except __toString(), are final. This means __toString() is the only one that can be overridden.

The other methods provide a finer level of detail, so you can display or log the information in a more user-friendly way. Note that the getLine() method refers to the class definition. This reflects the fact that it's the class that throws the exception, not the script that utilizes the class. However, what you're usually interested in is locating whatever it was in your script that caused the class to throw an exception. To find that information, you need to extract it from the line element of the array returned by getTrace(). An actual example should clarify how exceptions work.

Throwing and catching an exception

This exercise expands the Ch2_Book class from the examples earlier in the chapter to demonstrate how to throw an exception when invalid data is passed to a Ch2_Book object. It also shows what happens when you fail to catch the exception, and the type of information that can be extracted from an exception that has been caught. Continue working with Book.php from earlier in the chapter. If you no longer have the file, save Book_09.php in the Ch2 folder as Book.php.

This exercise shows only the information that you can extract from the Exception class methods. What you put in a catch block is entirely up to you. Since an exception brings a script to a halt, the catch block in a production environment should find some way of handling the error gracefully without exposing sensitive details about your server or online application.

In addition to the methods listed in Table 2-2, the Exception class has the four properties described in Table 2-3.

Because these properties are protected, they are available in any custom class that extends the Exception class.

I won't go into detail about extending the Exception class, because you extend it in exactly the same way as any other class. You can define your own properties and methods. If you override the constructor in your custom class, it is recommended that you call the parent constructor explicitly to ensure that all available data has been properly assigned. The following example taken from the PHP manual shows how you should do it:

// Redefine the exception so message isn't optional
public function __construct($message, $code = 0)
{
  // your own custom code
  // make sure everything is assigned properly
  parent::__construct($message, $code);
}

The normal practice with PHPDoc is to place a comment block before each function (or method) describing its purpose, the arguments it expects, and what it returns (if anything). You can also use comment blocks to describe properties and other variables.

The following example comes from the Pos_Date class in the next chapter and describes the setDate() method.

/**
 * Changes the date represented by the object.
 *
 * Overrides the default DateTime setDate() method, and checks
 * that the arguments supplied constitute a valid date.
 *
 * @param  int   $year   The year as a four-digit number.
 * @param  int   $month  The month as a number between 1 and 12.
 * @param  int   $day    The day as a number between 1 and 31.
 */

The comment block begins with a forward slash followed by two asterisks (/**). This is a signal to the PHPDoc parser that a PHPDoc comment block is starting. Each subsequent line should also begin with an asterisk. The comment block ends like a normal multiline comment with an asterisk followed by a forward slash (*/).

The first line of the comment block should contain a brief description of what's being commented. The second section contains a more detailed description. The final section contains PHPDoc tags. Each tag must be on a new line and begin with an @ mark. Nothing should precede the tag except whitespace and the asterisk at the start of the line. The preceding example contains three instances of the @param tag.

The @param tag describes an argument accepted by the method. Each argument is listed in the order expected by the method. Following @param is a keyword indicating the required data type. In this case, all three arguments are expected to be integers (int). Then follow the name of the argument, and a brief description.

Table 2-4 lists the most commonly used PHPDoc tags, what should follow the tag, and a description of its use. Where more than one type of data is expected after a tag, separate them with whitespace, not commas.

The following PHPDoc tags should not be used: @abstract, @final, and @static. They were created for PHP 4, which didn't support the abstract, final, or static keywords. Using the keywords in the class definition is now sufficient.