====== Request for Comments: callable type hint ======
  * Version: 1.0
  * Date: 2011-06-07
  * Author: Hannes Magnusson <bjori@php.net>
  * Status: Implemented in PHP 5.4
  * First Published at: http://wiki.php.net/rfc/callable


===== The problem =====


Frameworks have started to adopt Closures for callbacks, utilizing the 'Closure' typehint.
That has an unfortunate sideeffect of requiring already-existing-methods to be wrapped into a closure calling that method.
Additionally, the PHP documentation on closures indicates that the "Closure" class is considered an implementation detail, and may be subject to change in the future -- which means that typehinting on Closure may break in the future.

===== The solution =====

Introducing a callable typehint.

The typehint would allow a string with a function name, an array composed of classname/obj+methodname, and a closure.

===== Callable vs Callback =====

callback is callable, the opposite could not be true. A string, or a closure, is callable, but the string is not a callback.

The documentations already use `array` hinting when a function expects an array, even though it does not type hint on it.
The documentations already use `callable` hiting when a function expects a callable instance, even though it does not type hint on it.

Furthermore we already have a function called is_callable(), and this new feature will share its implementation.

Introducing a different name (i..e callback) will therefore only create more inconsistencies and confusion.

The callable typehint reuses the is_callable() logic.

===== Initialization =====

Only null initialize is allowed, making it consistent with classname typehinting.



===== Patch =====

  * http://php.markmail.org/download.xqy?id=ya3f6abxw2u6asdp&number=1

===== Previous discussions =====

  * http://php.markmail.org/message/gdas65h3im52sleg
  * http://php.markmail.org/message/ya3f6abxw2u6asdp

== Discussion summary ==


  * The only arguments against the idea came from Stas, [[http://php.markmail.org/message/hhdjdfo3o34mcj2t?q=callable|making the argument]];
    * 'callable' is a data structure not unlike 'balanced binary tree' and 'readable file', and none of them make sense have as a part of the language syntax. They belong in userspace. 
    * A "strict typing error" is hard to handle in user-space gracefully.
  * Everyone else seem to like the idea, so far.
  * As for the patch itself, Felipe pointed out that the patch is missing an method in ext/reflection to retrieve the typehint information.
  * Things to finalize:
    * Reflection support
    * Arginfo support


===== Changelog =====

  * June 7th 2011, Initial writeup
  * July 27th 2011, Added "callable vs callback" and "initialization" section