mirror of
https://github.com/php/php-src.git
synced 2025-08-19 17:04:47 +02:00
ebdfef807a
* I've added more content to the help to expand desciption for new-to-phpdbg developers. * After a code review of the new routines that I've added to the help module, I've decided that the implementation was unnecessarily convolved and that Keep-It-Simple-Stupid would be more understandable, maintainable and have no material performance hit.
939 lines
35 KiB
C
939 lines
35 KiB
C
/*
|
||
+----------------------------------------------------------------------+
|
||
| PHP Version 5 |
|
||
+----------------------------------------------------------------------+
|
||
| Copyright (c) 1997-2014 The PHP Group |
|
||
+----------------------------------------------------------------------+
|
||
| This source file is subject to version 3.01 of the PHP license, |
|
||
| that is bundled with this package in the file LICENSE, and is |
|
||
| available through the world-wide-web at the following url: |
|
||
| http://www.php.net/license/3_01.txt |
|
||
| If you did not receive a copy of the PHP license and are unable to |
|
||
| obtain it through the world-wide-web, please send a note to |
|
||
| license@php.net so we can mail you a copy immediately. |
|
||
+----------------------------------------------------------------------+
|
||
| Authors: Felipe Pena <felipe@php.net> |
|
||
| Authors: Joe Watkins <joe.watkins@live.co.uk> |
|
||
| Authors: Bob Weinand <bwoebi@php.net> |
|
||
| Authors: Terry Ellison <terry@ellisons.org.uk> |
|
||
+----------------------------------------------------------------------+
|
||
*/
|
||
|
||
#include "phpdbg.h"
|
||
#include "phpdbg_help.h"
|
||
#include "phpdbg_prompt.h"
|
||
#include "zend.h"
|
||
|
||
ZEND_EXTERN_MODULE_GLOBALS(phpdbg);
|
||
|
||
/* {{{ Commands Table */
|
||
#define PHPDBG_COMMAND_HELP_D(name, tip, alias, action) \
|
||
{PHPDBG_STRL(#name), tip, sizeof(tip)-1, alias, action, NULL, 0}
|
||
|
||
const phpdbg_command_t phpdbg_help_commands[] = {
|
||
PHPDBG_COMMAND_HELP_D(aliases, "show alias list", 'a', phpdbg_do_help_aliases),
|
||
PHPDBG_COMMAND_HELP_D(options, "command line options", 0, NULL),
|
||
PHPDBG_COMMAND_HELP_D(overview, "help overview", 0, NULL),
|
||
PHPDBG_COMMAND_HELP_D(phpdbginit, "phpdbginit file format", 0, NULL),
|
||
PHPDBG_COMMAND_HELP_D(syntax, "syntax overview", 0, NULL),
|
||
PHPDBG_END_COMMAND
|
||
}; /* }}} */
|
||
|
||
/* {{{ pretty_print. Formatting escapes and wrapping text in a string before printing it. */
|
||
void pretty_print(char *text TSRMLS_DC)
|
||
{
|
||
char *new, *p, *q;
|
||
|
||
const char *prompt_escape = phpdbg_get_prompt(TSRMLS_C);
|
||
unsigned int prompt_escape_len = strlen(prompt_escape);
|
||
unsigned int prompt_len = strlen(PHPDBG_G(prompt)[0]);
|
||
|
||
const char *bold_on_escape = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[1m" : "";
|
||
const char *bold_off_escape = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[0m" : "";
|
||
unsigned int bold_escape_len = strlen(bold_on_escape);
|
||
|
||
unsigned int term_width = phpdbg_get_terminal_width(TSRMLS_C);
|
||
unsigned int size = 0;
|
||
|
||
int in_bold = 0;
|
||
|
||
char *last_new_blank = NULL; /* position in new buffer of last blank char */
|
||
unsigned int last_blank_count = 0; /* printable char offset of last blank char */
|
||
unsigned int line_count = 0; /* number printable chars on current line */
|
||
|
||
/* First pass calculates a safe size for the pretty print version */
|
||
for (p = text; *p; p++) {
|
||
if ( UNEXPECTED(p[0] == '*') && p[1] == '*' ) {
|
||
size += bold_escape_len - 2;
|
||
p++;
|
||
} else if ( UNEXPECTED(p[0] == '$') && p[1] == 'P' ) {
|
||
size += prompt_escape_len - 2;
|
||
p++;
|
||
} else if ( UNEXPECTED(p[0] == '\\') ) {
|
||
p++;
|
||
}
|
||
}
|
||
size += (p-text)+1;
|
||
|
||
new = emalloc(size);
|
||
/*
|
||
* Second pass substitutes the bold and prompt escape sequences and line wrap
|
||
*
|
||
* ** toggles bold on and off if PHPDBG_IS_COLOURED flag is set
|
||
* $P substitutes the prompt sequence
|
||
* Lines are wrapped by replacing the last blank with a CR before <term width>
|
||
* characters. (This defaults to 100 if the width can't be detected). In the
|
||
* pathelogical case where no blanks are found, then the wrap occurs at the
|
||
* first blank.
|
||
*/
|
||
for (p = text, q = new; *p; p++) {
|
||
if ( UNEXPECTED(*p == ' ') ) {
|
||
last_new_blank = q;
|
||
last_blank_count = line_count++;
|
||
*q++ = ' ';
|
||
} else if ( UNEXPECTED(*p == '\n') ) {
|
||
last_new_blank = NULL;
|
||
*q++ = *p;
|
||
last_blank_count = 0;
|
||
line_count = 0;
|
||
} else if ( UNEXPECTED(p[0] == '*') && p[1] == '*' ) {
|
||
if (bold_escape_len) {
|
||
in_bold = !in_bold;
|
||
memcpy (q, in_bold ? bold_on_escape : bold_off_escape, bold_escape_len);
|
||
q += bold_escape_len;
|
||
/* bold on/off has zero print width so line count is unchanged */
|
||
}
|
||
p++;
|
||
} else if ( UNEXPECTED(p[0] == '$') && p[1] == 'P' ) {
|
||
memcpy (q, prompt_escape, prompt_escape_len);
|
||
q += prompt_escape_len;
|
||
line_count += prompt_len;
|
||
p++;
|
||
} else if ( UNEXPECTED(p[0] == '\\') ) {
|
||
p++;
|
||
*q++ = *p;
|
||
line_count++;
|
||
} else {
|
||
*q++ = *p;
|
||
line_count++;
|
||
}
|
||
|
||
if (UNEXPECTED(line_count>=term_width) && last_new_blank) {
|
||
*last_new_blank = '\n';
|
||
last_new_blank = NULL;
|
||
line_count -= last_blank_count;
|
||
last_blank_count = 0;
|
||
}
|
||
}
|
||
*q++ = '\0';
|
||
|
||
if ((q-new)>size) {
|
||
phpdbg_error("Output overrun of %lu bytes", ((q-new) - size));
|
||
}
|
||
|
||
(void) phpdbg_write("%s\n", new);
|
||
efree(new);
|
||
} /* }}} */
|
||
|
||
/* {{{ summary_print. Print a summary line giving, the command, its alias and tip */
|
||
void summary_print(phpdbg_command_t const * const cmd TSRMLS_DC)
|
||
{
|
||
char *summary;
|
||
spprintf(&summary, 0, "Command: **%s** Alias: **%c** **%s**\n",
|
||
cmd->name, cmd->alias, cmd->tip);
|
||
pretty_print(summary TSRMLS_CC);
|
||
efree(summary);
|
||
}
|
||
|
||
/* {{{ get_help. Retries and formats text from the phpdbg help text table */
|
||
static char *get_help(const char * const key TSRMLS_DC)
|
||
{
|
||
phpdbg_help_text_t *p;
|
||
|
||
/* Note that phpdbg_help_text is not assumed to be collated in key order. This is an
|
||
inconvience that means that help can't be logically grouped Not worth
|
||
the savings */
|
||
|
||
for (p = phpdbg_help_text; p->key; p++) {
|
||
if (!strcmp(p->key, key)) {
|
||
return p->text;
|
||
}
|
||
}
|
||
return ""; /* return empty string to denote no match found */
|
||
} /* }}} */
|
||
|
||
/* {{{ get_command. Return number of matching commands from a command table.
|
||
* Unlike the command parser, the help search is sloppy that is partial matches can occur
|
||
* * Any single character key is taken as an alias.
|
||
* * Other keys are matched again the table on the first len characters.
|
||
* * This means that non-unique keys can generate multiple matches.
|
||
* * The first matching command is returned as an OUT parameter. *
|
||
* The rationale here is to assist users in finding help on commands. So unique matches
|
||
* will be used to generate a help message but non-unique one will be used to list alternatives.
|
||
*/
|
||
static int get_command(
|
||
const char *key, size_t len, /* pointer and length of key */
|
||
phpdbg_command_t const **command, /* address of first matching command */
|
||
phpdbg_command_t const * const commands /* command table to be scanned */
|
||
TSRMLS_DC)
|
||
{
|
||
const phpdbg_command_t *c;
|
||
unsigned int num_matches = 0;
|
||
|
||
if (len == 1) {
|
||
for (c=commands; c->name; c++) {
|
||
if (c->alias == key[0]) {
|
||
num_matches++;
|
||
if ( num_matches == 1 && command) {
|
||
*command = c;
|
||
}
|
||
}
|
||
}
|
||
} else {
|
||
for (c=commands; c->name; c++) {
|
||
if (!strncmp(c->name, key, len)) {
|
||
++num_matches;
|
||
if ( num_matches == 1 && command) {
|
||
*command = c;
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
return num_matches;
|
||
|
||
} /* }}} */
|
||
|
||
PHPDBG_COMMAND(help) /* {{{ */
|
||
{
|
||
phpdbg_command_t const *cmd;
|
||
int n;
|
||
|
||
if (param->type == EMPTY_PARAM) {
|
||
pretty_print(get_help("overview!" TSRMLS_CC) TSRMLS_CC);
|
||
return SUCCESS;
|
||
}
|
||
|
||
if (param->type == STR_PARAM) {
|
||
n = get_command( param->str, param->len, &cmd, phpdbg_prompt_commands TSRMLS_CC);
|
||
|
||
if (n==1) {
|
||
summary_print(cmd TSRMLS_CC);
|
||
pretty_print(get_help(cmd->name TSRMLS_CC) TSRMLS_CC);
|
||
return SUCCESS;
|
||
|
||
} else if (n>1) {
|
||
if (param->len > 1) {
|
||
for (cmd=phpdbg_prompt_commands; cmd->name; cmd++) {
|
||
if (!strncmp(cmd->name, param->str, param->len)) {
|
||
summary_print(cmd TSRMLS_CC);
|
||
}
|
||
}
|
||
pretty_print(get_help("duplicate!" TSRMLS_CC) TSRMLS_CC);
|
||
return SUCCESS;
|
||
} else {
|
||
phpdbg_error("Internal help error, non-unique alias \"%c\"", param->str[0]);
|
||
return FAILURE;
|
||
}
|
||
|
||
} else { /* no prompt command found so try help topic */
|
||
n = get_command( param->str, param->len, &cmd, phpdbg_help_commands TSRMLS_CC);
|
||
|
||
if (n>0) {
|
||
if (cmd->alias == 'a') { /* help aliases executes a canned routine */
|
||
return cmd->handler(param, NULL TSRMLS_CC);
|
||
} else {
|
||
pretty_print(get_help(cmd->name TSRMLS_CC) TSRMLS_CC);
|
||
return SUCCESS;
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
phpdbg_error("No help can be found for the subject \"%s\"", param->str);
|
||
return FAILURE;
|
||
|
||
} /* }}} */
|
||
|
||
PHPDBG_HELP(aliases) /* {{{ */
|
||
{
|
||
const phpdbg_command_t *c, *c_sub;
|
||
int len;
|
||
|
||
/* Print out aliases for all commands except help as this one comes last */
|
||
phpdbg_writeln("Below are the aliased, short versions of all supported commands");
|
||
for(c = phpdbg_prompt_commands; c->name; c++) {
|
||
if (c->alias && c->alias != 'h') {
|
||
phpdbg_writeln(" %c %-20s %s", c->alias, c->name, c->tip);
|
||
if (c->subs) {
|
||
len = 20 - 1 - c->name_len;
|
||
for(c_sub = c->subs; c_sub->alias; c_sub++) {
|
||
if (c_sub->alias) {
|
||
phpdbg_writeln(" %c %c %s %-*s %s",
|
||
c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
/* Print out aliases for help as this one comes last, with the added text on how aliases are used */
|
||
(void) get_command( "h", 1, & c, phpdbg_prompt_commands TSRMLS_CC);
|
||
/* In function ‘phpdbg_do_help_aliases’:
|
||
274:2: warning: passing argument 3 of ‘get_command’ from incompatible pointer type [enabled by default]
|
||
180:12: note: expected ‘struct phpdbg_command_t **’ but argument is of type ‘const struct phpdbg_command_t **’ */
|
||
phpdbg_writeln(" %c %-20s %s\n", c->alias, c->name, c->tip);
|
||
|
||
len = 20 - 1 - c->name_len;
|
||
for(c_sub = c->subs; c_sub->alias; c_sub++) {
|
||
if (c_sub->alias) {
|
||
phpdbg_writeln(" %c %c %s %-*s %s",
|
||
c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
|
||
}
|
||
}
|
||
|
||
pretty_print(get_help("aliases!" TSRMLS_CC) TSRMLS_CC);
|
||
return SUCCESS;
|
||
} /* }}} */
|
||
|
||
|
||
/* {{{ Help Text Table
|
||
* Contains help text entries keyed by a lowercase ascii key.
|
||
* Text is in ascii and enriched by a simple markup:
|
||
* ** toggles bold font emphasis.
|
||
* $P insert an bold phpdbg> prompt.
|
||
* \ escapes the following character. Note that this is itself escaped inside string
|
||
* constants so \\\\ is required to output a single \ e.g. as in namespace names.
|
||
*
|
||
* Text will be wrapped according to the STDOUT terminal width, so paragraphs are
|
||
* flowed using the C stringizing and the CR definition. Also note that entries
|
||
* are collated in alphabetic order on key.
|
||
*
|
||
* Also note the convention that help text not directly referenceable as a help param
|
||
* has a key ending in !
|
||
*/
|
||
#define CR "\n"
|
||
phpdbg_help_text_t phpdbg_help_text[] = {
|
||
|
||
/******************************** General Help Topics ********************************/
|
||
{"overview!", CR
|
||
"**phpdbg** is a lightweight, powerful and easy to use debugging platform for PHP5.4+" CR
|
||
"It supports the following commands:" CR CR
|
||
|
||
"**Information**" CR
|
||
" **list** list PHP source" CR
|
||
" **info** displays information on the debug session" CR
|
||
" **help** provide help on a topic" CR
|
||
" **print** print argument " CR
|
||
" **frame** select a stack frame and print a stack frame summary" CR CR
|
||
|
||
"**Compilation**" CR
|
||
" **compile** compile a PHP source" CR CR
|
||
|
||
"**Starting and Stopping Execution**" CR
|
||
" **exec** set execution context" CR
|
||
" **clean** clean the execution environment" CR
|
||
" **run** attempt execution" CR
|
||
" **eval** evaluate some code" CR
|
||
" **step** Enable or disable per opcode stepping mode" CR
|
||
" **next** continue execution" CR
|
||
" **until** continue execution up to the given location" CR
|
||
" **finish** continue up to end of the current execution frame" CR
|
||
" **leave** continue up to end of the current execution frame and halt after the calling instruction" CR
|
||
" **break** set a breakpoint at the specified target" CR
|
||
" **clear** clear one or all breakpoints" CR CR
|
||
|
||
"**Miscellaneous**" CR
|
||
" **quiet** silence some output" CR
|
||
" **set** set the phpdbg configuration" CR
|
||
" **source** execute a phpdbginit script" CR
|
||
" **register** register a phpdbginit function as a command alias" CR
|
||
" **shell** shell a command" CR
|
||
" **quit** exit phpdbg" CR CR
|
||
|
||
"Type **help <command>** or (**help alias**) to get detailed help on any of the above commands, "
|
||
"for example **help list** or **h l**. Note that help will also match partial commands if unique "
|
||
"(and list out options if not unique), so **help clea** will give help on the **clean** command, "
|
||
"but **help cl** will list the summary for **clean** and **clear**." CR CR
|
||
|
||
"Type **help aliases** to show a full alias list, including any registered phpdginit functions" CR
|
||
"Type **help syntax** for a general introduction to the command syntax." CR
|
||
"Type **help options** for a list of phpdbg command line options." CR
|
||
"Type **help phpdbginit** to show how to customise the debugger environment."
|
||
},
|
||
{"options", CR
|
||
"Below are the command line options supported by phpdbg" CR CR
|
||
/* note the extra 4 space index in because of the extra **** */
|
||
"**Command Line Options and Flags**" CR
|
||
" **Option** **Example Argument** **Description**" CR
|
||
" **-c** **-c**/my/php.ini Set php.ini file to load" CR
|
||
" **-d** **-d**memory_limit=4G Set a php.ini directive" CR
|
||
" **-n** Disable default php.ini" CR
|
||
" **-q** Supress welcome banner" CR
|
||
" **-e** **-e**mytest.php Set execution context" CR
|
||
" **-v** Enable oplog output" CR
|
||
" **-s** Enable stepping" CR
|
||
" **-b** Disable colour" CR
|
||
" **-i** **-i**my.init Set .phpdbginit file" CR
|
||
" **-I** Ignore default .phpdbginit" CR
|
||
" **-O** **-O**my.oplog Sets oplog output file" CR
|
||
" **-r** Run execution context" CR
|
||
" **-rr** Run execution context and quit after execution" CR
|
||
" **-E** Enable step through eval, careful!" CR
|
||
" **-S** **-S**cli Override SAPI name, careful!" CR
|
||
" **-l** **-l**4000 Setup remote console ports" CR
|
||
" **-a** **-a**192.168.0.3 Setup remote console bind address" CR
|
||
" **-V** Print version number" CR CR
|
||
|
||
"**Remote Console Mode**" CR CR
|
||
|
||
"This mode is enabled by specifying the **-a** option. Phpdbg will bind only to the loopback "
|
||
"interface by default, and this can only be overridden by explicitly setting the remote console "
|
||
"bind address using the **-a** option. If **-a** is specied without an argument, then phpdbg "
|
||
"will bind to all available interfaces. You should be aware of the security implications of "
|
||
"doing this, so measures should be taken to secure this service if bound to a publicly accessible "
|
||
"interface/port." CR CR
|
||
|
||
"Specify both stdin and stdout with -lstdin/stdout; by default stdout is stdin * 2."
|
||
},
|
||
|
||
{"phpdbginit", CR
|
||
"Phpdgb uses an debugger script file to initialize the debugger context. By default, phpdbg looks "
|
||
"for the file named **.phpdbginit** in the current working directory. This location can be "
|
||
"overridden on the command line using the **-i** switch (see **help options** for a more "
|
||
"details)." CR CR
|
||
|
||
"Debugger scripts can also be executed using the **script** command." CR CR
|
||
|
||
"A script file can contain a sequence of valid debugger commands, comments and embedded PHP "
|
||
"code. " CR CR
|
||
|
||
"Comment lines are prefixed by the **#** character. Note that comments are only allowed in script "
|
||
"files and not in interactive sessions." CR CR
|
||
|
||
"PHP code is delimited by the start and end escape tags **<:** and **:>**. PHP code can be used "
|
||
"to define application context for a debugging session and also to extend the debugger by defining "
|
||
"and **register** PHP functions as new commands." CR CR
|
||
|
||
"Also note that executing a **clear** command will cause the current **phpdbginit** to be reparsed "
|
||
"/ reloaded."
|
||
},
|
||
|
||
{"syntax", CR
|
||
"All **phpdbg** commands are case sensitive. Commands start with a keyword, and some keywords "
|
||
"(**break**, **info**, **set**, **print** and **list**) may include a subcommand keyword. All "
|
||
"keywords have a single letter alias (most lowercase, some uppercase) that may be used instead "
|
||
"of spelling out the keyword in full. Note that keywords cannot be abbreviated other than by "
|
||
"substitution by the alias." CR CR
|
||
|
||
"Some commands take one or more optional arguments which are interpreted in the context of the "
|
||
"command. In some cases the format of the argument enables the secondard keyword to be omitted." CR CR
|
||
|
||
"Type **help** for an overview of all commands and type **help <command>** to get detailed help "
|
||
"on any specific command." CR CR
|
||
|
||
"**Valid Examples**" CR CR
|
||
|
||
" $P quit" CR
|
||
" $P q" CR
|
||
" Quit the debugger" CR CR
|
||
|
||
" $P eval $total[2]" CR
|
||
" $P E $total[2]" CR
|
||
" Evaluate and print the variable $total[2] in the current stack frame" CR
|
||
" " CR
|
||
" $P break lineno 200" CR
|
||
" $P b my_source.php:200" CR
|
||
" Break at line 200 in the current source and in file **my_source.php**. " CR CR
|
||
|
||
" $P b A ClassX::get_args if $arg[0] == \"fred\"" CR
|
||
" $P b d 3" CR
|
||
" Break at ClassX::get_args() if $arg[0] == \"fred\" and delete breakpoint 3" CR CR
|
||
|
||
"**Examples of invalid commands**" CR
|
||
" $P break line 23" CR
|
||
" The command keyword is **lineno**; **line** is not allowed" CR CR
|
||
|
||
" $P NEXT" CR
|
||
" Commands are case sensitive. The keyword is **next**" CR CR
|
||
|
||
" $P s on" CR
|
||
" **step** takes an integer argument **0** or **1**; on/off is not allowed." CR CR
|
||
|
||
" $P #This is a comment" CR
|
||
" Comments introduced by the **#** character are only allowed in **phpdbginit** script files."
|
||
},
|
||
|
||
/******************************** Help Codicils ********************************/
|
||
{"aliases!", CR
|
||
"Note that aliases can be used for either command or sub-command keywords or both, so **info b** "
|
||
"is a synomyn for **info break** and **l func** for **list func**, etc." CR CR
|
||
|
||
"Note that help will also accept any alias as a parameter and provide help on that command, for example **h p** will provide help on the print command."
|
||
},
|
||
|
||
{"duplicate!", CR
|
||
"Parameter is not unique. For detailed help select help on one of the above commands."
|
||
},
|
||
|
||
/******************************** Help on Commands ********************************/
|
||
{"back",
|
||
"Provide a formatted backtrace using the standard debug_backtrace() functionality. An optional "
|
||
"unsigned integer argument specifying the maximum number of frames to be traced; if omitted then "
|
||
"a complete backtrace is given." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P back 5" CR
|
||
" $P t " CR
|
||
" " CR
|
||
"A backtrace can be executed at any time during execution."
|
||
},
|
||
|
||
{"break",
|
||
"Breakpoints can be set at a range of targets within the execution environment. Execution will "
|
||
"be paused if the program flow hits a breakpoint. The break target can be one of the following "
|
||
"types:" CR CR
|
||
|
||
" **Target** **Alias** **Purpose**" CR
|
||
" **file** **F** specify breakpoint by file:line" CR
|
||
" **lineno** **l** specify breakpoint by line of currently executing file" CR
|
||
" **func** **f** specify breakpoint by global function name" CR
|
||
" **method** **m** specify breakpoint by class::method" CR
|
||
" **address** **a** specify breakpoint by address" CR
|
||
" **op** **O** specify breakpoint by opcode" CR
|
||
" **on** **o** specify breakpoint by condition" CR
|
||
" **at** **A** specify breakpoint by location and condition" CR
|
||
" **del** **d** delete breakpoint by breakpoint identifier number" CR CR
|
||
|
||
"The syntax of the target argument is dependent on the target type and in the case of file, func "
|
||
"method, and address targets the target keyword or alias is optional and can be omitted." CR CR
|
||
|
||
"**Break on** takes a string argument which must be a valid PHP expression." CR CR
|
||
|
||
"**Break at** takes two arguments. The first is any valid target as per the file, lineno, func "
|
||
"and address types. The second is a valid PHP expression which will trigger the break in "
|
||
"execution, if evaluated as true in a boolean context at the specified target." CR CR
|
||
|
||
"Note that breakpoints can also be temporarily enabled and disabled by the set break command." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P break file test.php:100" CR
|
||
" $P b F test.php:100" CR
|
||
" $P b test.php:100" CR
|
||
" Break execution at line 100 of test.php" CR CR
|
||
|
||
" $P break lineno 200" CR
|
||
" $P b l 200" CR
|
||
" $P b 200" CR
|
||
" Break execution at line 200 of the currently PHP script file" CR CR
|
||
|
||
" $P break func \\\\mynamespace\\\\my_function" CR
|
||
" $P b f \\\\mynamespace\\\\my_function" CR
|
||
" $P b \\\\mynamespace\\\\my_function" CR
|
||
" Break execution on entry to \\\\mynamespace\\\\my_function" CR CR
|
||
|
||
" $P break method classX::method" CR
|
||
" $P b m classX::method" CR
|
||
" $P b classX::method" CR
|
||
" Break execution on entry to classX::method" CR CR
|
||
|
||
" $P break address 0x7ff68f570e08" CR
|
||
" $P b a 0x7ff68f570e08" CR
|
||
" $P b 0x7ff68f570e08" CR
|
||
" Break at the opline at the address 0x7ff68f570e08" CR CR
|
||
|
||
" $P break address my_function#14" CR
|
||
" $P b a my_function#14" CR
|
||
" $P b my_function#14" CR
|
||
" Break at the opline #14 of the function my_function" CR CR
|
||
|
||
" $P break address \\\\my\\\\class::method#2" CR
|
||
" $P b a \\\\my\\\\class::method#2" CR
|
||
" $P b \\\\my\\\\class::method#2" CR
|
||
" Break at the opline #2 of the method \\\\my\\\\class::method" CR CR
|
||
|
||
" $P break address test.php#3" CR
|
||
" $P b a test.php#3" CR
|
||
" Break at the opline #3 of test.php" CR CR
|
||
|
||
" $P break on $cnt > 10" CR
|
||
" $P b o $cnt > 10" CR
|
||
" Break when the condition ($cnt > 10) evaluates to true" CR CR
|
||
|
||
" $P break at phpdbg::isGreat if $opt == 'S'" CR
|
||
" Break at any opcode in phpdbg::isGreat when the condition ($opt == 'S') is true" CR CR
|
||
|
||
" $P break at test.php:20 if !isset($x)" CR
|
||
" Break at every opcode on line 20 of test.php when the condition evaluates to true" CR CR
|
||
|
||
" $P break op ZEND_ADD" CR
|
||
" $P b O ZEND_ADD" CR
|
||
" Break on any occurence of the opcode ZEND_ADD" CR CR
|
||
|
||
" $P break del 2" CR
|
||
" $P b d 2" CR
|
||
" Remove breakpoint 2" CR CR
|
||
|
||
"Note: Conditional breaks are costly in terms of runtime overhead. Use them only when required "
|
||
"as they significantly slow execution." CR CR
|
||
|
||
"Note: An address is only valid for the current compilation."
|
||
},
|
||
|
||
{"clean",
|
||
"Classes, constants or functions can only be declared once in PHP. You may experience errors "
|
||
"during a debug session if you attempt to recompile a PHP source. The clean command clears "
|
||
"the Zend runtime tables which holds the sets of compiled classes, constants and functions, "
|
||
"releasing any associated storage back into the storage pool. This enables recompilation to "
|
||
"take place." CR CR
|
||
|
||
"Note that you cannot selectively trim any of these resource pools. You can only do a complete "
|
||
"clean."
|
||
},
|
||
|
||
{"clear",
|
||
"Clearing breakpoints means you can once again run code without interruption." CR CR
|
||
|
||
"Note: use break delete N to clear a specific breakpoint." CR CR
|
||
|
||
"Note: if all breakpoints are cleared, then the PHP script will run until normal completion."
|
||
},
|
||
|
||
{"compile",
|
||
"The execution context may be pre-compiled before execution to provide an opportunity to "
|
||
"inspect the generated opcode output. The execution context must be defined before the compile "
|
||
"command can be used. Use the command **exec** to set the execution context." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P compile" CR
|
||
" $P c" CR CR
|
||
|
||
"Note: Then that it is usually necessary to issue a **clean** command to reset the environment prior "
|
||
"to compilation."
|
||
},
|
||
|
||
{"eval",
|
||
"The **eval** command takes a string expression which it evaluates and then displays. It "
|
||
"evaluates in the context of the lowest (that is the executing) frame, unless this has first "
|
||
"been explicitly changed by issuing a **frame** command. " CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P eval $variable" CR
|
||
" $P E $variable" CR
|
||
" Will print_r($variable) on the console, if it is defined" CR CR
|
||
|
||
" $P eval $variable = \"Hello phpdbg :)\"" CR
|
||
" $P E $variable = \"Hello phpdbg :)\"" CR
|
||
" Will set $variable in the current scope" CR CR
|
||
|
||
"Note that **eval** allows any valid PHP expression including assignments, function calls and "
|
||
"other write statements. This enables you to change the environment during execution, so care "
|
||
"is needed here. You can even call PHP functions which have breakpoints defined. " CR CR
|
||
|
||
"Note: **eval** will always show the result, so do not prefix the code with **return**"
|
||
},
|
||
|
||
{"exec",
|
||
"The **exec** command sets the execution context, that is the script to be executed. The "
|
||
"execution context must be defined either by executing the **exec** command or by using the "
|
||
"**-e** command line option before the script can be compiled or run." CR CR
|
||
|
||
"Note that the **exec** command also can be used to replace a previously defined execution "
|
||
"context." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
|
||
" $P exec /tmp/script.php" CR
|
||
" $P e /tmp/script.php" CR
|
||
" Set the execution context to **/tmp/script.php**"
|
||
},
|
||
|
||
//*********** Does F skip any breakpoints lower stack frames or only the current??
|
||
{"finish",
|
||
"The **finish** command causes control to be passed back to the vm, continuing execution. Any "
|
||
"breakpoints that are encountered within the current stack frame will be skipped. Execution "
|
||
"will then continue until the next breakpoint after leaving the stack frame or unitil "
|
||
"completion of the script" CR CR
|
||
|
||
"Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
|
||
"skipped. "CR CR
|
||
|
||
"Note **finish** will trigger a \"not executing\" error if not executing."
|
||
},
|
||
|
||
{"frame",
|
||
"The **frame** takes an optional integer argument. If omitted, then the current frame is displayed "
|
||
"If specified then the current scope is set to the corresponding frame listed in a **back** trace. " "This can be used to allowing access to the variables in a higher stack frame than that currently "
|
||
"being executed." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P frame 2" CR
|
||
" $P E $count" CR
|
||
" Go to frame 2 and print out variable **$count** in that frame" CR CR
|
||
|
||
"Note that this frame scope is discarded when execution continues, with the execution frame "
|
||
"then reset to the lowest executiong frame."
|
||
},
|
||
|
||
{"info",
|
||
"**info** commands provide quick access to various types of information about the PHP environment" CR
|
||
"Specific info commands are show below:" CR CR
|
||
|
||
" **Target** **Alias** **Purpose**" CR
|
||
" **break** **b** show current breakpoints" CR
|
||
" **files** **F** show included files" CR
|
||
" **classes** **c** show loaded classes" CR
|
||
" **funcs** **f** show loaded classes" CR
|
||
" **error** **e** show last error" CR
|
||
" **vars** **v** show active variables" CR
|
||
" **literal** **l** show active literal constants" CR
|
||
" **memory** **m** show memory manager stats"
|
||
},
|
||
|
||
// ******** same issue about breakpoints in called frames
|
||
{"leave",
|
||
"The **leave** command causes control to be passed back to the vm, continuing execution. Any "
|
||
"breakpoints that are encountered within the current stack frame will be skipped. In effect a "
|
||
"temporary breakpoint is associated with any return opcode, so that a break in execution occurs "
|
||
"before leaving the current stack frame. This allows inspection / modification of any frame "
|
||
"variables including the return value before it is returned" CR CR
|
||
|
||
"**Examples**" CR CR
|
||
|
||
" $P leave" CR
|
||
" $P L" CR CR
|
||
|
||
"Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
|
||
"skipped. "CR CR
|
||
|
||
"Note **leave** will trigger a \"not executing\" error if not executing."
|
||
},
|
||
|
||
{"list",
|
||
"The list command displays source code for the given argument. The target type is specficied by "
|
||
"a second subcommand keyword:" CR CR
|
||
|
||
" **Type** **Alias** **Purpose**" CR
|
||
" **lines** **l** List N lines from the current execution point" CR
|
||
" **func** **f** List the complete source for a specified function" CR
|
||
" **method** **m** List the complete source for a specified class::method" CR
|
||
" **class** **c** List the complete source for a specified class" CR CR
|
||
|
||
"Note that the context of **lines**, **func** and **method** can be determined by parsing the "
|
||
"argument, so these subcommands are optional. However, you must specify the **class** keyword "
|
||
"to list off a class." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P list 2" CR
|
||
" $P l l 2" CR
|
||
" List the next 2 lines from the current file" CR CR
|
||
|
||
" $P list my_function" CR
|
||
" $P l f my_function" CR
|
||
" List the source of the function **my_function**" CR CR
|
||
|
||
//************ ????
|
||
" $P list func .mine" CR
|
||
" $P l f .mine" CR
|
||
" List the source of the method **mine** from the active class in scope" CR CR
|
||
|
||
" $P list m my::method" CR
|
||
" $P l my::method" CR
|
||
" List the source of **my::method**" CR CR
|
||
|
||
" $P list c myClass" CR
|
||
" $P l c myClass" CR
|
||
" List the source of **myClass**" CR CR
|
||
|
||
"Note that functions and classes can only be listed if the corresponding classes and functions "
|
||
"table in the Zend executor has a corresponding entry. You can use the compile command to "
|
||
"populate these tables for a given execution context."
|
||
},
|
||
|
||
//*********** what is the difference between n and s ???
|
||
{"next",
|
||
"The **next** command causes control to be passed back to the vm, continuing execution. The next "
|
||
"opline will be executed if **step 1** is set. Otherwise execution will continue to the next "
|
||
"breakpoint or script completion" CR CR
|
||
|
||
"Note **next** will trigger a \"not running\" error if not executing."
|
||
},
|
||
|
||
{"print",
|
||
"By default, print will show information about the current execution context." CR
|
||
"Other printing commands give access to instruction information." CR
|
||
"Specific printers loaded are show below:" CR CR
|
||
|
||
" **Type** **Alias** **Purpose**" CR
|
||
" **exec** **e** print out the instructions in the execution context" CR
|
||
" **opline** **o** print out the instruction in the current opline" CR
|
||
" **class** **c** print out the instructions in the specified class" CR
|
||
" **method** **m** print out the instructions in the specified method" CR
|
||
" **func** **f** print out the instructions in the specified function" CR
|
||
" **stack** **s** print out the instructions in the current stack" CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P print class \\\\my\\\\class" CR
|
||
" $P p c \\\\my\\\\class" CR
|
||
" Print the instructions for the methods in \\\\my\\\\class" CR CR
|
||
|
||
" $P print method \\\\my\\\\class::method" CR
|
||
" $P p m \\\\my\\\\class::method" CR
|
||
" Print the instructions for \\\\my\\\\class::method" CR CR
|
||
|
||
" $P print func .getSomething" CR
|
||
" $P p f .getSomething" CR
|
||
//************* Check this local method scope
|
||
" Print the instructions for ::getSomething in the active scope" CR CR
|
||
|
||
" $P print func my_function" CR
|
||
" $P p f my_function" CR
|
||
" Print the instructions for the global function my_function" CR CR
|
||
|
||
" $P print opline" CR
|
||
" $P p o" CR
|
||
" Print the instruction for the current opline" CR CR
|
||
|
||
" $P print exec" CR
|
||
" $P p e" CR
|
||
" Print the instructions for the execution context" CR CR
|
||
|
||
" $P print stack" CR
|
||
" $P p s" CR
|
||
" Print the instructions for the current stack"
|
||
},
|
||
|
||
{"quiet",
|
||
"Setting quietness on will stop the OPLINE output during execution" CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P quiet 1" CR
|
||
" $P Q 1" CR
|
||
" Will silence OPLINE output, while" CR CR
|
||
|
||
" $P quiet 0" CR
|
||
" $P Q 0" CR
|
||
" Will enable OPLINE output again" CR CR
|
||
|
||
"Note: Quietness is disabled automatically while stepping"
|
||
},
|
||
|
||
{"register",
|
||
//******* Needs a general explanation of the how registered functions work
|
||
"Register any global function for use as a command in phpdbg console" CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P register scandir" CR
|
||
" $P R scandir" CR
|
||
" Will register the scandir function for use in phpdbg" CR CR
|
||
|
||
"Note: arguments passed as strings, return (if present) print_r'd on console"
|
||
},
|
||
|
||
{"run",
|
||
"Enter the vm, startinging execution. Execution will then continue until the next breakpoint "
|
||
"or completion of the script"
|
||
"**Examples**" CR CR
|
||
" $P run" CR
|
||
" $P r" CR
|
||
" Will cause execution of the context, if it is set." CR CR
|
||
|
||
"Note that the execution context must be set. If not previously compiled, then the script will "
|
||
"be compiled before execution." CR CR
|
||
|
||
"Note that attempting to run a script that is already executing will result in an \"execution "
|
||
"in progress\" error."
|
||
},
|
||
|
||
{"set",
|
||
"The **set** command is used to configure how phpdbg looks and behaves. Specific set commands "
|
||
"are as follows:" CR CR
|
||
|
||
" **Type** **Alias** **Purpose**" CR
|
||
" **prompt** **p** set the prompt " CR
|
||
" **color** **c** set color <element> <color>" CR
|
||
" **colors** **C** set colors on or off" CR
|
||
" **oplog** **O** set oplog output" CR
|
||
" **break** **b** set break **id** <on|off>" CR CR
|
||
|
||
"Valid colors are **none**, **white**, **red**, **green**, **yellow**, **blue**, **purple**, "
|
||
"**cyan** and **black**. All colours except **none** can be followed by an optional "
|
||
"**-bold** or **-underline** qualifier." CR CR
|
||
|
||
"Color elements can be one of **prompt**, **notice**, or **error**." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P s C on" CR
|
||
" Set colors on" CR CR
|
||
|
||
" $P set p >" CR
|
||
" $P set color prompt white-bold" CR
|
||
" Set the prompt to a bold >" CR CR
|
||
|
||
" $P s c error red-bold" CR
|
||
" Use red bold for errors" CR
|
||
" " CR
|
||
" $P s b 4 off" CR
|
||
" Temporarily disable breakpoint 4. This can be subsequently reenabled by a **s b 4 on**." CR
|
||
//*********** check oplog syntax
|
||
},
|
||
|
||
{"shell",
|
||
//************ Check ! notation
|
||
"Direct access to shell commands saves having to switch windows/consoles" CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P shell ls /usr/src/php-src" CR
|
||
" $P - ls /usr/src/php-src" CR
|
||
" Will execute ls /usr/src/php-src, displaying the output in the console"
|
||
//*********** what does this mean????Note: read only commands please!
|
||
},
|
||
|
||
{"source",
|
||
"Sourcing a **phpdbginit** script during your debugging session might save some time." CR CR
|
||
|
||
"The source command can also be used to export breakpoints to a phpdbginit file." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
|
||
" $P source /my/init" CR
|
||
" $P . /my/init" CR
|
||
" Will execute the phpdbginit file at /my/init" CR CR
|
||
|
||
" $P source export /my/init" CR
|
||
" $P . export /my/init" CR
|
||
" Will export breakpoints to /my/init in phpdbginit file format"
|
||
},
|
||
|
||
{"step",
|
||
"You can enable and disable **stepping** mode at the phpdbg prompt during execution. When "
|
||
"stepping mode is enabled, execution will be step through opcode by opcode." CR CR
|
||
|
||
"**Examples**" CR CR
|
||
" $P step 1" CR
|
||
" $P s 1" CR
|
||
" Will enable stepping" CR CR
|
||
|
||
"While stepping is enabled you are presented with an interactive prompt after the execution of "
|
||
"each opcode." CR CR
|
||
|
||
"Note that when executing the **finish** and **leave** commands, and oplines within the current "
|
||
"execution frame will be skipped in line with the command behaviour. Stepping will resume on exit "
|
||
"from the current frame."
|
||
},
|
||
|
||
{"until",
|
||
"The **until** command causes control to be passed back to the vm, continuing execution. Any "
|
||
"breakpoints that are encountered before the next source line will be skipped. Execution "
|
||
"will then continue until the next breakpoint or completion of the script" CR CR
|
||
|
||
"Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
|
||
|
||
"Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
|
||
"skipped. " CR CR
|
||
|
||
"Note **until** will trigger a \"not executing\" error if not executing."
|
||
|
||
},
|
||
{NULL, NULL /* end of table marker */}
|
||
}; /* }}} */
|