__debugInfo() magic method View as Markdown

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 __debugInfo().

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 __debugInfo function is defined.

Proposed PHP Version(s)

5.next

Alternates under discussion

• Rather than use __debugInfo() as the whole property info result, either merge it with the properties table or stuff it into a "__debugInfo" 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 __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.

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 __debug_info to __debugInfo 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 __debugInfo() patch. See Vote 2 for options on what name it will have.

Vote: Merge ___debugInfo() — Yes (5.6): 23 · Yes (5.7): 1 · No: 3 (closed)

Vote 2

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

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

Vote: Name ___debugInfo() — __debugInfo(): 23 · __debug(): 1 (closed)

Implementation

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