Recipe 7.20. Checking if an Object Is an Instance of a Specific Class

7.20.1. Problem

You want to check if an object is an instance of a specific class.

7.20.2. Solution

To check that a value passed as a function argument is an instance of a specific class, specify the class name in your function prototype:

public function add(Person $person) {         // add $person to address book     } }

In other contexts, use the instanceof operator:

<?php $media = get_something_from_catalog(); if ($media instanceof Book) {   // do bookish things } else if ($media instanceof DVD) {   // watch the movie } ?>

7.20.3. Discussion

One way of enforcing controls on your objects is by using type hints. A type hint is a way to tell PHP that an object passed to a function or method must be of a certain class.

To do this, specify a class name in your function and method prototypes. As of PHP 5.1, you can also require that an argument is an array, by using the keyword array. This only works for classes and arrays, though, not for any other variable types. You cannot, for example, specify strings or integers.

For example, to require the first argument to your AddressBook class's add( ) method to be of type Person:

class AddressBook {     public function add(Person $person) {         // add $person to address book     } }

Then, if you call add( ) but pass a string, you get a fatal error:

$book = new AddressBook; $person = 'Rasmus Lerdorf'; $book->add($person); PHP Fatal error:  Argument 1 must be an object of class Person in...

Placing a type hint of Person in the first argument of your function declaration is equivalent to adding the following PHP code to the function:

public function add($person) {         if (!($person instanceof Person)) {                 die("Argument 1 must be an instance of Person");         } }

The instanceof operator checks whether an object is an instance of a particular class. This code makes sure $person is a Person.

PHP 4 does not have an instanceof operator. You need to use the is_a( ) function, which is deprecated in PHP 5.

The instanceof operator also returns true with classes that are subclasses of the one you're comparing against. For instance:

class Person { /* ... */ } class Kid extends Person { /* ... */ } $kid = new Kid; if ($kid instanceof Person) {     print "Kids are people, too.\n"; }  Kids are people, too.

Last, you can use instanceof to see if a class has implemented a specific interface:

interface Nameable {     public function getName();     public function setName($name); } class Book implements Nameable {     private $name;     public function getName() {         return $this->name;     }     public function setName($name) {         return $this->name = $name;     } } $book = new Book; if ($book instanceof Book) {     print "You can name a Book.\n"; } You can name a Book

Type hinting has the side benefit of integrating API documentation directly into the class itself. If you see that a class constructor takes an Event type, you know exactly what to provide the method. Additionally, you know that the code and the "documentation" must always be in sync, because it's baked directly into the class definition.

You can also use type hinting in interface definitions, which lets you further specify all your interface details.

However, type hinting does come at the cost of less flexibility. There's no way to allow a parameter to accept more than one type of object, so this places some restrictions on how you design your object hierarchy.

Also, the penalty for violating a type hint is quite drastic'the script aborts with a fatal error. In a web context, you may want to have more control over how errors are handled and recover more gracefully from this kind of mistake. Implementing your own form of type checking inside of methods lets you print out an error page if you choose.

Last, unlike some languages, you cannot use type hinting for return values, so there's no way to mandate that a particular function always returns an object of a particular type.

7.20.4. See Also

Documentation on type hints at http://www.php.net/manual/language.oop5.typehinting.php and instanceof at http://www.php.net/manual/language.operators.type.php