====== PHP RFC: __debugInfo() ======
  * Version: 1.1
  * Date: 2014-01-21
  * Author: Sara Golemon, pollita@php.net
  * Status: Accepted (implemented in 5.6)
  * First Published at: http://wiki.php.net/rfc/debug-info

===== Proposal =====

This RFC is for exposing the "get_debug_info" API already available to internal classes (written in C) to PHP classes via a magic method called <nowiki>__debugInfo()</nowiki>.

Example Usage:

  class File {
    // "Resource(stream)" isn't all that useful
    private $fp;
  
    // But all the stream meta data is
    public function __debugInfo() {
      return $this->fp ? stream_get_meta_data($fp) : [];
    }
  
    public function open($filename, $mode = 'r'){
      $this->fp = fopen($filename, $mode);
    }  
  }
  
  $f = new File;
  var_dump($f); // object(File)#1 { }
  $f->open('http://php.net');
  var_dump($f);
  /*
  object(File)#1 {
    ["wrapper_type"]=>
    string(4) "http"
    ["stream_type"]=>
    string(10) "tcp_socket"
    etc...
  */

===== Backward Incompatible Changes =====

Double underscore is a reserved namespace, so any classes which happen to implement this are the ones which need to change.

===== Impact to Existing Extensions =====

Existing fallback behavior for internal classes not overriding get_debug_info is preserved via chaining to get_properties when no <nowiki>__debugInfo</nowiki> function is defined.

===== Proposed PHP Version(s) =====

5.next

===== Alternates under discussion =====

  * Rather than use <nowiki>__debugInfo() as the whole property info result, either merge it with the properties table or stuff it into a "__debugInfo"</nowiki> property and return it with the full properties table.

IMO, this takes control away from the user and removes a particularly useful reason for having the <nowiki>__debugInfo() magic method in the first place.  Consider an object which points at itself (or more likely, another object which points back at the original).  This normally results in a recursive loop.  This is detected by the var_dump() routine, but only after a couple cycles.  A more intelligent __debugInfo() output could avoid any iterations of the loop.</nowiki>

===== Potential expansions of scope =====

  * Add ReflectionObject::getDebugInfo() to return the result of zend_object_handlers->get_debug_info as an array of ReflectionParameter objects

===== Revision History =====

  * 1.1 (2014-01-22) - Changed name from <nowiki>__debug_info to __debugInfo</nowiki> and added alternates/expansion headings
  * 1.0 (2014-01-21) - Initial Revision

===== Vote 1 =====

  * Vote start: 2014/02/03
  * Vote end: 2014/02/17

Vote [YES] to merge the <nowiki>__debugInfo()</nowiki> patch.  See Vote 2 for options on what name it will have.

<doodle title="Merge ___debugInfo()" auth="pollita" voteType="single" closed="true">
   * Yes (5.6)
   * Yes (5.7)
   * No
</doodle>

===== Vote 2 =====

  * Vote start: 2014/02/03
  * Vote end: 2014/02/17

If Vote 1 passes, what should the userland magic method be called?

<doodle title="Name ___debugInfo()" auth="pollita" voteType="single" closed="true">
   * __debugInfo()
   * __debug()
</doodle>

===== Implementation =====

https://github.com/sgolemon/php-src/compare/debug.info