This source file includes following definitions.
- pretty_print
- summary_print
- get_help
- get_command
- PHPDBG_COMMAND
- PHPDBG_HELP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
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
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;
62 unsigned int last_blank_count = 0;
63 unsigned int line_count = 0;
64
65 if (PHPDBG_G(flags) & PHPDBG_WRITE_XML) {
66 phpdbg_xml("<help %r msg=\"%s\" />", text);
67 return;
68 }
69
70
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
87
88
89
90
91
92
93
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
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
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
154 static char *get_help(const char * const key)
155 {
156 phpdbg_help_text_t *p;
157
158
159
160
161
162 for (p = phpdbg_help_text; p->key; p++) {
163 if (!strcmp(p->key, key)) {
164 return p->text;
165 }
166 }
167 return "";
168 }
169
170
171
172
173
174
175
176
177
178
179 static int get_command(
180 const char *key, size_t len,
181 phpdbg_command_t const **command,
182 phpdbg_command_t const * commands
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
212 PHPDBG_COMMAND(help)
213 {
214 phpdbg_command_t const *cmd;
215 int n;
216
217 if (!param || param->type == EMPTY_PARAM) {
218 pretty_print(get_help("overview!"));
219 return SUCCESS;
220 }
221
222 if (param && param->type == STR_PARAM) {
223 n = get_command(param->str, param->len, &cmd, phpdbg_prompt_commands);
224
225 if (n==1) {
226 summary_print(cmd);
227 pretty_print(get_help(cmd->name));
228 return SUCCESS;
229
230 } else if (n>1) {
231 if (param->len > 1) {
232 for (cmd=phpdbg_prompt_commands; cmd->name; cmd++) {
233 if (!strncmp(cmd->name, param->str, param->len)) {
234 summary_print(cmd);
235 }
236 }
237 pretty_print(get_help("duplicate!"));
238 return SUCCESS;
239 } else {
240 phpdbg_error("help", "type=\"ambiguousalias\" alias=\"%s\"", "Internal help error, non-unique alias \"%c\"", param->str[0]);
241 return FAILURE;
242 }
243
244 } else {
245 n = get_command( param->str, param->len, &cmd, phpdbg_help_commands);
246
247 if (n>0) {
248 if (cmd->alias == 'a') {
249 return cmd->handler(param);
250 } else {
251 pretty_print(get_help(cmd->name));
252 return SUCCESS;
253 }
254 }
255 }
256 }
257
258 return FAILURE;
259
260 }
261
262 PHPDBG_HELP(aliases)
263 {
264 const phpdbg_command_t *c, *c_sub;
265 int len;
266
267
268 phpdbg_writeln("help", "", "Below are the aliased, short versions of all supported commands");
269 phpdbg_xml("<helpcommands %r>");
270 for(c = phpdbg_prompt_commands; c->name; c++) {
271 if (c->alias && c->alias != 'h') {
272 phpdbg_writeln("command", "alias=\"%c\" name=\"%s\" tip=\"%s\"", " %c %-20s %s", c->alias, c->name, c->tip);
273 if (c->subs) {
274 len = 20 - 1 - c->name_len;
275 for(c_sub = c->subs; c_sub->alias; c_sub++) {
276 if (c_sub->alias) {
277 phpdbg_writeln("subcommand", "parent_alias=\"%c\" alias=\"%c\" parent=\"%s\" name=\"%-*s\" tip=\"%s\"", " %c %c %s %-*s %s",
278 c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
279 }
280 }
281 }
282 }
283 }
284
285 phpdbg_xml("</helpcommands>");
286
287
288 get_command("h", 1, &c, phpdbg_prompt_commands);
289 phpdbg_writeln("aliasinfo", "alias=\"%c\" name=\"%s\" tip=\"%s\"", " %c %-20s %s\n", c->alias, c->name, c->tip);
290
291 phpdbg_xml("<helpaliases>");
292
293 len = 20 - 1 - c->name_len;
294 for(c_sub = c->subs; c_sub->alias; c_sub++) {
295 if (c_sub->alias) {
296 phpdbg_writeln("alias", "parent_alias=\"%c\" alias=\"%c\" parent=\"%s\" name=\"%-*s\" tip=\"%s\"", " %c %c %s %-*s %s",
297 c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
298 }
299 }
300
301 phpdbg_xml("</helpaliases>");
302
303 pretty_print(get_help("aliases!"));
304 return SUCCESS;
305 }
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323 #define CR "\n"
324 phpdbg_help_text_t phpdbg_help_text[] = {
325
326
327 {"overview!", CR
328 "**phpdbg** is a lightweight, powerful and easy to use debugging platform for PHP5.4+" CR
329 "It supports the following commands:" CR CR
330
331 "**Information**" CR
332 " **list** list PHP source" CR
333 " **info** displays information on the debug session" CR
334 " **print** show opcodes" CR
335 " **frame** select a stack frame and print a stack frame summary" CR
336 " **back** shows the current backtrace" CR
337 " **help** provide help on a topic" CR CR
338
339 "**Starting and Stopping Execution**" CR
340 " **exec** set execution context" CR
341 " **run** attempt execution" CR
342 " **step** continue execution until other line is reached" CR
343 " **continue** continue execution" CR
344 " **until** continue execution up to the given location" CR
345 " **next** continue execution up to the given location and halt on the first line after it" CR
346 " **finish** continue up to end of the current execution frame" CR
347 " **leave** continue up to end of the current execution frame and halt after the calling instruction" CR
348 " **break** set a breakpoint at the specified target" CR
349 " **watch** set a watchpoint on $variable" CR
350 " **clear** clear one or all breakpoints" CR
351 " **clean** clean the execution environment" CR CR
352
353 "**Miscellaneous**" CR
354 " **set** set the phpdbg configuration" CR
355 " **source** execute a phpdbginit script" CR
356 " **register** register a phpdbginit function as a command alias" CR
357 " **sh** shell a command" CR
358 " **ev** evaluate some code" CR
359 " **quit** exit phpdbg" CR CR
360
361 "Type **help <command>** or (**help alias**) to get detailed help on any of the above commands, "
362 "for example **help list** or **h l**. Note that help will also match partial commands if unique "
363 "(and list out options if not unique), so **help clea** will give help on the **clean** command, "
364 "but **help cl** will list the summary for **clean** and **clear**." CR CR
365
366 "Type **help aliases** to show a full alias list, including any registered phpdginit functions" CR
367 "Type **help syntax** for a general introduction to the command syntax." CR
368 "Type **help options** for a list of phpdbg command line options." CR
369 "Type **help phpdbginit** to show how to customise the debugger environment."
370 },
371 {"options", CR
372 "Below are the command line options supported by phpdbg" CR CR
373
374 "**Command Line Options and Flags**" CR
375 " **Option** **Example Argument** **Description**" CR
376 " **-c** **-c**/my/php.ini Set php.ini file to load" CR
377 " **-d** **-d**memory_limit=4G Set a php.ini directive" CR
378 " **-n** Disable default php.ini" CR
379 " **-q** Suppress welcome banner" CR
380 " **-v** Enable oplog output" CR
381 " **-b** Disable colour" CR
382 " **-i** **-i**my.init Set .phpdbginit file" CR
383 " **-I** Ignore default .phpdbginit" CR
384 " **-O** **-O**my.oplog Sets oplog output file" CR
385 " **-r** Run execution context" CR
386 " **-rr** Run execution context and quit after execution (not respecting breakpoints)" CR
387 " **-e** Generate extended information for debugger/profiler" CR
388 " **-E** Enable step through eval, careful!" CR
389 " **-S** **-S**cli Override SAPI name, careful!" CR
390 " **-l** **-l**4000 Setup remote console ports" CR
391 " **-a** **-a**192.168.0.3 Setup remote console bind address" CR
392 " **-x** Enable xml output (instead of normal text output)" CR
393 " **-p** **-p**, **-p=func**, **-p* ** Output opcodes and quit" CR
394 " **-h** Print the help overview" CR
395 " **-V** Print version number" CR
396 " **--** **--** arg1 arg2 Use to delimit phpdbg arguments and php $argv; append any $argv "
397 "argument after it" CR CR
398
399 "**Remote Console Mode**" CR CR
400
401 "This mode is enabled by specifying the **-a** option. Phpdbg will bind only to the loopback "
402 "interface by default, and this can only be overridden by explicitly setting the remote console "
403 "bind address using the **-a** option. If **-a** is specied without an argument, then phpdbg "
404 "will bind to all available interfaces. You should be aware of the security implications of "
405 "doing this, so measures should be taken to secure this service if bound to a publicly accessible "
406 "interface/port." CR CR
407
408 "**Opcode output**" CR CR
409
410 "Outputting opcodes requires that a file path is passed as last argument. Modes of execution:" CR
411 "**-p** Outputs the main execution context" CR
412 "**-p* **Outputs all opcodes in the whole file (including classes and functions)" CR
413 "**-p=function_name** Outputs opcodes of a given function in the file" CR
414 "**-p=class_name::** Outputs opcodes of all the methods of a given class" CR
415 "**-p=class_name::method** Outputs opcodes of a given method"
416 },
417
418 {"phpdbginit", CR
419 "Phpdgb uses an debugger script file to initialize the debugger context. By default, phpdbg looks "
420 "for the file named **.phpdbginit** in the current working directory. This location can be "
421 "overridden on the command line using the **-i** switch (see **help options** for a more "
422 "details)." CR CR
423
424 "Debugger scripts can also be executed using the **source** command." CR CR
425
426 "A script file can contain a sequence of valid debugger commands, comments and embedded PHP "
427 "code. " CR CR
428
429 "Comment lines are prefixed by the **#** character. Note that comments are only allowed in script "
430 "files and not in interactive sessions." CR CR
431
432 "PHP code is delimited by the start and end escape tags **<:** and **:>**. PHP code can be used "
433 "to define application context for a debugging session and also to extend the debugger by defining "
434 "and **register** PHP functions as new commands." CR CR
435
436 "Also note that executing a **clear** command will cause the current **phpdbginit** to be reparsed "
437 "/ reloaded."
438 },
439
440 {"syntax", CR
441 "Commands start with a keyword, and some (**break**, "
442 "**info**, **set**, **print** and **list**) may include a subcommand keyword. All keywords are "
443 "lower case but also have a single letter alias that may be used as an alternative to typing in the"
444 "keyword in full. Note some aliases are uppercase, and that keywords cannot be abbreviated other "
445 "than by substitution by the alias." CR CR
446
447 "Some commands take an argument. Arguments are typed according to their format:" CR
448 " * **omitted**" CR
449 " * **address** **0x** followed by a hex string" CR
450 " * **number** an optionally signed number" CR
451 " * **method** a valid **Class::methodName** expression" CR
452 " * **func#op** a valid **Function name** follow by # and an integer" CR
453 " * **method#op** a valid **Class::methodName** follow by # and an integer" CR
454 " * **string** a general string" CR
455 " * **function** a valid **Function name**" CR
456 " * **file:line** a valid **filename** follow by : and an integer" CR CR
457
458 "In some cases the type of the argument enables the second keyword to be omitted." CR CR
459
460 "Type **help** for an overview of all commands and type **help <command>** to get detailed help "
461 "on any specific command." CR CR
462
463 "**Valid Examples**" CR CR
464
465 " $P quit" CR
466 " $P q" CR
467 " Quit the debugger" CR CR
468
469 " $P ev $total[2]" CR
470 " Evaluate and print the variable $total[2] in the current stack frame" CR
471 " " CR
472 " $P break 200" CR
473 " $P b my_source.php:200" CR
474 " Break at line 200 in the current source and in file **my_source.php**. " CR CR
475
476 " $P b @ ClassX::get_args if $arg[0] == \"fred\"" CR
477 " $P b ~ 3" CR
478 " Break at ClassX::get_args() if $arg[0] == \"fred\" and delete breakpoint 3" CR CR
479
480 "**Examples of invalid commands**" CR
481
482 " $P #This is a comment" CR
483 " Comments introduced by the **#** character are only allowed in **phpdbginit** script files."
484 },
485
486
487 {"aliases!", CR
488 "Note that aliases can be used for either command or sub-command keywords or both, so **info b** "
489 "is a synomyn for **info break** and **l func** for **list func**, etc." CR CR
490
491 "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."
492 },
493
494 {"duplicate!", CR
495 "Parameter is not unique. For detailed help select help on one of the above commands."
496 },
497
498
499 {"back",
500 "Provide a formatted backtrace using the standard debug_backtrace() functionality. An optional "
501 "unsigned integer argument specifying the maximum number of frames to be traced; if omitted then "
502 "a complete backtrace is given." CR CR
503
504 "**Examples**" CR CR
505 " $P back 5" CR
506 " $P t " CR
507 " " CR
508 "A backtrace can be executed at any time during execution."
509 },
510
511 {"break",
512 "Breakpoints can be set at a range of targets within the execution environment. Execution will "
513 "be paused if the program flow hits a breakpoint. The break target can be one of the following "
514 "types:" CR CR
515
516 " **Target** **Alias** **Purpose**" CR
517 " **at** **A** specify breakpoint by location and condition" CR
518 " **del** **d** delete breakpoint by breakpoint identifier number" CR CR
519
520 "**Break at** takes two arguments. The first is any valid target. The second "
521 "is a valid PHP expression which will trigger the break in "
522 "execution, if evaluated as true in a boolean context at the specified target." CR CR
523
524 "Note that breakpoints can also be disabled and re-enabled by the **set break** command." CR CR
525
526 "**Examples**" CR CR
527 " $P break test.php:100" CR
528 " $P b test.php:100" CR
529 " Break execution at line 100 of test.php" CR CR
530
531 " $P break 200" CR
532 " $P b 200" CR
533 " Break execution at line 200 of the currently PHP script file" CR CR
534
535 " $P break \\\\mynamespace\\\\my_function" CR
536 " $P b \\\\mynamespace\\\\my_function" CR
537 " Break execution on entry to \\\\mynamespace\\\\my_function" CR CR
538
539 " $P break classX::method" CR
540 " $P b classX::method" CR
541 " Break execution on entry to classX::method" CR CR
542
543 " $P break 0x7ff68f570e08" CR
544 " $P b 0x7ff68f570e08" CR
545 " Break at the opline at the address 0x7ff68f570e08" CR CR
546
547 " $P break my_function#14" CR
548 " $P b my_function#14" CR
549 " Break at the opline #14 of the function my_function" CR CR
550
551 " $P break \\\\my\\\\class::method#2" CR
552 " $P b \\\\my\\\\class::method#2" CR
553 " Break at the opline #2 of the method \\\\my\\\\class::method" CR CR
554
555 " $P break test.php:#3" CR
556 " $P b test.php:#3" CR
557 " Break at opline #3 in test.php" CR CR
558
559 " $P break if $cnt > 10" CR
560 " $P b if $cnt > 10" CR
561 " Break when the condition ($cnt > 10) evaluates to true" CR CR
562
563 " $P break at phpdbg::isGreat if $opt == 'S'" CR
564 " $P break @ phpdbg::isGreat if $opt == 'S'" CR
565 " Break at any opcode in phpdbg::isGreat when the condition ($opt == 'S') is true" CR CR
566
567 " $P break at test.php:20 if !isset($x)" CR
568 " Break at every opcode on line 20 of test.php when the condition evaluates to true" CR CR
569
570 " $P break ZEND_ADD" CR
571 " $P b ZEND_ADD" CR
572 " Break on any occurrence of the opcode ZEND_ADD" CR CR
573
574 " $P break del 2" CR
575 " $P b ~ 2" CR
576 " Remove breakpoint 2" CR CR
577
578 "Note: Conditional breaks are costly in terms of runtime overhead. Use them only when required "
579 "as they significantly slow execution." CR CR
580
581 "Note: An address is only valid for the current compilation."
582 },
583
584 {"clean",
585 "Classes, constants or functions can only be declared once in PHP. You may experience errors "
586 "during a debug session if you attempt to recompile a PHP source. The clean command clears "
587 "the Zend runtime tables which holds the sets of compiled classes, constants and functions, "
588 "releasing any associated storage back into the storage pool. This enables recompilation to "
589 "take place." CR CR
590
591 "Note that you cannot selectively trim any of these resource pools. You can only do a complete "
592 "clean."
593 },
594
595 {"clear",
596 "Clearing breakpoints means you can once again run code without interruption." CR CR
597
598 "Note: use break delete N to clear a specific breakpoint." CR CR
599
600 "Note: if all breakpoints are cleared, then the PHP script will run until normal completion."
601 },
602
603 {"ev",
604 "The **ev** command takes a string expression which it evaluates and then displays. It "
605 "evaluates in the context of the lowest (that is the executing) frame, unless this has first "
606 "been explicitly changed by issuing a **frame** command. " CR CR
607
608 "**Examples**" CR CR
609 " $P ev $variable" CR
610 " Will print_r($variable) on the console, if it is defined" CR CR
611
612 " $P ev $variable = \"Hello phpdbg :)\"" CR
613 " Will set $variable in the current scope" CR CR
614
615 "Note that **ev** allows any valid PHP expression including assignments, function calls and "
616 "other write statements. This enables you to change the environment during execution, so care "
617 "is needed here. You can even call PHP functions which have breakpoints defined. " CR CR
618
619 "Note: **ev** will always show the result, so do not prefix the code with **return**"
620 },
621
622 {"exec",
623 "The **exec** command sets the execution context, that is the script to be executed. The "
624 "execution context must be defined either by executing the **exec** command or by using the "
625 "**-e** command line option." CR CR
626
627 "Note that the **exec** command also can be used to replace a previously defined execution "
628 "context." CR CR
629
630 "**Examples**" CR CR
631
632 " $P exec /tmp/script.php" CR
633 " $P e /tmp/script.php" CR
634 " Set the execution context to **/tmp/script.php**"
635 },
636
637
638 {"finish",
639 "The **finish** command causes control to be passed back to the vm, continuing execution. Any "
640 "breakpoints that are encountered within the current stack frame will be skipped. Execution "
641 "will then continue until the next breakpoint after leaving the stack frame or until "
642 "completion of the script" CR CR
643
644 "Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
645 "skipped. "CR CR
646
647 "Note **finish** will trigger a \"not executing\" error if not executing."
648 },
649
650 {"frame",
651 "The **frame** takes an optional integer argument. If omitted, then the current frame is displayed "
652 "If specified then the current scope is set to the corresponding frame listed in a **back** trace. "
653 "This can be used to allowing access to the variables in a higher stack frame than that currently being executed." CR CR
654
655 "**Examples**" CR CR
656 " $P frame 2" CR
657 " $P ev $count" CR
658 " Go to frame 2 and print out variable **$count** in that frame" CR CR
659
660 "Note that this frame scope is discarded when execution continues, with the execution frame "
661 "then reset to the lowest executiong frame."
662 },
663
664 {"info",
665 "**info** commands provide quick access to various types of information about the PHP environment" CR
666 "By default general information about environment and PHP build is shown." CR
667 "Specific info commands are show below:" CR CR
668
669 " **Target** **Alias** **Purpose**" CR
670 " **break** **b** show current breakpoints" CR
671 " **files** **F** show included files" CR
672 " **classes** **c** show loaded classes" CR
673 " **funcs** **f** show loaded functions" CR
674 " **error** **e** show last error" CR
675 " **constants** **d** show user-defined constants" CR
676 " **vars** **v** show active variables" CR
677 " **globals** **g** show superglobal variables" CR
678 " **literal** **l** show active literal constants" CR
679 " **memory** **m** show memory manager stats"
680 },
681
682
683 {"leave",
684 "The **leave** command causes control to be passed back to the vm, continuing execution. Any "
685 "breakpoints that are encountered within the current stack frame will be skipped. In effect a "
686 "temporary breakpoint is associated with any return opcode, so that a break in execution occurs "
687 "before leaving the current stack frame. This allows inspection / modification of any frame "
688 "variables including the return value before it is returned" CR CR
689
690 "**Examples**" CR CR
691
692 " $P leave" CR
693 " $P L" CR CR
694
695 "Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
696 "skipped. "CR CR
697
698 "Note **leave** will trigger a \"not executing\" error if not executing."
699 },
700
701 {"list",
702 "The list command displays source code for the given argument. The target type is specficied by "
703 "a second subcommand keyword:" CR CR
704
705 " **Type** **Alias** **Purpose**" CR
706 " **lines** **l** List N lines from the current execution point" CR
707 " **func** **f** List the complete source for a specified function" CR
708 " **method** **m** List the complete source for a specified class::method" CR
709 " **class** **c** List the complete source for a specified class" CR CR
710
711 "Note that the context of **lines**, **func** and **method** can be determined by parsing the "
712 "argument, so these subcommands are optional. However, you must specify the **class** keyword "
713 "to list off a class." CR CR
714
715 "**Examples**" CR CR
716 " $P list 2" CR
717 " $P l l 2" CR
718 " List the next 2 lines from the current file" CR CR
719
720 " $P list my_function" CR
721 " $P l f my_function" CR
722 " List the source of the function **my_function**" CR CR
723
724
725 " $P list func .mine" CR
726 " $P l f .mine" CR
727 " List the source of the method **mine** from the active class in scope" CR CR
728
729 " $P list m my::method" CR
730 " $P l my::method" CR
731 " List the source of **my::method**" CR CR
732
733 " $P list c myClass" CR
734 " $P l c myClass" CR
735 " List the source of **myClass**" CR CR
736
737 "Note that functions and classes can only be listed if the corresponding classes and functions "
738 "table in the Zend executor has a corresponding entry. You can use the compile command to "
739 "populate these tables for a given execution context."
740 },
741
742 {"continue",
743 "Continue with execution after hitting a break or watchpoint" CR CR
744
745 "**Examples**" CR CR
746 " $P continue" CR
747 " $P c" CR
748 " Continue executing until the next break or watchpoint" CR CR
749
750 "Note **continue** will trigger a \"not running\" error if not executing."
751 },
752
753 {"print",
754 "By default, print will show the opcodes of the current execution context." CR
755 "Other printing commands give access to instruction information." CR
756 "Specific printers loaded are show below:" CR CR
757
758 " **Type** **Alias** **Purpose**" CR
759 " **exec** **e** print out the instructions in the execution context" CR
760 " **opline** **o** print out the instruction in the current opline" CR
761 " **class** **c** print out the instructions in the specified class" CR
762 " **method** **m** print out the instructions in the specified method" CR
763 " **func** **f** print out the instructions in the specified function" CR
764 " **stack** **s** print out the instructions in the current stack" CR CR
765
766 "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
767
768 "**Examples**" CR CR
769 " $P print class \\\\my\\\\class" CR
770 " $P p c \\\\my\\\\class" CR
771 " Print the instructions for the methods in \\\\my\\\\class" CR CR
772
773 " $P print method \\\\my\\\\class::method" CR
774 " $P p m \\\\my\\\\class::method" CR
775 " Print the instructions for \\\\my\\\\class::method" CR CR
776
777 " $P print func .getSomething" CR
778 " $P p f .getSomething" CR
779
780 " Print the instructions for ::getSomething in the active scope" CR CR
781
782 " $P print func my_function" CR
783 " $P p f my_function" CR
784 " Print the instructions for the global function my_function" CR CR
785
786 " $P print opline" CR
787 " $P p o" CR
788 " Print the instruction for the current opline" CR CR
789
790 " $P print exec" CR
791 " $P p e" CR
792 " Print the instructions for the execution context" CR CR
793
794 " $P print stack" CR
795 " $P p s" CR
796 " Print the instructions for the current stack"
797 },
798
799 {"register",
800
801 "Register any global function for use as a command in phpdbg console" CR CR
802
803 "**Examples**" CR CR
804 " $P register scandir" CR
805 " $P R scandir" CR
806 " Will register the scandir function for use in phpdbg" CR CR
807
808 "Note: arguments passed as strings, return (if present) print_r'd on console"
809 },
810
811 {"run",
812 "Enter the vm, startinging execution. Execution will then continue until the next breakpoint "
813 "or completion of the script. Add parameters you want to use as $argv"
814 "**Examples**" CR CR
815 " $P run" CR
816 " $P r" CR
817 " Will cause execution of the context, if it is set" CR CR
818 " $P r test" CR
819 " Will execute with $argv[1] == \"test\"" CR CR
820
821 "Note that the execution context must be set. If not previously compiled, then the script will "
822 "be compiled before execution." CR CR
823
824 "Note that attempting to run a script that is already executing will result in an \"execution "
825 "in progress\" error."
826 },
827
828 {"set",
829 "The **set** command is used to configure how phpdbg looks and behaves. Specific set commands "
830 "are as follows:" CR CR
831
832 " **Type** **Alias** **Purpose**" CR
833 " **prompt** **p** set the prompt" CR
834 " **color** **c** set color <element> <color>" CR
835 " **colors** **C** set colors [<on|off>]" CR
836 " **oplog** **O** set oplog [output]" CR
837 " **break** **b** set break **id** <on|off>" CR
838 " **breaks** **B** set breaks [<on|off>]" CR
839 " **quiet** **q** set quiet [<on|off>]" CR
840 " **stepping** **s** set stepping [<opcode|line>]" CR
841 " **refcount** **r** set refcount [<on|off>] " CR CR
842
843 "Valid colors are **none**, **white**, **red**, **green**, **yellow**, **blue**, **purple**, "
844 "**cyan** and **black**. All colours except **none** can be followed by an optional "
845 "**-bold** or **-underline** qualifier." CR CR
846
847 "Color elements can be one of **prompt**, **notice**, or **error**." CR CR
848
849 "**Examples**" CR CR
850 " $P S C on" CR
851 " Set colors on" CR CR
852
853 " $P set p >" CR
854 " $P set color prompt white-bold" CR
855 " Set the prompt to a bold >" CR CR
856
857 " $P S c error red-bold" CR
858 " Use red bold for errors" CR CR
859
860 " $P S refcount on" CR
861 " Enable refcount display when hitting watchpoints" CR CR
862
863 " $P S b 4 off" CR
864 " Temporarily disable breakpoint 4. This can be subsequently reenabled by a **s b 4 on**." CR
865
866 },
867
868 {"sh",
869 "Direct access to shell commands saves having to switch windows/consoles" CR CR
870
871 "**Examples**" CR CR
872 " $P sh ls /usr/src/php-src" CR
873 " Will execute ls /usr/src/php-src, displaying the output in the console"
874
875 },
876
877 {"source",
878 "Sourcing a **phpdbginit** script during your debugging session might save some time." CR CR
879
880 "**Examples**" CR CR
881
882 " $P source /my/init" CR
883 " $P < /my/init" CR
884 " Will execute the phpdbginit file at /my/init" CR CR
885 },
886
887 {"export",
888 "Exporting breakpoints allows you to share, and or save your current debugging session" CR CR
889
890 "**Examples**" CR CR
891
892 " $P export /my/exports" CR
893 " $P > /my/exports" CR
894 " Will export all breakpoints to /my/exports" CR CR
895 },
896
897 {"step",
898 "Execute opcodes until next line" CR CR
899
900 "**Examples**" CR CR
901
902 " $P s" CR
903 " Will continue and break again in the next encountered line" CR CR
904 },
905 {"next",
906 "The **next** command causes control to be passed back to the vm, continuing execution. Any "
907 "breakpoints that are encountered before the next source line will be skipped. Execution will"
908 "be stopped when that line is left." CR CR
909
910 "Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
911
912 "Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
913 "skipped. " CR CR
914
915 "Note **next** will trigger a \"not executing\" error if not executing."
916
917 },
918 {"until",
919 "The **until** command causes control to be passed back to the vm, continuing execution. Any "
920 "breakpoints that are encountered before the next source line will be skipped. Execution "
921 "will then continue until the next breakpoint or completion of the script" CR CR
922
923 "Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
924
925 "Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
926 "skipped. " CR CR
927
928 "Note **until** will trigger a \"not executing\" error if not executing."
929
930 },
931 {"watch",
932 "Sets watchpoints on variables as long as they are defined" CR
933 "Passing no parameter to **watch**, lists all actually active watchpoints" CR CR
934
935 "**Format for $variable**" CR CR
936 " **$var** Variable $var" CR
937 " **$var[]** All array elements of $var" CR
938 " **$var->** All properties of $var" CR
939 " **$var->a** Property $var->a" CR
940 " **$var[b]** Array element with key b in array $var" CR CR
941
942 "Subcommands of **watch**:" CR CR
943
944 " **Type** **Alias** **Purpose**" CR
945 " **array** **a** Sets watchpoint on array/object to observe if an entry is added or removed" CR
946 " **recursive** **r** Watches variable recursively and automatically adds watchpoints if some entry is added to an array/object" CR
947 " **delete** **d** Removes watchpoint" CR CR
948
949 "Note when **recursive** watchpoints are removed, watchpoints on all the children are removed too" CR CR
950
951 "**Examples**" CR CR
952 " $P watch" CR
953 " List currently active watchpoints" CR CR
954
955 " $P watch $array" CR
956 " $P w $array" CR
957 " Set watchpoint on $array" CR CR
958
959 " $P watch recursive $obj->" CR
960 " $P w r $obj->" CR
961 " Set recursive watchpoint on $obj->" CR CR
962
963 " $P watch delete $obj->a" CR
964 " $P w d $obj->a" CR
965 " Remove watchpoint $obj->a" CR CR
966
967 "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
968 " You then you can continue, phpdbg will remove the write protection, so that the program can continue." CR
969 " If phpdbg could not handle that segfault, the same segfault is triggered again and this time phpdbg will abort."
970 },
971 {NULL, NULL }
972 };