This is an old revision of the document!
PHP RFC: phpdbg
- Version: 0.1
- Date: 2013-11-21
- Author: Joe Watkins krakjoe@php.net
- Author: Felipe Pena felipe@php.net
- Status: Under Discussion
- First Published at: http://wiki.php.net/rfc/phpdbg
Introduction
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 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
Proposal
Felipe Pena and I have recently developed a debugging platform for PHP, development continues ...
It could (should) be included in the distribution in the /sapi folder, it makes no changes to any other SAPI.
There will be a great benefit to everyone in having a debugger distributed with PHP.
Usually, the content of an RFC is used for the basis for documentation of a feature if it is merged;
I ask in this case we make an exception, documenting the use of a debugger is a huge task, not suited for these pages. We will of course write documentation, lots of it, in the manual should it be merged, in the mean time the brief documentation we have written is on phpdbg.com and will remain there whatever happens.
This is a brief proposal to get the conversation started, I am busy ... anything you might want to know about the software can be read in source or on the phpdbg website.
If anything requires clarification, find me in the usual places ...
Backward Incompatible Changes
Nothing
Proposed PHP Version(s)
ASAP
SAPIs Impacted
None
Impact to Existing Extensions
None
New Constants
In phpdbg the constants:
- PHPDBG_METHOD
- PHPDBG_FUNC
- PHPDBG_LINENO
- PHPDBG_FILE
are registered, they are only available when executing in phpdbg
php.ini Defaults
None
Open Issues
None
Unaffected PHP Functionality
All
Changes to PHP
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+
Proposed Voting Choices
Simple
Implementation
References
N/A
Rejected Features
N/A