====== Request for Comments: Return value and parameter type hint ======
  * Version: 1.0
  * Date: 2008-04-07
  * Author: Felipe Pena <felipensp@gmail.com>
  * Status: [[http://news.php.net/php.internals/37049|Under Discussion]]


====== Details of implementation ======
**Parameter type hint:**
  - The behavior when the default parameter value is ''NULL'' was kept.
**Both:**
  - Binary and unicode string are specified by ''string''.

===== Return value type hint =====

==== BC Break ====
No BC break using the "(type)" syntax. (Inspirated by Objective-C)


==== Examples ====

=== Using inside namespaces ===
<code php>
namespace foo;

class test { }

class bar {
	static public function (foo::test) testing($instance) {
		return $instance;
	}
}

bar::testing(new test);
bar::testing(new stdClass); // Catchable fatal error: The returned value should be instance of foo::test
</code>

=== Using inheritance ===
<code php>
interface ITest { }
class bar implements ITest { }
class foo extends bar { }

function (Itest) testing($instance) {
	return $instance;	
}

testing(new bar);
testing(new foo);
testing(new stdClass); // Catchable fatal error: The returned value must implement interface Itest
</code>

=== Interfaces ===

<code php>
interface ITest {
	public function (int) foo();	
}

class foo implements ITest {
	public function (int) foo() {
		return 'a';
	}	
}

$test = new foo;
$test->foo(); // Catchable fatal error: The returned value must be of the type integer
</code>

<code php>
interface ITest {
	public function (int) foo();	
}

class foo implements ITest {
	public function foo() {
		return 1;
	}	
}

$test = new foo;
$test->foo(); // Fatal error: Declaration of foo::foo() must be compatible with that of ITest::foo()
</code>

=== Trying use with magic methods ===
<code php>
class test {
	// Fatal error: Return type hint can't be used with magic methods
	public function (int) __toString() {
	}
}
</code>

=== PHP types ===
<code php>
function (int) test($value) {
	return $value;
}

test('1337'); // Catchable fatal error: The returned value must be of the type integer
</code>


===== Parameter type hint =====

==== BC Break ====

== New tokens (new keywords) ==
  - T_INTEGER (Keywords: int, integer)
  - T_BOOLEAN (Keywords: bool, boolean)
  - T_DOUBLE (Keywords: real, float, double)
  - T_OBJECT (Keyword: object)
  - T_RESOURCE (Keyword: resource)
  - T_STR (Keyword: string)

==== Other changes ====
  - Removed ZEND_ARG_ARRAY_INFO()
  - Added ZEND_ARG_PHP_TYPE_INFO()
<code diff u>
-#define ZEND_ARG_ARRAY_INFO(pass_by_ref, name, allow_null) { {#name}, sizeof(#name)-1, {NULL}, 0, 1, allow_null, pass_by_ref, 0, 0 },
+#define ZEND_ARG_PHP_TYPE_INFO(pass_by_ref, name, php_type, allow_null) { {#name}, sizeof(#name)-1, {NULL}, 0, php_type, allow_null, pass_by_ref, 0, 0 },
</code>
  - **Reflection**: ReflectionParameter class:
    - Added:
      - isInt()
      - isDouble()
      - isBool()
      - isString()
      - isObject()
      - isResource()



==== Examples ====

=== With default parameter value ===
<code php>
function test(integer $value = '1') {
}
// Fatal error: Default value for parameters with integer type hint can only be the exact type or NULL
</code>

=== integer / int ===
<code php>
function test(integer $value) {
}

test(1);
test(-1);
test("1."); 
// Catchable fatal error: Argument 1 passed to test() must be of the type integer, string given ...
</code>

=== double / float / real ===
<code php>
function test(double $value) {
}

test(1.1);
test(.1);
test("1."); // Catchable fatal error: Argument 1 passed to test() must be of the type double, string given
</code>

=== bool / boolean ===
<code php>
function test(bool $value = true) {
}

test(false);
test(0); // Catchable fatal error: Argument 1 passed to test() must be of the type boolean, null given
</code>

=== resource ===
<code php>
function test(resource $value) {
}

test(fopen(__FILE__, 'r'));
test(NULL); // Catchable fatal error: Argument 1 passed to test() must be of the type resource, null given
</code>

=== object ===
<code php>
function test(object $value) {
}

test(new stdclass);
test(NULL); // Catchable fatal error: Argument 1 passed to test() must be of the type object, null given
</code>



===== Patches & tests =====

  - Return value type hint: http://felipe.ath.cx/diff/return_type_hint.diff
  - Parameter type hint: http://felipe.ath.cx/diff/param_type_hint.diff
  - Tests: http://felipe.ath.cx/diff/tests/