rfc:debug-info

PHP RFC: __debugInfo()

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.

Merge ___debugInfo()
Real name Yes (5.6) Yes (5.7) No
aharvey (aharvey)   
ajf (ajf)   
bwoebi (bwoebi)   
chobieeee (chobieeee)   
chregu (chregu)   
dsp (dsp)   
fa (fa)   
googleguy (googleguy)   
indeyets (indeyets)   
jpauli (jpauli)   
jwage (jwage)   
kassner (kassner)   
krakjoe (krakjoe)   
levim (levim)   
lstrojny (lstrojny)   
malukenho (malukenho)   
mbeccati (mbeccati)   
peehaa (peehaa)   
pollita (pollita)   
rdlowrey (rdlowrey)   
remi (remi)   
salathe (salathe)   
sebastian (sebastian)   
stas (stas)   
treffynnon (treffynnon)   
willfitch (willfitch)   
yohgaki (yohgaki)   
Final result: 23 1 3
This poll has been 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?

Name ___debugInfo()
Real name __debugInfo() __debug()
aharvey (aharvey)  
ajf (ajf)  
bwoebi (bwoebi)  
chobieeee (chobieeee)  
chregu (chregu)  
dsp (dsp)  
fa (fa)  
indeyets (indeyets)  
jpauli (jpauli)  
krakjoe (krakjoe)  
levim (levim)  
lstrojny (lstrojny)  
malukenho (malukenho)  
mariuz (mariuz)  
mbeccati (mbeccati)  
nikic (nikic)  
pollita (pollita)  
rdlowrey (rdlowrey)  
remi (remi)  
salathe (salathe)  
sebastian (sebastian)  
stas (stas)  
willfitch (willfitch)  
yohgaki (yohgaki)  
Final result: 23 1
This poll has been closed.

Implementation

rfc/debug-info.txt · Last modified: 2014/03/06 15:23 by danielc