Delicious Bookmark this on Delicious Share on Facebook SlashdotSlashdot It! Digg! Digg



PHP : Language Reference : Classes and Objects (PHP 5) : Type Hinting

Type Hinting

PHP 5 introduces Type Hinting. Functions are now able to force parameters to be objects (by specifying the name of the class in the function prototype) or arrays (since PHP 5.1).

Example 10.41. Type Hinting examples

copy to clipboard
<?php
// An example class
class MyClass
{
   /**
    * A test function
    *
    * First parameter must be an object of type OtherClass
    */
   public function test(OtherClass $otherclass) {
       echo $otherclass->var;
   }


   /**
    * Another test function
    *
    * First parameter must be an array
    */
   public function test_array(array $input_array) {
       print_r($input_array);
   }
}

// Another example class
class OtherClass {
   public $var = 'Hello World';
}
?>

Failing to satisfy the type hint results in a fatal error.

copy to clipboard
<?php
// An instance of each class
$myclass = new MyClass;
$otherclass = new OtherClass;

// Fatal Error: Argument 1 must be an object of class OtherClass
$myclass->test('hello');

// Fatal Error: Argument 1 must be an instance of OtherClass
$foo = new stdClass;
$myclass->test($foo);

// Fatal Error: Argument 1 must not be null
$myclass->test(null);

// Works: Prints Hello World
$myclass->test($otherclass);

// Fatal Error: Argument 1 must be an array
$myclass->test_array('a string');

// Works: Prints the array
$myclass->test_array(array('a', 'b', 'c'));
?>

Type hinting also works with functions:

copy to clipboard
<?php
// An example class
class MyClass {
   public $var = 'Hello World';
}

/**
* A test function
*
* First parameter must be an object of type MyClass
*/
function MyFunction (MyClass $foo) {
   echo $foo->var;
}

// Works
$myclass = new MyClass;
MyFunction($myclass);
?>


Type Hints can only be of the object and array (since PHP 5.1) type. Traditional type hinting with int and string isn't supported.

Code Examples / Notes » language.oop5.typehinting

mlovett
Type hinting works with interfaces too. In other words, you can specify the name of an interface for a function parameter, and the object passed in must implement that interface, or else type hinting throws an exception.

andrea giammarchi
Type Hinting is a good idea but PHP 5 doesn't support explicit overload so this is my Type Hinting overload proposal using "magic" __call method and a bit of Reflection.
<?php
// just two classes ...
class A{
private $value;
function __construct($value){
$this->value = $value;
}
function __toString(){
return ''.$this->value;
}
}
class B extends A{}
// just another class with my fake Type Hint overload
class Overload {
protected function doSomething0(A $a) {
return 'Recieved an A instance with value: '.$a;
}

protected function doSomething1(B $b) {
return 'Recieved a B instance with value: '.$b;
}

protected function doSomething2(A $a, B $b) {
return $this->doSomething0($a).' and '.$this->doSomething1($b).' too';
}

protected function doSomething3(B $b, A $a) {
return $this->doSomething1($b).' and '.$this->doSomething0($a).' too';
}

// magic __call
public function __call($method, $arguments){
for(
$methods = call_user_func(array(new ReflectionObject($this), 'getMethods')),
$re = '/^'.$method.'[0-9]+/',
$i = 0, $j = count($methods), $k = count($arguments);
$i < $j; $i++
) {
if(
preg_match($re, $methods[$i]->name) &&
$methods[$i]->getNumberOfRequiredParameters() === $k
) {
$params = $methods[$i]->getParameters();
for(
$l = 0, $call = true;
$l < $k && $call;
$l++
)
$call = call_user_func(array(new ReflectionObject($arguments[$l]), 'getName')) === $params[$l]->getClass()->name;
if($call)
return call_user_func_array(array($this, $methods[$i]->name), $arguments);
}
}
}
}
// just a test to check my proposal
$o = new Overload();
$a = new A('test one');
$b = new B('test two');
echo $o->doSomething($a), '<br />',
$o->doSomething($b), '<br />',
$o->doSomething($a, $b), '<br />',
$o->doSomething($b, $a), '<br />';
?>
That's all, do You like it?

mega-squall
Type hinting cannot be used with array of instances of a given class. When submited to PHP Team, idea got this answer :
" That's impossible and never will be. But you can do that more or less yourself. Derive a class that implements ArrayAccess or reuse ArrayObject/ArrayIterator. And overload its offsetSet(). In the method body you add the check to ensure only what you want can go in. Now if that class accepts only B's (B beeing an examble classname, ndla) you may call it ArrayOfB and the use ArrayOfB as you typehint. "
This is obviously reaching the limit between "typing" and "type hinting" ...

jazz
To Nikivich and Edorian:
There are many times when you would use an equals() method other than to find out if the two objects are the same object. Think of all the primitive wrapper classes in Java, for example -- if you create two new Integer()'s with identical values, equals() returns true, even though they are two different objects. There would be no reason to allow someone to perform an equals() between an Integer and, say, a GregorianCalendar -- it just doesn't make sense. In Java you would attempt this and probably get a ClassCastException, but in PHP no such facility exists, so the best way to prevent this would be through type hinting.
The point Nicholas was making is that you can't specify a stricter type hint on an inherited method, and despite your arguments, that would be a truly useful thing to be able to do.
(True overloading would be a better way, IMHO, but *shrug*)

02-sep-2006 04:59
The type hinting system can also be used for interfaces.  Example:
<?php
interface fooface
{
public function foo ();
}
class fooclass implements fooface
{
public function foo ()
{
echo ('foo
');
}
}
class barclass implements fooface
{
public function foo ()
{
echo ('bar
');
}
}
class bazclass implements fooface
{
public function foo ()
{
echo ('baz
');
}
}
class quuxclass
{
public function foo ()
{
echo ('quux
');
}
}
function callfoo (fooface $myClass)
{
$myClass -> foo ();
}
$myfoo = new fooclass;
$mybar = new barclass;
$mybaz = new bazclass;
$myquux = new quuxclass;
callfoo ($myfoo);
callfoo ($mybar);
callfoo ($mybaz);
callfoo ($myquux); // Fails because the quuxclass doesn't implement the fooface interface
?>
Using this syntax you can allow a function to work with different classes as long as they all implement the same interfaces.  An example might be an online shop that implements a plugin system for payment.  If the creator of the script provides a payment module interface then functions can check if it has been implemented in a given payment class.  This means that the details of the class are unimportant, so it doesn't matter if it interfaces with PayPal, HSBC, ProTX or any other payment system you care to name, but if it doesn't properly provide all the functionality a payment module requires a fatal error is generated.  
Unfortunately, it doesn't seem possible to use type hinting with new.  In java you could do a "fooface myfoo = new fooclass" which would fail if you tried it with quuxclass instead, but as far as I can tell you can't do a similar test on create with PHP.

jesdisciple @t gmail -dot- com
The manual's sample code says:
<?php
//...
// Fatal Error: Argument 1 must not be null
$myclass->test(null);
//...
?>
And this is true, unless a default value of NULL is given; in fact, this is the only way to give a default value for object arguments (as a default value must be a constant expression):
<?php
$mine = new MyClass();
$mine->test(NULL);
class MyClass{
   public function __construct(OtherClass $arg = NULL){
       if(is_null($arg)){
           //Apply default value here.
       }
   }
   public function test(array $arr = NULL){
       print_r($arr);
   }
}
class OtherClass{
   
}
?>

nicholas
Please note that the following will not work:
<?php
abstract class Object
{
public abstract function toString( );
public abstract function equals( Object &$o );
}
class Chair extends Object
{
public function toString( )
{
return 'This is a chair.';
}

public function equals( Chair &$o )
{
return TRUE;
}
}
class Table extends Object
{
public function toString( )
{
return 'This is a table.';
}

public function equals( Table &$o )
{
return TRUE;
}
}
$chair = new Chair();
$table = new Table();
echo $chair->equals( $table );
?>
The expected output is "Fatal error: Argument 1 passed to Chair::equals() must be an instance of Chair, called in [filename] on line 38 and defined in [filename] on line 16" but instead you get "Fatal error: Declaration of Chair::equals() must be compatible with that of Object::equals() in [filename] on line 20".
This is unlike other OO languages (secifically Java) which not only allow but expect this type of code. It is in the nature of abstraction. However, you can get similar results using the following code instead:
<?php
abstract class Object
{
public abstract function toString( );
public abstract function equals( self &$o );
}
class Chair extends Object
{
public function toString( )
{
return 'This is a chair.';
}

public function equals( self &$o )
{
return TRUE;
}
}
class Table extends Object
{
public function toString( )
{
return 'This is a table.';
}

public function equals( self &$o )
{
return TRUE;
}
}
$chair = new Chair();
$table = new Table();
echo $chair->equals( $table );
?>
This code gives the expected result "Fatal error: Argument 1 passed to Chair::equals() must be an instance of Chair, called in [filename] on line 38 and defined in [filename] on line 16". This is the proper behavior but isn't the most intuitive approach for those of us used to OO programming.
Hope this helps someone :-).
Nicholas

andrea giammarchi
Ok guys, this is a complete example about my proposal, I hope this will be useful to understand (and to use too).
<?php
class TypeHintOverloadable {
public function __call($method, $arguments){
for(
$methods = call_user_func(array(new ReflectionObject($this), 'getMethods')),
$re = '/^'.$method.'[0-9]+$/',
$i = 0, $j = count($methods), $k = count($arguments);
$i < $j; $i++
) {
if(
preg_match($re, $methods[$i]->name) &&
$methods[$i]->getNumberOfRequiredParameters() === $k
) {
$params = $methods[$i]->getParameters();
for(
$l = 0, $call = true;
$l < $k && $call;
$l++
)
$call = call_user_func(array(new ReflectionObject($arguments[$l]), 'getName')) === $params[$l]->getClass()->name;
if($call)
return call_user_func_array(array($this, $methods[$i]->name), $arguments);
}
}
throw new Exception('Unable to find method '.$method.' with specified overload');
}
}
class Example1 extends TypeHintOverloadable {
protected function doSomething0(A $a) {
return 'Recieved an A instance with value: '.$a;
}

protected function doSomething1(B $b) {
return 'Recieved a B instance with value: '.$b;
}

protected function doSomething2(A $a, B $b) {
return $this->doSomething($a).' and '.$this->doSomething($b).' too';
}

protected function doSomething3(B $b, A $a) {
return $this->doSomething($b).' and '.$this->doSomething($a).' too';
}

public function getName(){
return 'Example1';
}
}
class Example2 extends TypeHintOverloadable {
private $name = 'Example2';
public function doStuff1(){
return $this->name;
}
public function doStuff2(Example2 $instance){
return $instance->doStuff();
}
public function doStuff3(Example1 $instance) {
return $instance->getName();
}
protected function copyName1(Example2 $instance){
$this->name = $instance->doStuff();
}
protected function copyName2(Example1 $instance){
$this->name = $instance->getName();
}
public function newName($Example1_OR_Example2){
$this->copyName($Example1_OR_Example2);
}
}
// tests
class A{
private $value;
function __construct($value){
$this->value = $value;
}
function __toString(){
return ''.$this->value;
}
}
class B extends A{}
$o = new Example1();
$a = new A('test one');
$b = new B('test two');
echo $o->doSomething($a), '<br />',
$o->doSomething($b), '<br />',
$o->doSomething($a, $b), '<br />',
$o->doSomething($b, $a), '<br />';


$o2 = new Example2();
$o3 = new Example2;
echo $o2->doStuff(), '<br />',
$o2->doStuff($o), '<br />',
$o2->doStuff($o3), '<br />';
$o2->newName($o3);
$o2->newName($o);
echo $o2->doStuff().'<hr />';
echo $o2->noWay();
?>

edorian
In response to nicholas at nicholaswilliams dot info:
Of course this doesn't work. Not in Php nor in Java.
You can't put a Chair into Table just because there both implementing "Object"
It wouldn't make any sense to say "i'm expecting an argument that implements the same object that i'm implementing" with type hinting.
You say: "I'm expection an Object of that Class or a Object of a Subclass of that Class " like you do in every OO languange.

ldebuyst->brutele.be
In reply to Nikivich and Edorian:
Although it isn't quite clear from his post, I believe that the point nicholas is trying to make is that, if you typehint an abstract function, you MUST use that same typehint for all classes extending the abstract class.
As his example shows, if you typehint (Object $object), then  you must use the exact same typehint in the extending class. Using the typehint (Table $table) or (Chair $chair) will give fatal errors, even if Table and Chair are subclasses of Object.
In other words, type hinting allows for descendants, as caliban at darklock dot com has shown, except when you're subclassing.
See http://bugs.php.net/bug.php?id=36601 for a bit more info. Flagged as wontfix, though, so something to keep in mind.

nikivich
In reply to Nicolas
I don't think you exactly understand the inheritance principles
If you want to do the equals thing in a decent OO way, you would do something like this:
class Object {
     public equals(Object &o) {
           return this == &o; //perform default equals check, one could arguably say that === is the correct default, but doesnt matter for the example
     }
}
class Chair extends Object {
}
class Table extends Object {
}
$chair = new Chair();
$table = new Table();
$chair->equals($table); //will print false (zero)
This is actually a correct implementation of an equals method. Since you want to take a chair for example and just call equals() on it WITH ANY OBJECT, you should only hint Object, not an implementation, since the whole point of the equals method is to find out whether it is actually the same object :-) I want to be able to pass a table (which implements Object too, so is perfectly allowed as a parameter to equals).
Hope this clears it up a bit for you... :-)

caliban
In case you're worried, type hinting does allow descendants. Extending the documentation example:
<?php
  // Example class
  class MyClass
  {
     public function test(OtherClass $otherclass)
     {
         if(is_callable(array($otherclass,$otherclass->var)))
         {
            $otherclass->{$otherclass->var}();
         }
         else
         {
            echo $otherclass->var;
         }
     }
  }
  // Another example class
  class OtherClass
  {
     public $var = 'Hello World';
  }
  // Yet another example class
  class DerivedClass extends OtherClass
  {
     function __construct()
     {
        $this->var="Planet";
     }
     public function Planet()
     {
        echo "Hello ".$this->var;
     }
  }
  $myclass = new MyClass;
  $otherclass = new OtherClass;
  $derivedclass = new DerivedClass;
  // Works - prints "Hello World"
  $myclass->test($otherclass);
  // Works - calls DerivedClass::Planet()
  //    which prints "Hello Planet"
  $myclass->test($derivedclass);
?>

13-sep-2006 11:00
If one is type hinting for a specific class type but wishes for there to be a default option of no object at all (e.g., to work on the object if it exists, or do something else (e.g., print out data) if it doesn't exist), this can be done by (and only by) NULL:
<?php
function printBreadcrumbs(Smarty &$smarty = NULL) {
  $breadcrumbs = <add code here to make or obtain breadcrumbs>;
  if ($smarty != NULL) {
     $smarty->assign('breadcrumbs', $breadcrumbs);
  }
  else {
     print $breadcrumbs;
  }
}
?>
If one tries to change NULL to '' or the like, one will get this error message:
    Default value for parameters with a class type hint can only be NULL

yarco dot w
I think php could add this feature: user could self define the __toXXX magic method. So when there exists type hinting, the object could automatically be changed into such type.
Code like this:
<?php
class A
{
  public function __toArray()
  { // do change to array
  }
}
function insertData(array $array)
{ // insert data into database
}
insertData($a = new A());
?>
object $a could automatically call __toArray().
It is very useful when you change data from database into model under MVC enviroment.(For example, zend framework. So you could do
$table->insert($a);
no need:
$table->insert($a->toArray());
//such ugly code if insert defined as  insert(array $array);

Change Language


Follow Navioo On Twitter
Introduction
The Basics
Autoloading Objects
Constructors and Destructors
Visibility
Scope Resolution Operator (::)
Static Keyword
Class Constants
Class Abstraction
Object Interfaces
Overloading
Object Iteration
Patterns
Magic Methods
Final Keyword
Object cloning
Comparing objects
Reflection
Type Hinting
Late Static Bindings
Terms of Service Privacy Policy Sitemap

©2024 -EPSILONSYS SOFTWARE inc

Other EPSILONSYS SOFTWARE Web Sites : Programming Resources | News Headline | Free local classifieds

eXTReMe Tracker