PHP RFC: phpdbg

• Version: 0.1
• Date: 2013-11-21
• Author: Joe Watkins krakjoe@php.net
• Author: Felipe Pena felipe@php.net
• Status: Voting
• First Published at: http://wiki.php.net/rfc/phpdbg

phpdbg is a gdb-like PHP debugger. Implemented as a SAPI module, it is intended to be installed alongside CLI and other SAPI modules.

Like CLI, and gdb, phpdbg is an executable intended to be executed at the terminal in an interactive way.

Much power is provided to the user in order to control and inspect execution as it occurs, breaking execution is supported in the following ways:

phpdbg> break [file] test.php:1
phpdbg> b [F] test.php:1
Will break execution on line 1 of test.php

phpdbg> break [func] my_function
phpdbg> b [f] my_function
Will break execution on entry to my_function

phpdbg> break [method] \my\class::method
phpdbg> b [m] \my\class::method
Will break execution on entry to \my\class::method

phpdbg> break [address] 0x7ff68f570e08
phpdbg> b [a] 0x7ff68f570e08
Will break at the opline with the address provided

phpdbg> break [lineno] 200
phpdbg> b [l] 200
Will break at line 200 of the currently executing file

phpdbg> break on ($expression == true)
phpdbg> b on ($expression == true)
Will break when the condition evaluates to true

phpdbg> break at phpdbg::isGreat if ($condition)
phpdbg> b at phpdbg::isGreat if ($condition)
Will break in phpdbg::isGreat as specified, can take a function/method/file:line

phpdbg> break op ZEND_ADD
phpdbg> b O ZEND_ADD
Will break on every occurence of the opcode provided

phpdbg> break del 1
phpdbg> b d 1

phpdbg has a step-through-each-opcode mode, whereby the interactive console is presented to the user after the execution of each individual opcode, and a few useful commands besides.

Disassembly of code is supported, providing tooling to inspect the internal structure of code in an effort to be a useful tool for pecl devs and php programmers.

  phpdbg> print class phpdbg
  [User Class: phpdbg]
  Methods (1):
      L9-13 phpdbg::isGreat() /usr/src/phpdbg/test.php
              L9      0x7f41937db810 ZEND_RECV_INIT                                                           $greeting           
              L11     0x7f41937db840 ZEND_SEND_VAL                  C1                   <unused>             <unused>            
              L11     0x7f41937db870 ZEND_SEND_VAL                  C2                   <unused>             <unused>            
              L11     0x7f41937db8a0 ZEND_SEND_VAR                  $greeting            <unused>             <unused>            
              L11     0x7f41937db8d0 ZEND_DO_FCALL                  C3                   <unused>             @0                  
              L12     0x7f41937db900 ZEND_RETURN                    $this                <unused>             <unused>
              
  phpdbg> info literal
  [Literal Constants in /usr/src/phpdbg/test.php (23)]
  |-------- C0 -------> [%s/web-bootstrap.php]
  |-------- C1 -------> [/usr/src/phpdbg/test.php]
  |-------- C2 -------> [dirname]
  |-------- C3 -------> [sprintf]
  |-------- C4 -------> [php://stdout]
  |-------- C5 -------> [w+]
  |-------- C6 -------> [fopen]
  |-------- C9 -------> [phpdbg]
  |-------- C10 -------> [phpdbg]
  |-------- C11 -------> [isGreat]
  |-------- C12 -------> [isGreat]
  |-------- C13 -------> [isgreat]
  |-------- C14 -------> [PHP Rocks !!]
  |-------- C15 -------> [var_dump]
  |-------- C16 -------> [1]
  |-------- C17 -------> [test]
  |-------- C18 -------> [1]
  |-------- C19 -------> [it works!
  ]
  |-------- C20 -------> [_SERVER]
  |-------- C21 -------> [var_dump]
  |-------- C23 -------> [1]

Many more commands provide access to just about everything ...

Remote Debugging:

Remote Debugging is supported in unix by way of a protocol-free inetd like service, the Java client displayed is distributed with phpdbg, and is at least as comfortable as the command line, more so for some perhaps.

Much more information and documentation can be found on http://phpdbg.com

phpdbg could (should) be included in the distribution in the /sapi folder, it makes no changes to any other SAPI.

The reason it should be included is, as a SAPI module, it is quite difficult to distribute phpdbg to a large audience.

The debugging environment is self contained within that executable, without requiring changes to any other binaries or libraries, with no need to share configurations it's installation is non-intrusive.

phpdbg can be merged into 5.6+ as it has already been patched, 5.5 would require a small change ... that boat has probably sailed ...

Nothing

5.6

Note: it would be nice if 5.5 could get phpdbg too, but requires a patch that might cause ABI incompatibiilty issues caused by new exports.

None

Opcache requires the following patch to support phpdbg: http://pastebin.com/caPW9tVx

Note: that list should be a blacklist, it's more forward compatible, the assumption that it doesn't work with new SAPI's is illogical.

This limitation, which may have an affect on userland software where php_sapi_name() is used, can be mitigated using the -S option to override the SAPI name.

Note that, overriding the SAPI name only changes the name as reported to the rest of the engine; it does not use any of the structures from the SAPI requested

In phpdbg the constants:

1. PHPDBG_METHOD
2. PHPDBG_FUNC
3. PHPDBG_LINENO
4. PHPDBG_FILE

are registered, they are only available when executing in phpdbg

None

None

All

No actual changes were required, a patch to export more of the Zend API was already merged into 5.6+

I'd quite like to introduce the same patch to 5.5

http://git.php.net/?p=php-src.git;a=commit;h=a0e3cb08e616a67d3eaddef665e27566a774ef78

This patch is only required for a build on Windows; where it requires exports because of the build system.

The phpdbg codebase is compatible with 5.4+

If phpdbg is bundled, it means that it must follow the release cycle of PHP itself; we're not sure if this will create any problem - every other SAPI manages it, and there's no particular reason to think this is any more complex. Tyrael had the rather clever idea that should the need arise for a different release cycle, phpdbg can have its build process changes such that the base SAPI is bundled and the functionality it provides is contained in a Zend Extension, thus freeing phpdbg from PHP's release cycle.

This is definitely the way we will go, should the need arise, however, we would prefer not to have to disturb the build process or code base unnecessarily.

Simple

http://phpdbg.com http://github.com/krakjoe/phpdbg

N/A

N/A

Distribute phpdbg with PHP5.6+
Real name	Yes	No
aharvey (aharvey)
ajf (ajf)
bwoebi (bwoebi)
chobieeee (chobieeee)
datibbaw (datibbaw)
daverandom (daverandom)
davey (davey)
dm (dm)
ericsten (ericsten)
fa (fa)
felipe (felipe)
jpauli (jpauli)
juliens (juliens)
kalle (kalle)
krakjoe (krakjoe)
laruence (laruence)
levim (levim)
lstrojny (lstrojny)
mbeccati (mbeccati)
mfonda (mfonda)
mike (mike)
mj (mj)
nikic (nikic)
pajoye (pajoye)
patrickallaert (patrickallaert)
Paul White (vascowhite)
peehaa (peehaa)
philstu (philstu)
rdlowrey (rdlowrey)
reeze (reeze)
remi (remi)
salathe (salathe)
sebastian (sebastian)
shm (shm)
stas (stas)
thorstenr (thorstenr)
tyrael (tyrael)
yohgaki (yohgaki)
zeev (zeev)
zhangzhenyu (zhangzhenyu)
Final result:	40	0
This poll has been closed.

Voting commenced December 11th 2013, closing December 18th 2013.