1 /*
2 +----------------------------------------------------------------------+
3 | PHP Version 7 |
4 +----------------------------------------------------------------------+
5 | Copyright (c) 1997-2017 The PHP Group |
6 +----------------------------------------------------------------------+
7 | This source file is subject to version 3.01 of the PHP license, |
8 | that is bundled with this package in the file LICENSE, and is |
9 | available through the world-wide-web at the following url: |
10 | http://www.php.net/license/3_01.txt |
11 | If you did not receive a copy of the PHP license and are unable to |
12 | obtain it through the world-wide-web, please send a note to |
13 | license@php.net so we can mail you a copy immediately. |
14 +----------------------------------------------------------------------+
15 | Authors: Felipe Pena <felipe@php.net> |
16 | Authors: Joe Watkins <joe.watkins@live.co.uk> |
17 | Authors: Bob Weinand <bwoebi@php.net> |
18 | Authors: Terry Ellison <terry@ellisons.org.uk> |
19 +----------------------------------------------------------------------+
20 */
21
22 #include "phpdbg.h"
23 #include "phpdbg_help.h"
24 #include "phpdbg_prompt.h"
25 #include "phpdbg_eol.h"
26 #include "zend.h"
27
28 ZEND_EXTERN_MODULE_GLOBALS(phpdbg)
29
30 /* {{{ Commands Table */
31 #define PHPDBG_COMMAND_HELP_D(name, tip, alias, action) \
32 {PHPDBG_STRL(#name), tip, sizeof(tip)-1, alias, action, &phpdbg_prompt_commands[16], 0}
33
34 const phpdbg_command_t phpdbg_help_commands[] = {
35 PHPDBG_COMMAND_HELP_D(aliases, "show alias list", 'a', phpdbg_do_help_aliases),
36 PHPDBG_COMMAND_HELP_D(options, "command line options", 0, NULL),
37 PHPDBG_COMMAND_HELP_D(overview, "help overview", 0, NULL),
38 PHPDBG_COMMAND_HELP_D(phpdbginit, "phpdbginit file format", 0, NULL),
39 PHPDBG_COMMAND_HELP_D(syntax, "syntax overview", 0, NULL),
40 PHPDBG_END_COMMAND
41 }; /* }}} */
42
43 /* {{{ pretty_print. Formatting escapes and wrapping text in a string before printing it. */
pretty_print(char * text)44 void pretty_print(char *text)
45 {
46 char *new, *p, *q;
47
48 const char *prompt_escape = phpdbg_get_prompt();
49 unsigned int prompt_escape_len = strlen(prompt_escape);
50 unsigned int prompt_len = strlen(PHPDBG_G(prompt)[0]);
51
52 const char *bold_on_escape = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[1m" : "";
53 const char *bold_off_escape = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[0m" : "";
54 unsigned int bold_escape_len = strlen(bold_on_escape);
55
56 unsigned int term_width = phpdbg_get_terminal_width();
57 unsigned int size = 0;
58
59 int in_bold = 0;
60
61 char *last_new_blank = NULL; /* position in new buffer of last blank char */
62 unsigned int last_blank_count = 0; /* printable char offset of last blank char */
63 unsigned int line_count = 0; /* number printable chars on current line */
64
65 if (PHPDBG_G(flags) & PHPDBG_WRITE_XML) {
66 phpdbg_xml("<help %r msg=\"%s\" />", text);
67 return;
68 }
69
70 /* First pass calculates a safe size for the pretty print version */
71 for (p = text; *p; p++) {
72 if (UNEXPECTED(p[0] == '*') && p[1] == '*') {
73 size += bold_escape_len - 2;
74 p++;
75 } else if (UNEXPECTED(p[0] == '$') && p[1] == 'P') {
76 size += prompt_escape_len - 2;
77 p++;
78 } else if (UNEXPECTED(p[0] == '\\')) {
79 p++;
80 }
81 }
82 size += (p-text)+1;
83
84 new = emalloc(size);
85 /*
86 * Second pass substitutes the bold and prompt escape sequences and line wrap
87 *
88 * ** toggles bold on and off if PHPDBG_IS_COLOURED flag is set
89 * $P substitutes the prompt sequence
90 * Lines are wrapped by replacing the last blank with a CR before <term width>
91 * characters. (This defaults to 100 if the width can't be detected). In the
92 * pathelogical case where no blanks are found, then the wrap occurs at the
93 * first blank.
94 */
95 for (p = text, q = new; *p; p++) {
96 if (UNEXPECTED(*p == ' ')) {
97 last_new_blank = q;
98 last_blank_count = line_count++;
99 *q++ = ' ';
100 } else if (UNEXPECTED(*p == '\n')) {
101 last_new_blank = NULL;
102 *q++ = *p;
103 last_blank_count = 0;
104 line_count = 0;
105 } else if (UNEXPECTED(p[0] == '*') && p[1] == '*') {
106 if (bold_escape_len) {
107 in_bold = !in_bold;
108 memcpy (q, in_bold ? bold_on_escape : bold_off_escape, bold_escape_len);
109 q += bold_escape_len;
110 /* bold on/off has zero print width so line count is unchanged */
111 }
112 p++;
113 } else if (UNEXPECTED(p[0] == '$') && p[1] == 'P') {
114 memcpy (q, prompt_escape, prompt_escape_len);
115 q += prompt_escape_len;
116 line_count += prompt_len;
117 p++;
118 } else if (UNEXPECTED(p[0] == '\\')) {
119 p++;
120 *q++ = *p;
121 line_count++;
122 } else {
123 *q++ = *p;
124 line_count++;
125 }
126
127 if (UNEXPECTED(line_count>=term_width) && last_new_blank) {
128 *last_new_blank = '\n';
129 last_new_blank = NULL;
130 line_count -= last_blank_count;
131 last_blank_count = 0;
132 }
133 }
134 *q++ = '\0';
135
136 if ((q-new)>size) {
137 phpdbg_error("help", "overrun=\"%lu\"", "Output overrun of %lu bytes", ((q - new) - size));
138 }
139
140 phpdbg_out("%s\n", new);
141 efree(new);
142 } /* }}} */
143
144 /* {{{ summary_print. Print a summary line giving, the command, its alias and tip */
summary_print(phpdbg_command_t const * const cmd)145 void summary_print(phpdbg_command_t const * const cmd)
146 {
147 char *summary;
148 spprintf(&summary, 0, "Command: **%s** Alias: **%c** **%s**\n", cmd->name, cmd->alias, cmd->tip);
149 pretty_print(summary);
150 efree(summary);
151 }
152
153 /* {{{ get_help. Retries and formats text from the phpdbg help text table */
get_help(const char * const key)154 static char *get_help(const char * const key)
155 {
156 phpdbg_help_text_t *p;
157
158 /* Note that phpdbg_help_text is not assumed to be collated in key order. This is an
159 inconvience that means that help can't be logically grouped Not worth
160 the savings */
161
162 for (p = phpdbg_help_text; p->key; p++) {
163 if (!strcmp(p->key, key)) {
164 return p->text;
165 }
166 }
167 return ""; /* return empty string to denote no match found */
168 } /* }}} */
169
170 /* {{{ get_command. Return number of matching commands from a command table.
171 * Unlike the command parser, the help search is sloppy that is partial matches can occur
172 * * Any single character key is taken as an alias.
173 * * Other keys are matched again the table on the first len characters.
174 * * This means that non-unique keys can generate multiple matches.
175 * * The first matching command is returned as an OUT parameter. *
176 * The rationale here is to assist users in finding help on commands. So unique matches
177 * will be used to generate a help message but non-unique one will be used to list alternatives.
178 */
get_command(const char * key,size_t len,phpdbg_command_t const ** command,phpdbg_command_t const * commands)179 static int get_command(
180 const char *key, size_t len, /* pointer and length of key */
181 phpdbg_command_t const **command, /* address of first matching command */
182 phpdbg_command_t const * commands /* command table to be scanned */
183 )
184 {
185 const phpdbg_command_t *c;
186 unsigned int num_matches = 0;
187
188 if (len == 1) {
189 for (c=commands; c->name; c++) {
190 if (c->alias == key[0]) {
191 num_matches++;
192 if ( num_matches == 1 && command) {
193 *command = c;
194 }
195 }
196 }
197 } else {
198 for (c=commands; c->name; c++) {
199 if (!strncmp(c->name, key, len)) {
200 ++num_matches;
201 if ( num_matches == 1 && command) {
202 *command = c;
203 }
204 }
205 }
206 }
207
208 return num_matches;
209
210 } /* }}} */
211
phpdbg_do_help_cmd(char * type)212 void phpdbg_do_help_cmd(char *type) { /* {{{ */
213 char *help;
214
215 if (!type) {
216 pretty_print(get_help("overview!"));
217 return;
218 }
219
220 help = get_help(type);
221
222 if (!help || memcmp(help, "", sizeof("")) == SUCCESS) {
223 pretty_print(get_help("overview!"));
224 pretty_print(
225 "\nrequested help page could not be found");
226 return;
227 }
228
229 pretty_print(help);
230 } /* }}} */
231
PHPDBG_COMMAND(help)232 PHPDBG_COMMAND(help) /* {{{ */
233 {
234 phpdbg_command_t const *cmd;
235 int n;
236
237 if (!param || param->type == EMPTY_PARAM) {
238 pretty_print(get_help("overview!"));
239 return SUCCESS;
240 }
241
242 if (param && param->type == STR_PARAM) {
243 n = get_command(param->str, param->len, &cmd, phpdbg_prompt_commands);
244
245 if (n==1) {
246 summary_print(cmd);
247 pretty_print(get_help(cmd->name));
248 return SUCCESS;
249
250 } else if (n>1) {
251 if (param->len > 1) {
252 for (cmd=phpdbg_prompt_commands; cmd->name; cmd++) {
253 if (!strncmp(cmd->name, param->str, param->len)) {
254 summary_print(cmd);
255 }
256 }
257 pretty_print(get_help("duplicate!"));
258 return SUCCESS;
259 } else {
260 phpdbg_error("help", "type=\"ambiguousalias\" alias=\"%s\"", "Internal help error, non-unique alias \"%c\"", param->str[0]);
261 return FAILURE;
262 }
263
264 } else { /* no prompt command found so try help topic */
265 n = get_command( param->str, param->len, &cmd, phpdbg_help_commands);
266
267 if (n>0) {
268 if (cmd->alias == 'a') { /* help aliases executes a canned routine */
269 return cmd->handler(param);
270 } else {
271 pretty_print(get_help(cmd->name));
272 return SUCCESS;
273 }
274 }
275 }
276 }
277
278 return FAILURE;
279
280 } /* }}} */
281
PHPDBG_HELP(aliases)282 PHPDBG_HELP(aliases) /* {{{ */
283 {
284 const phpdbg_command_t *c, *c_sub;
285 int len;
286
287 /* Print out aliases for all commands except help as this one comes last */
288 phpdbg_writeln("help", "", "Below are the aliased, short versions of all supported commands");
289 phpdbg_xml("<helpcommands %r>");
290 for(c = phpdbg_prompt_commands; c->name; c++) {
291 if (c->alias && c->alias != 'h') {
292 phpdbg_writeln("command", "alias=\"%c\" name=\"%s\" tip=\"%s\"", " %c %-20s %s", c->alias, c->name, c->tip);
293 if (c->subs) {
294 len = 20 - 1 - c->name_len;
295 for(c_sub = c->subs; c_sub->alias; c_sub++) {
296 if (c_sub->alias) {
297 phpdbg_writeln("subcommand", "parent_alias=\"%c\" alias=\"%c\" parent=\"%s\" name=\"%-*s\" tip=\"%s\"", " %c %c %s %-*s %s",
298 c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
299 }
300 }
301 }
302 }
303 }
304
305 phpdbg_xml("</helpcommands>");
306
307 /* Print out aliases for help as this one comes last, with the added text on how aliases are used */
308 get_command("h", 1, &c, phpdbg_prompt_commands);
309 phpdbg_writeln("aliasinfo", "alias=\"%c\" name=\"%s\" tip=\"%s\"", " %c %-20s %s\n", c->alias, c->name, c->tip);
310
311 phpdbg_xml("<helpaliases>");
312
313 len = 20 - 1 - c->name_len;
314 for(c_sub = c->subs; c_sub->alias; c_sub++) {
315 if (c_sub->alias) {
316 phpdbg_writeln("alias", "parent_alias=\"%c\" alias=\"%c\" parent=\"%s\" name=\"%-*s\" tip=\"%s\"", " %c %c %s %-*s %s",
317 c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
318 }
319 }
320
321 phpdbg_xml("</helpaliases>");
322
323 pretty_print(get_help("aliases!"));
324 return SUCCESS;
325 } /* }}} */
326
327
328 /* {{{ Help Text Table
329 * Contains help text entries keyed by a lowercase ascii key.
330 * Text is in ascii and enriched by a simple markup:
331 * ** toggles bold font emphasis.
332 * $P insert an bold phpdbg> prompt.
333 * \ escapes the following character. Note that this is itself escaped inside string
334 * constants so \\\\ is required to output a single \ e.g. as in namespace names.
335 *
336 * Text will be wrapped according to the STDOUT terminal width, so paragraphs are
337 * flowed using the C stringizing and the CR definition. Also note that entries
338 * are collated in alphabetic order on key.
339 *
340 * Also note the convention that help text not directly referenceable as a help param
341 * has a key ending in !
342 */
343 #define CR "\n"
344 phpdbg_help_text_t phpdbg_help_text[] = {
345
346 /******************************** General Help Topics ********************************/
347 {"overview!", CR
348 "**phpdbg** is a lightweight, powerful and easy to use debugging platform for PHP5.4+" CR
349 "It supports the following commands:" CR CR
350
351 "**Information**" CR
352 " **list** list PHP source" CR
353 " **info** displays information on the debug session" CR
354 " **print** show opcodes" CR
355 " **frame** select a stack frame and print a stack frame summary" CR
356 " **back** shows the current backtrace" CR
357 " **help** provide help on a topic" CR CR
358
359 "**Starting and Stopping Execution**" CR
360 " **exec** set execution context" CR
361 " **stdin** set executing script from stdin" CR
362 " **run** attempt execution" CR
363 " **step** continue execution until other line is reached" CR
364 " **continue** continue execution" CR
365 " **until** continue execution up to the given location" CR
366 " **next** continue execution up to the given location and halt on the first line after it" CR
367 " **finish** continue up to end of the current execution frame" CR
368 " **leave** continue up to end of the current execution frame and halt after the calling instruction" CR
369 " **break** set a breakpoint at the specified target" CR
370 " **watch** set a watchpoint on $variable" CR
371 " **clear** clear one or all breakpoints" CR
372 " **clean** clean the execution environment" CR CR
373
374 "**Miscellaneous**" CR
375 " **set** set the phpdbg configuration" CR
376 " **source** execute a phpdbginit script" CR
377 " **register** register a phpdbginit function as a command alias" CR
378 " **sh** shell a command" CR
379 " **ev** evaluate some code" CR
380 " **quit** exit phpdbg" CR CR
381
382 "Type **help <command>** or (**help alias**) to get detailed help on any of the above commands, "
383 "for example **help list** or **h l**. Note that help will also match partial commands if unique "
384 "(and list out options if not unique), so **help clea** will give help on the **clean** command, "
385 "but **help cl** will list the summary for **clean** and **clear**." CR CR
386
387 "Type **help aliases** to show a full alias list, including any registered phpdginit functions" CR
388 "Type **help syntax** for a general introduction to the command syntax." CR
389 "Type **help options** for a list of phpdbg command line options." CR
390 "Type **help phpdbginit** to show how to customise the debugger environment."
391 },
392 {"options", CR
393 "Below are the command line options supported by phpdbg" CR CR
394 /* note the extra 4 space index in because of the extra **** */
395 "**Command Line Options and Flags**" CR
396 " **Option** **Example Argument** **Description**" CR
397 " **-c** **-c**/my/php.ini Set php.ini file to load" CR
398 " **-d** **-d**memory_limit=4G Set a php.ini directive" CR
399 " **-n** Disable default php.ini" CR
400 " **-q** Suppress welcome banner" CR
401 " **-v** Enable oplog output" CR
402 " **-b** Disable colour" CR
403 " **-i** **-i**my.init Set .phpdbginit file" CR
404 " **-I** Ignore default .phpdbginit" CR
405 " **-O** **-O**my.oplog Sets oplog output file" CR
406 " **-r** Run execution context" CR
407 " **-rr** Run execution context and quit after execution (not respecting breakpoints)" CR
408 " **-e** Generate extended information for debugger/profiler" CR
409 " **-E** Enable step through eval, careful!" CR
410 " **-s** **-s=**, **-s**=foo Read code to execute from stdin with an optional delimiter" CR
411 " **-S** **-S**cli Override SAPI name, careful!" CR
412 " **-l** **-l**4000 Setup remote console ports" CR
413 " **-a** **-a**192.168.0.3 Setup remote console bind address" CR
414 " **-x** Enable xml output (instead of normal text output)" CR
415 " **-p** **-p**, **-p=func**, **-p* ** Output opcodes and quit" CR
416 " **-h** Print the help overview" CR
417 " **-V** Print version number" CR
418 " **--** **--** arg1 arg2 Use to delimit phpdbg arguments and php $argv; append any $argv "
419 "argument after it" CR CR
420
421 "**Reading from stdin**" CR CR
422
423 "The **-s** option allows inputting a script to execute directly from stdin. The given delimiter "
424 "(\"foo\" in the example) needs to be specified at the end of the input on its own line, followed by "
425 "a line break. If **-rr** has been specified, it is allowed to omit the delimiter (**-s=**) and "
426 "it will read until EOF. See also the help entry for the **stdin** command." CR CR
427
428 "**Remote Console Mode**" CR CR
429
430 "This mode is enabled by specifying the **-a** option. Phpdbg will bind only to the loopback "
431 "interface by default, and this can only be overridden by explicitly setting the remote console "
432 "bind address using the **-a** option. If **-a** is specied without an argument, then phpdbg "
433 "will bind to all available interfaces. You should be aware of the security implications of "
434 "doing this, so measures should be taken to secure this service if bound to a publicly accessible "
435 "interface/port." CR CR
436
437 "**Opcode output**" CR CR
438
439 "Outputting opcodes requires that a file path is passed as last argument. Modes of execution:" CR
440 "**-p** Outputs the main execution context" CR
441 "**-p* **Outputs all opcodes in the whole file (including classes and functions)" CR
442 "**-p=function_name** Outputs opcodes of a given function in the file" CR
443 "**-p=class_name::** Outputs opcodes of all the methods of a given class" CR
444 "**-p=class_name::method** Outputs opcodes of a given method"
445 },
446
447 {"phpdbginit", CR
448 "Phpdgb uses an debugger script file to initialize the debugger context. By default, phpdbg looks "
449 "for the file named **.phpdbginit** in the current working directory. This location can be "
450 "overridden on the command line using the **-i** switch (see **help options** for a more "
451 "details)." CR CR
452
453 "Debugger scripts can also be executed using the **source** command." CR CR
454
455 "A script file can contain a sequence of valid debugger commands, comments and embedded PHP "
456 "code. " CR CR
457
458 "Comment lines are prefixed by the **#** character. Note that comments are only allowed in script "
459 "files and not in interactive sessions." CR CR
460
461 "PHP code is delimited by the start and end escape tags **<:** and **:>**. PHP code can be used "
462 "to define application context for a debugging session and also to extend the debugger by defining "
463 "and **register** PHP functions as new commands." CR CR
464
465 "Also note that executing a **clear** command will cause the current **phpdbginit** to be reparsed "
466 "/ reloaded."
467 },
468
469 {"syntax", CR
470 "Commands start with a keyword, and some (**break**, "
471 "**info**, **set**, **print** and **list**) may include a subcommand keyword. All keywords are "
472 "lower case but also have a single letter alias that may be used as an alternative to typing in the"
473 "keyword in full. Note some aliases are uppercase, and that keywords cannot be abbreviated other "
474 "than by substitution by the alias." CR CR
475
476 "Some commands take an argument. Arguments are typed according to their format:" CR
477 " * **omitted**" CR
478 " * **address** **0x** followed by a hex string" CR
479 " * **number** an optionally signed number" CR
480 " * **method** a valid **Class::methodName** expression" CR
481 " * **func#op** a valid **Function name** follow by # and an integer" CR
482 " * **method#op** a valid **Class::methodName** follow by # and an integer" CR
483 " * **string** a general string" CR
484 " * **function** a valid **Function name**" CR
485 " * **file:line** a valid **filename** follow by : and an integer" CR CR
486
487 "In some cases the type of the argument enables the second keyword to be omitted." CR CR
488
489 "Type **help** for an overview of all commands and type **help <command>** to get detailed help "
490 "on any specific command." CR CR
491
492 "**Valid Examples**" CR CR
493
494 " $P quit" CR
495 " $P q" CR
496 " Quit the debugger" CR CR
497
498 " $P ev $total[2]" CR
499 " Evaluate and print the variable $total[2] in the current stack frame" CR
500 " " CR
501 " $P break 200" CR
502 " $P b my_source.php:200" CR
503 " Break at line 200 in the current source and in file **my_source.php**. " CR CR
504
505 " $P b @ ClassX::get_args if $arg[0] == \"fred\"" CR
506 " $P b ~ 3" CR
507 " Break at ClassX::get_args() if $arg[0] == \"fred\" and delete breakpoint 3" CR CR
508
509 "**Examples of invalid commands**" CR
510
511 " $P #This is a comment" CR
512 " Comments introduced by the **#** character are only allowed in **phpdbginit** script files."
513 },
514
515 /******************************** Help Codicils ********************************/
516 {"aliases!", CR
517 "Note that aliases can be used for either command or sub-command keywords or both, so **info b** "
518 "is a synomyn for **info break** and **l func** for **list func**, etc." CR CR
519
520 "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."
521 },
522
523 {"duplicate!", CR
524 "Parameter is not unique. For detailed help select help on one of the above commands."
525 },
526
527 /******************************** Help on Commands ********************************/
528 {"back",
529 "Provide a formatted backtrace using the standard debug_backtrace() functionality. An optional "
530 "unsigned integer argument specifying the maximum number of frames to be traced; if omitted then "
531 "a complete backtrace is given." CR CR
532
533 "**Examples**" CR CR
534 " $P back 5" CR
535 " $P t " CR
536 " " CR
537 "A backtrace can be executed at any time during execution."
538 },
539
540 {"break",
541 "Breakpoints can be set at a range of targets within the execution environment. Execution will "
542 "be paused if the program flow hits a breakpoint. The break target can be one of the following "
543 "types:" CR CR
544
545 " **Target** **Alias** **Purpose**" CR
546 " **at** **A** specify breakpoint by location and condition" CR
547 " **del** **d** delete breakpoint by breakpoint identifier number" CR CR
548
549 "**Break at** takes two arguments. The first is any valid target. The second "
550 "is a valid PHP expression which will trigger the break in "
551 "execution, if evaluated as true in a boolean context at the specified target." CR CR
552
553 "Note that breakpoints can also be disabled and re-enabled by the **set break** command." CR CR
554
555 "**Examples**" CR CR
556 " $P break test.php:100" CR
557 " $P b test.php:100" CR
558 " Break execution at line 100 of test.php" CR CR
559
560 " $P break 200" CR
561 " $P b 200" CR
562 " Break execution at line 200 of the currently PHP script file" CR CR
563
564 " $P break \\\\mynamespace\\\\my_function" CR
565 " $P b \\\\mynamespace\\\\my_function" CR
566 " Break execution on entry to \\\\mynamespace\\\\my_function" CR CR
567
568 " $P break classX::method" CR
569 " $P b classX::method" CR
570 " Break execution on entry to classX::method" CR CR
571
572 " $P break 0x7ff68f570e08" CR
573 " $P b 0x7ff68f570e08" CR
574 " Break at the opline at the address 0x7ff68f570e08" CR CR
575
576 " $P break my_function#14" CR
577 " $P b my_function#14" CR
578 " Break at the opline #14 of the function my_function" CR CR
579
580 " $P break \\\\my\\\\class::method#2" CR
581 " $P b \\\\my\\\\class::method#2" CR
582 " Break at the opline #2 of the method \\\\my\\\\class::method" CR CR
583
584 " $P break test.php:#3" CR
585 " $P b test.php:#3" CR
586 " Break at opline #3 in test.php" CR CR
587
588 " $P break if $cnt > 10" CR
589 " $P b if $cnt > 10" CR
590 " Break when the condition ($cnt > 10) evaluates to true" CR CR
591
592 " $P break at phpdbg::isGreat if $opt == 'S'" CR
593 " $P break @ phpdbg::isGreat if $opt == 'S'" CR
594 " Break at any opcode in phpdbg::isGreat when the condition ($opt == 'S') is true" CR CR
595
596 " $P break at test.php:20 if !isset($x)" CR
597 " Break at every opcode on line 20 of test.php when the condition evaluates to true" CR CR
598
599 " $P break ZEND_ADD" CR
600 " $P b ZEND_ADD" CR
601 " Break on any occurrence of the opcode ZEND_ADD" CR CR
602
603 " $P break del 2" CR
604 " $P b ~ 2" CR
605 " Remove breakpoint 2" CR CR
606
607 "Note: Conditional breaks are costly in terms of runtime overhead. Use them only when required "
608 "as they significantly slow execution." CR CR
609
610 "Note: An address is only valid for the current compilation."
611 },
612
613 {"clean",
614 "Classes, constants or functions can only be declared once in PHP. You may experience errors "
615 "during a debug session if you attempt to recompile a PHP source. The clean command clears "
616 "the Zend runtime tables which holds the sets of compiled classes, constants and functions, "
617 "releasing any associated storage back into the storage pool. This enables recompilation to "
618 "take place." CR CR
619
620 "Note that you cannot selectively trim any of these resource pools. You can only do a complete "
621 "clean."
622 },
623
624 {"clear",
625 "Clearing breakpoints means you can once again run code without interruption." CR CR
626
627 "Note: use break delete N to clear a specific breakpoint." CR CR
628
629 "Note: if all breakpoints are cleared, then the PHP script will run until normal completion."
630 },
631
632 {"ev",
633 "The **ev** command takes a string expression which it evaluates and then displays. It "
634 "evaluates in the context of the lowest (that is the executing) frame, unless this has first "
635 "been explicitly changed by issuing a **frame** command. " CR CR
636
637 "**Examples**" CR CR
638 " $P ev $variable" CR
639 " Will print_r($variable) on the console, if it is defined" CR CR
640
641 " $P ev $variable = \"Hello phpdbg :)\"" CR
642 " Will set $variable in the current scope" CR CR
643
644 "Note that **ev** allows any valid PHP expression including assignments, function calls and "
645 "other write statements. This enables you to change the environment during execution, so care "
646 "is needed here. You can even call PHP functions which have breakpoints defined. " CR CR
647
648 "Note: **ev** will always show the result, so do not prefix the code with **return**"
649 },
650
651 {"exec",
652 "The **exec** command sets the execution context, that is the script to be executed. The "
653 "execution context must be defined either by executing the **exec** command or by using the "
654 "**-e** command line option." CR CR
655
656 "Note that the **exec** command also can be used to replace a previously defined execution "
657 "context." CR CR
658
659 "**Examples**" CR CR
660
661 " $P exec /tmp/script.php" CR
662 " $P e /tmp/script.php" CR
663 " Set the execution context to **/tmp/script.php**"
664 },
665
666 {"stdin",
667 "The **stdin** command takes a string serving as delimiter. It will then read all the input from "
668 "stdin until encountering the given delimiter on a standalone line. It can also be passed at "
669 "startup using the **-s=** command line option (the delimiter then is optional if **-rr** is "
670 "also passed - in that case it will just read until EOF)." CR
671 "This input will be then compiled as PHP code and set as execution context." CR CR
672
673 "**Example**" CR CR
674
675 " $P stdin foo" CR
676 " <?php" CR
677 " echo \"Hello, world!\\n\";" CR
678 " foo"
679 },
680
681 //*********** Does F skip any breakpoints lower stack frames or only the current??
682 {"finish",
683 "The **finish** command causes control to be passed back to the vm, continuing execution. Any "
684 "breakpoints that are encountered within the current stack frame will be skipped. Execution "
685 "will then continue until the next breakpoint after leaving the stack frame or until "
686 "completion of the script" CR CR
687
688 "Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
689 "skipped. "CR CR
690
691 "Note **finish** will trigger a \"not executing\" error if not executing."
692 },
693
694 {"frame",
695 "The **frame** takes an optional integer argument. If omitted, then the current frame is displayed "
696 "If specified then the current scope is set to the corresponding frame listed in a **back** trace. "
697 "This can be used to allowing access to the variables in a higher stack frame than that currently being executed." CR CR
698
699 "**Examples**" CR CR
700 " $P frame 2" CR
701 " $P ev $count" CR
702 " Go to frame 2 and print out variable **$count** in that frame" CR CR
703
704 "Note that this frame scope is discarded when execution continues, with the execution frame "
705 "then reset to the lowest executiong frame."
706 },
707
708 {"info",
709 "**info** commands provide quick access to various types of information about the PHP environment" CR
710 "By default general information about environment and PHP build is shown." CR
711 "Specific info commands are show below:" CR CR
712
713 " **Target** **Alias** **Purpose**" CR
714 " **break** **b** show current breakpoints" CR
715 " **files** **F** show included files" CR
716 " **classes** **c** show loaded classes" CR
717 " **funcs** **f** show loaded functions" CR
718 " **error** **e** show last error" CR
719 " **constants** **d** show user-defined constants" CR
720 " **vars** **v** show active variables" CR
721 " **globals** **g** show superglobal variables" CR
722 " **literal** **l** show active literal constants" CR
723 " **memory** **m** show memory manager stats"
724 },
725
726 // ******** same issue about breakpoints in called frames
727 {"leave",
728 "The **leave** command causes control to be passed back to the vm, continuing execution. Any "
729 "breakpoints that are encountered within the current stack frame will be skipped. In effect a "
730 "temporary breakpoint is associated with any return opcode, so that a break in execution occurs "
731 "before leaving the current stack frame. This allows inspection / modification of any frame "
732 "variables including the return value before it is returned" CR CR
733
734 "**Examples**" CR CR
735
736 " $P leave" CR
737 " $P L" CR CR
738
739 "Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
740 "skipped. "CR CR
741
742 "Note **leave** will trigger a \"not executing\" error if not executing."
743 },
744
745 {"list",
746 "The list command displays source code for the given argument. The target type is specficied by "
747 "a second subcommand keyword:" CR CR
748
749 " **Type** **Alias** **Purpose**" CR
750 " **lines** **l** List N lines from the current execution point" CR
751 " **func** **f** List the complete source for a specified function" CR
752 " **method** **m** List the complete source for a specified class::method" CR
753 " **class** **c** List the complete source for a specified class" CR CR
754
755 "Note that the context of **lines**, **func** and **method** can be determined by parsing the "
756 "argument, so these subcommands are optional. However, you must specify the **class** keyword "
757 "to list off a class." CR CR
758
759 "**Examples**" CR CR
760 " $P list 2" CR
761 " $P l l 2" CR
762 " List the next 2 lines from the current file" CR CR
763
764 " $P list my_function" CR
765 " $P l f my_function" CR
766 " List the source of the function **my_function**" CR CR
767
768 //************ ????
769 " $P list func .mine" CR
770 " $P l f .mine" CR
771 " List the source of the method **mine** from the active class in scope" CR CR
772
773 " $P list m my::method" CR
774 " $P l my::method" CR
775 " List the source of **my::method**" CR CR
776
777 " $P list c myClass" CR
778 " $P l c myClass" CR
779 " List the source of **myClass**" CR CR
780
781 "Note that functions and classes can only be listed if the corresponding classes and functions "
782 "table in the Zend executor has a corresponding entry. You can use the compile command to "
783 "populate these tables for a given execution context."
784 },
785
786 {"continue",
787 "Continue with execution after hitting a break or watchpoint" CR CR
788
789 "**Examples**" CR CR
790 " $P continue" CR
791 " $P c" CR
792 " Continue executing until the next break or watchpoint" CR CR
793
794 "Note **continue** will trigger a \"not running\" error if not executing."
795 },
796
797 {"print",
798 "By default, print will show the opcodes of the current execution context." CR
799 "Other printing commands give access to instruction information." CR
800 "Specific printers loaded are show below:" CR CR
801
802 " **Type** **Alias** **Purpose**" CR
803 " **exec** **e** print out the instructions in the execution context" CR
804 " **opline** **o** print out the instruction in the current opline" CR
805 " **class** **c** print out the instructions in the specified class" CR
806 " **method** **m** print out the instructions in the specified method" CR
807 " **func** **f** print out the instructions in the specified function" CR
808 " **stack** **s** print out the instructions in the current stack" CR CR
809
810 "In case passed argument does not match a specific printing command, it will treat it as function or method name and print its opcodes" CR CR
811
812 "**Examples**" CR CR
813 " $P print class \\\\my\\\\class" CR
814 " $P p c \\\\my\\\\class" CR
815 " Print the instructions for the methods in \\\\my\\\\class" CR CR
816
817 " $P print method \\\\my\\\\class::method" CR
818 " $P p m \\\\my\\\\class::method" CR
819 " Print the instructions for \\\\my\\\\class::method" CR CR
820
821 " $P print func .getSomething" CR
822 " $P p f .getSomething" CR
823 //************* Check this local method scope
824 " Print the instructions for ::getSomething in the active scope" CR CR
825
826 " $P print func my_function" CR
827 " $P p f my_function" CR
828 " Print the instructions for the global function my_function" CR CR
829
830 " $P print opline" CR
831 " $P p o" CR
832 " Print the instruction for the current opline" CR CR
833
834 " $P print exec" CR
835 " $P p e" CR
836 " Print the instructions for the execution context" CR CR
837
838 " $P print stack" CR
839 " $P p s" CR
840 " Print the instructions for the current stack"
841 },
842
843 {"register",
844 //******* Needs a general explanation of the how registered functions work
845 "Register any global function for use as a command in phpdbg console" CR CR
846
847 "**Examples**" CR CR
848 " $P register scandir" CR
849 " $P R scandir" CR
850 " Will register the scandir function for use in phpdbg" CR CR
851
852 "Note: arguments passed as strings, return (if present) print_r'd on console"
853 },
854
855 {"run",
856 "Enter the vm, starting execution. Execution will then continue until the next breakpoint "
857 "or completion of the script. Add parameters you want to use as $argv. Add a trailing "
858 "**< filename** for reading STDIN from a file." CR CR
859
860 "**Examples**" CR CR
861
862 " $P run" CR
863 " $P r" CR
864 " Will cause execution of the context, if it is set" CR CR
865 " $P r test < foo.txt" CR
866 " Will execute with $argv[1] == \"test\" and read from the foo.txt file for STDIN" CR CR
867
868 "Note that the execution context must be set. If not previously compiled, then the script will "
869 "be compiled before execution."
870 },
871
872 {"set",
873 "The **set** command is used to configure how phpdbg looks and behaves. Specific set commands "
874 "are as follows:" CR CR
875
876 " **Type** **Alias** **Purpose**" CR
877 " **prompt** **p** set the prompt" CR
878 " **color** **c** set color <element> <color>" CR
879 " **colors** **C** set colors [<on|off>]" CR
880 " **oplog** **O** set oplog [output]" CR
881 " **break** **b** set break **id** <on|off>" CR
882 " **breaks** **B** set breaks [<on|off>]" CR
883 " **quiet** **q** set quiet [<on|off>]" CR
884 " **stepping** **s** set stepping [<opcode|line>]" CR
885 " **refcount** **r** set refcount [<on|off>] " CR CR
886
887 "Valid colors are **none**, **white**, **red**, **green**, **yellow**, **blue**, **purple**, "
888 "**cyan** and **black**. All colours except **none** can be followed by an optional "
889 "**-bold** or **-underline** qualifier." CR CR
890
891 "Color elements can be one of **prompt**, **notice**, or **error**." CR CR
892
893 "**Examples**" CR CR
894 " $P S C on" CR
895 " Set colors on" CR CR
896
897 " $P set p >" CR
898 " $P set color prompt white-bold" CR
899 " Set the prompt to a bold >" CR CR
900
901 " $P S c error red-bold" CR
902 " Use red bold for errors" CR CR
903
904 " $P S refcount on" CR
905 " Enable refcount display when hitting watchpoints" CR CR
906
907 " $P S b 4 off" CR
908 " Temporarily disable breakpoint 4. This can be subsequently reenabled by a **s b 4 on**." CR
909 //*********** check oplog syntax
910 },
911
912 {"sh",
913 "Direct access to shell commands saves having to switch windows/consoles" CR CR
914
915 "**Examples**" CR CR
916 " $P sh ls /usr/src/php-src" CR
917 " Will execute ls /usr/src/php-src, displaying the output in the console"
918 //*********** what does this mean????Note: read only commands please!
919 },
920
921 {"source",
922 "Sourcing a **phpdbginit** script during your debugging session might save some time." CR CR
923
924 "**Examples**" CR CR
925
926 " $P source /my/init" CR
927 " $P < /my/init" CR
928 " Will execute the phpdbginit file at /my/init" CR CR
929 },
930
931 {"export",
932 "Exporting breakpoints allows you to share, and or save your current debugging session" CR CR
933
934 "**Examples**" CR CR
935
936 " $P export /my/exports" CR
937 " $P > /my/exports" CR
938 " Will export all breakpoints to /my/exports" CR CR
939 },
940
941 {"step",
942 "Execute opcodes until next line" CR CR
943
944 "**Examples**" CR CR
945
946 " $P s" CR
947 " Will continue and break again in the next encountered line" CR CR
948 },
949 {"next",
950 "The **next** command causes control to be passed back to the vm, continuing execution. Any "
951 "breakpoints that are encountered before the next source line will be skipped. Execution will"
952 "be stopped when that line is left." CR CR
953
954 "Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
955
956 "Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
957 "skipped. " CR CR
958
959 "Note **next** will trigger a \"not executing\" error if not executing."
960
961 },
962 {"until",
963 "The **until** command causes control to be passed back to the vm, continuing execution. Any "
964 "breakpoints that are encountered before the next source line will be skipped. Execution "
965 "will then continue until the next breakpoint or completion of the script" CR CR
966
967 "Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
968
969 "Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
970 "skipped. " CR CR
971
972 "Note **until** will trigger a \"not executing\" error if not executing."
973
974 },
975 {"watch",
976 "Sets watchpoints on variables as long as they are defined" CR
977 "Passing no parameter to **watch**, lists all actually active watchpoints" CR CR
978
979 "**Format for $variable**" CR CR
980 " **$var** Variable $var" CR
981 " **$var[]** All array elements of $var" CR
982 " **$var->** All properties of $var" CR
983 " **$var->a** Property $var->a" CR
984 " **$var[b]** Array element with key b in array $var" CR CR
985
986 "Subcommands of **watch**:" CR CR
987
988 " **Type** **Alias** **Purpose**" CR
989 " **array** **a** Sets watchpoint on array/object to observe if an entry is added or removed" CR
990 " **recursive** **r** Watches variable recursively and automatically adds watchpoints if some entry is added to an array/object" CR
991 " **delete** **d** Removes watchpoint" CR CR
992
993 "Note when **recursive** watchpoints are removed, watchpoints on all the children are removed too" CR CR
994
995 "**Examples**" CR CR
996 " $P watch" CR
997 " List currently active watchpoints" CR CR
998
999 " $P watch $array" CR
1000 " $P w $array" CR
1001 " Set watchpoint on $array" CR CR
1002
1003 " $P watch recursive $obj->" CR
1004 " $P w r $obj->" CR
1005 " Set recursive watchpoint on $obj->" CR CR
1006
1007 " $P watch delete $obj->a" CR
1008 " $P w d $obj->a" CR
1009 " Remove watchpoint $obj->a" CR CR
1010
1011 "Technical note: If using this feature with a debugger, you will get many segmentation faults, each time when a memory page containing a watched address is hit." CR
1012 " You then you can continue, phpdbg will remove the write protection, so that the program can continue." CR
1013 " If phpdbg could not handle that segfault, the same segfault is triggered again and this time phpdbg will abort."
1014 },
1015 {NULL, NULL /* end of table marker */}
1016 }; /* }}} */
1017
