xref: /PHP-7.1/sapi/phpdbg/xml.md (revision 7f6387b5)
1phpdbg XML format
2=================
3
4Common attributes
5=================
6
7severity
8--------
9
10- indicates the genre of phpdbg system output
11- usually one of these values:
12 - normal
13 - notice
14 - error
15
16msgout
17------
18
19- text message output related to the xml data (e.g. <intro severity="normal" help="help" msgout="To get help using phpdbg type "help" and press enter" />)
20
21req
22---
23
24- the request id, if one was passed to the last command (via -r %d, where %d is the id) (and the output is related to that message)
25
26file
27----
28
29- refers to a filename
30
31method
32------
33
34- format classname::methodname
35- refers to a method
36
37function
38--------
39
40- refers to a function
41
42symbol
43------
44
45- either function or method (is method if "::" are present)
46
47opline
48------
49
50- in hexadecimal format
51- refers to a specific pointer to a (zend_)op
52
53opcode
54------
55
56- refers to an opcode (ZEND_*)
57
58type
59----
60
61- general attribute for most errors, describes the genre of the error
62
63General tags
64============
65
66intro
67-----
68
69- appears on startup if -q flag wasn't provided as command line arg
70- before any input possibility
71- attributes may be spread over multiple tags
72- wrapped in <intros> tag
73
74### attributes ###
75
76- version: current phpdbg version (as string)
77- help: command name for help
78- report: URL for bug reporting
79
80
81phpdbg
82------
83
84- general text message output from phpdbg system
85
86stream
87------
88
89- any output by PHP itself (e.g. <stream type="stdout">test</stream>)
90
91### attributes ###
92
93- type: stderr or stdout
94
95php
96---
97
98- php error output
99
100### attributes ###
101
102- msg: the error message
103
104
105General error tags
106==================
107
108command
109-------
110
111- general errors about commands
112
113### possible attributes ###
114
115- type
116 - toomanyargs: more arguments than allowed
117 - noarg: argument missing
118 - wrongarg: wrong type of argument (e.g. letters instead of integer)
119 - toofewargs: not enough arguments
120 - notfound: command (or subcommand) doesn't exist
121 - ambiguous: command was ambiguous
122 - invalidcommand: command input is totally invalid
123 - (nostack: should not happen: is an internal error)
124 - (emptystack: should not happen: is an internal error)
125- command: passed command
126- subcommand: passed subcommand (present if the error is related to the subcommand)
127- expected: count of expected arguments
128- got: type of argument for type "wrongarg"
129- num: if possible, information about which parameter had a wrong argument
130
131inactive
132--------
133
134- by type
135 - op_array: nothing was yet compiled (probably because no execution context set)
136 - symbol_table: no symbol table present (not yet initiailized or already destructed)
137 - noexec: not in execution
138 - memory_manager: using the native memory manager (malloc, free, realloc) instead of e.g. the Zend MM
139 - notfound: file not found
140 - nocontext: execution context was not set (or compilation had failed)
141 - isrunning: command requires no running script
142
143
144Commands
145========
146
147export
148------
149
150- tag: <exportbreakpoint />
151- usually triggered by successful export command
152- may appear when cleaning to temporary store breakpoints
153- errors by type
154 - openfailure: could not create file
155
156### attributes ###
157
158- count: number of exported breakpoints
159
160break / info break
161------------------
162
163- General tag for breakpoint creation, deletion and hits is "<breakpoint />"
164
165### possible attributes ###
166
167- id: the breakpoint id (if the leave command was executed, the id has the value "leave")
168- num: the nth opline of a function/method/file
169- add: has value "success"/"fail": a brekpoint was successfully/not added
170- pending: the breakpoint is waiting for resolving (e.g. a file opline on a not yet loaded file)
171- deleted: has value "success"/"fail": a breakpoint was successfully/not deleted
172- eval: the condition on conditional breakpoints
173- file
174- opline
175- opcode
176- symbol
177- function
178- method
179- line
180
181
182- listing breakpoints always in a container element "<breakpoints>"
183 - Child nodes:
184  - function
185  - method
186  - file
187  - opline
188  - methodopline
189  - functionopline
190  - fileopline
191  - evalfunction
192  - evalfunctionopline
193  - evalmethod
194  - evalmethodopline
195  - evalfile
196  - evalopline
197  - eval
198  - opcode
199 - attributes:
200  - name: name of the symbol (function/method/file/opcode)
201  - disabled: empty value if enabled, non-empty if enabled
202
203- errors (by type)
204 - exists: the breakpoint already exists
205 - maxoplines: tries to break at an opline (usedoplinenum) higher than the number of present oplines (in maxoplinenum)
206 - nomethod: method doesn't exist
207 - internalfunction: one cannot break on an opline of an internal function
208 - notregular: tries to set a breakpoint in not a regular file
209 - (invalidparameter: should not happen: is an internal error)
210
211frame
212-----
213
214- General tag for frames is "<frame>"
215- always has id attribute; if it only has id attribute, it just indicates current frame number, no other elements follow
216- may contain other elements (of type <arg>) when contained in <backtrace> tag
217- <arg> always contains a <stream> element, the value of the variable
218
219### possible attributes ###
220
221- id: the frame id, current frame has id 0 (frames with internal function calls have the same id than their called frame)
222- symbol ("{main}" is root frame)
223- file
224- line
225- internal: has value "internal" when being an internal function call (one cannot inspect that frame)
226
227- being an error: (by type)
228 - maxnum: tried to access a frame with a number higher than existing (or < 0)
229
230### attributes on <arg> ###
231
232- variadic: has a non-empty value if the argument is variadic
233- name: variable name of parameter
234
235info (subcommands)
236------------------
237
238### break ###
239
240- See above ("break / info break")
241
242### files ###
243
244- lists included files
245- <includedfileinfo num="" /> with num having an integer value, indicating the number of included files
246- <includedfile name=""/>: one per file, with name being the file path of the included file
247
248### error ###
249
250- gets last error
251- <lasterror error="" (file="" line="") />
252- error attribute contains the last error as a string, is empty if there's no last error
253
254### vars / globals ###
255
256- <variableinfo num="" /> with num having an integer value, indicating the number of (local or superglobal) variables
257- if info vars was used it'll have also one of these attributes:
258 - method
259 - function
260 - file
261 - opline
262- for each variable there is a <variable> followed by a <variabledetails> element
263- <variable address="" refcount="" type="" name="" />
264 - address: pointer to zval (hexadecimal)
265 - refcount: refcount of zval
266 - type: the variable type (long, string, ...). If the value is "unknown", the other attributes are meaningless
267 - name: the name of the variable
268 - refstatus: empty if the zval is not a reference
269 - class: the class the object in the zval is an instance of
270 - resource: the type of the resource in the zval
271
272### literal ###
273
274- <literalinfo num="" /> with num having an integer value, indicating the number of literals, optional arguments are:
275 - method
276 - function
277 - file
278 - opline
279- for each literal there is a <literal> followed by a <stream type="stdout"> which prints the value of the literal
280- <literal id="" />: where id is the internal identifier of the literal
281
282### memory ###
283
284- Format:
285
286    <meminfo />
287    <current />
288    <used mem="" />
289    <real mem="" />
290    <peak />
291    <used mem="" />
292    <real mem="" />
293
294- mem is an attribute whose value is a float. The memory is given in kilobytes (1 kB == 1024 bytes)
295
296### classes ###
297
298- <classinfo num="" /> with num having an integer value, indicating the number of loaded user-defined classes
299- Each class is enumerated with first a <class>, then an optional <parents> container and then a <classsource> element
300- The <parents> container contains the <class> elements of the parent of the last <class> element.
301- <class type="" flags="" name="" methodcount="" />
302 - type: either "User" or "Internal"
303 - flags: either "Interface", "Class" or "Abstract Class"
304- <classsource /> where the class was defined, if there are no attributes, location is unknown, usually defined by
305 - file
306 - line
307
308### funcs ###
309
310- <functioninfo num="" /> with num having an integer value, indicating the number of loaded user-defined functions
311- Each class is enumerated with first a <function> and then a <functionsource> element
312- <function name="" />
313- <functionsource /> where the function was defined, if there are no attributes, location is unknown, usually defined by
314 - file
315 - line
316
317list
318----
319
320- consists of <line> elements wrapped in a <list> container
321- <list file=""> is the container element with file being the filename
322- <line line="" code="" /> with value of code being the whole line of code in the line specified in the line attribute
323 - current: this attribute is set to "current" if that line is the line where the executor currently is
324
325print
326-----
327
328### without a subcommand ###
329
330- <print> elements are wrapped in a <printinfo> element
331- there may be a variable number of <print> elements with a variable count of args inside the <printinfo> element
332- possible args are:
333 - readline: yes/no - readline enabled or disabled
334 - libedit: yes/no - libedit enabled or disabled
335 - context: current executing context
336 - compiled: yes/no - are there actual compiled ops?
337 - stepping: @@ TODO (meaningless for now) @@
338 - quiet: on/off - should it always print the opline being currently executed?
339 - oplog: on/off - are oplines logged in a file?
340 - ops: number of opcodes in current executing context
341 - vars: number of compiled variables (CV)
342 - executing: yes/no - in executor?
343 - vmret: the return value of the last executed opcode
344  - default: continue
345  - 1: return from vm
346  - 2: enter stack frame
347  - 3: leave stack frame
348 - classes: number of classes
349 - functions: number of functions
350 - constants: number of constants
351 - includes: number of included files
352
353### with a subcommand ###
354
355- introduced by <printinfo num="" /> (except for print opline) with num being the number of opcodes and one of these args:
356 - file
357 - method
358 - function
359 - class (then also type and flags attributes, see info classes command for their meanings)
360 - symbol (also type and flags attributes; here the value of flags is either "Method" or "Function")
361- if there is a class method, the methods are all wrapped in a <printmethods> container
362- then comes a <printoplineinfo type="" /> where type is either "User" or "Internal"
363- the <printoplineinfo> has either a method or a function attribute
364- if the type is "Internal"
365 - there are no oplines, it's an internal method or function
366- if the type is "User"
367 - it has these attributes
368   - startline: the first line of code where the method or function is defined
369   - endline: the lastt line of code where the method or function is defined
370   - file: the file of code where the method or function is defined
371 - is followed by the oplines of that method or function (<print> elements)
372- <print line="%u" opline="%p" opcode="%s" op="%s" />
373- in case of print opline it emits a single <opline line="" opline="" opcode="" op="" file="" />
374
375exec
376----
377
378- command executing and compiling a given file
379 - <exec type="unset" context="" />: indicates unsetting of the old context
380 - <exec type="unsetops" />: indicates unsetting of the old compiled opcodes
381 - <exec type="unchanged" />: same execution context chosen again
382 - <exec type="set" context="" />: indicates setting of the new context
383- errors by tag
384 - <compile>
385  - openfailure: couldn't open file
386  - compilefailure: The file indicated in context couldn't be compiled
387 - <exec>
388  - invalid: given context (attribute) is not matching a valid file or symlink
389  - notfound: given context (attribute) does not exist
390
391run / <stop> tag
392-------------------
393
394- runs the script (set via exec command)
395- <stop type="end" />: script execution ended normally
396- (error) <stop type="bailout" /> the VM bailed out (usually because there was some error)
397- compile failures see under exec, errors, <compile>
398
399step
400----
401
402- steps by one line or opcode (as defined via set stepping) default is one line
403- returns back to the executor
404
405continue
406--------
407
408- returns back to the executor
409
410until
411-----
412
413- temporarily disables all the breakpoints on that line until that line was left once
414- returns back to the executor
415
416finish
417------
418
419- temporarily disables all the breakpoints until the end of the current frame
420- returns back to the executor
421
422leave
423------
424
425- temporarily disables all the breakpoints past the end of the current frame and then stops
426- returns back to the executor
427
428back
429----
430
431- prints backtrace
432- see frame command
433
434ev
435--
436
437- eval()uates some code
438- output wrapped in <eval> tags
439
440sh
441--
442
443- executes shell command
444- still pipes to stdout ... without wrapping <stream> !!! (@@ TODO @@)
445
446source
447------
448
449- executes a file in .phpdbginit format
450- errors by type
451 - notfound: file not found
452
453register
454--------
455
456- registers a function to be used like a command
457- <register function="" />: successfully registered function
458- errors by type
459 - notfound: no such function
460 - inuse: function already registered
461
462quit
463----
464
465- quits phpdbg
466- if successful connection will be closed...
467
468clean
469-----
470
471- cleans environment (basically a shutdown + new startup)
472- <clean> tags wrapped in a <cleaninfo> container
473- possible attributes of <clean> tag
474 - classes: number of classes
475 - functions: number of functions
476 - constants: number of constants
477 - includes: number of included files
478
479clear
480-----
481
482- removes all breakpoints
483- <clear> tags wrapped in a <clearinfo> container
484- possible attributes of <clear> tag (value is always the number of defined breakpoints of that type)
485 - files
486 - functions
487 - methods
488 - oplines
489 - fileoplines
490 - functionoplines
491 - methodoplines
492 - eval
493
494watch
495-----
496
497- watchpoints generally are identified by a variable (one may need to switch frames first...)
498- <watch variable="" />, <watchrecursive variable="" /> and <watcharray variable="" /> (normal, array, recursive)
499- <watch> if error, by type:
500 - undefined: tried to set a watchpoint on a not (yet) defined variable
501 - notiterable: element which is tried to be accessed as an object or array is nor array nor object
502 - invalidinput: generally malformed input
503- <watchdelete variable="" />: when "watch delete" was used on a watchpoint
504- (error) <watchdelete type="nowatch" />: that watchpoint doesn't exist, so couldn't be deleted
505- for hit watchpoints etc., see Other tags, <watch*>
506- when using watch list, <watchvariable> elements are wrapped in a <watchlist> container
507 - <watchvariable variable="" on="" type="" />
508  - variable: watched variable (may be a variable of another scope!)
509  - on: values are array or variable, depending on what is watched
510  - type: values are recursive or simple, depending on whether the watchpoint is checked recursively or not
511
512set
513---
514
515- a general error is type="wrongargs" where a wrong argument was passed to a subcommand; tag is then <set*>
516
517### prompt ###
518
519- without other args, a <setpromt str="" /> tag is emitted where the value of the str attribue is the value of the prompt
520- when there is another arg, the prompt is changed to that arg, no further xml answer
521
522### break ###
523
524- enables / disables a given breakpoint silently with no further xml answer
525- if the boolean switch is omitted, it emits current state in a <setbreak id="" active="" /> where active is on or off
526- error with type="nobreak", when no breakpoint with the given id exists
527
528### breaks ###
529
530- generally enables / disables breakpoint functionality silently with no further xml answer
531- if the boolean switch is omitted, it emits current state in a <setbreaks active="" /> where active is on or off
532
533### color ###
534
535- sets the color on prompt, error or notices
536- <setcolor type="" color="" code="" />: code is the color code of color, type is either:
537 - prompt
538 - error
539 - notice
540- errors by type:
541 - nocolor: color doesn't exist
542 - invalidtype: type wasn't one of the three allowed types
543
544### colors ###
545
546- generally enables / disables colors silently with no further xml answer
547- if the boolean switch is omitted, it emits current state in a <setcolors active="" /> where active is on or off
548
549### oplog ###
550
551- sets oplog
552- (error) <setoplog type="openfailure" file="" /> when it couldn't open the passed file path
553- <setoplog type="closingold" /> is emitted when there was a previous open oplog (and a file is passed)
554- if no further argument is passed, it emits current state in a <setoplog active="" /> where active is on or off
555
556### quiet ###
557
558- generally enables / disables quietness silently with no further xml answer
559- if the boolean switch is omitted, it emits current state in a <setquiet active="" /> where active is on or off
560
561### setpping ###
562
563- sets stepping to either opcode or line (so a step command will either advance one op or one line)
564- if no further argument is passed, it emits current state in a <setoplog type="" /> where active is opcode or line
565
566### refcount ###
567
568- generally enables / disables showing of refcount in watchpoint breaks silently with no further xml answer
569- if the boolean switch is omitted, it emits current state in a <setrefcount active="" /> where active is on or off
570
571wait
572----
573
574- internally executes exec, so exec will output first (if binding to socket worked)
575
576### attributes ###
577
578- import: has value "success"/"fail"
579- missingmodule/missingextension: modules/extensions loaded in the target SAPI, but not in phpdbg
580
581### errors (by type) ###
582
583- nosocket: couldn't establish socket
584- invaliddata: invalid JSON passed to socket
585
586dl
587--
588
589- loads a module or Zend extension at a given path
590- if a relative path is passed, it's relative to the extension_dir ini setting
591
592### attributes ###
593
594- extensiontype: "Zend extension" or "module"
595- name: the extension name
596- path: the path where it was loaded
597
598### errors (by type) ###
599
600- unsupported: dynamic extension loading is unsupported
601- relpath: relative path given, but no extension_dir defined
602- unknown: general error with internal DL_LOAD() (for message see msg attribute)
603- wrongapi: wrong Zend engine version (apineeded / apiinstalled attributes give information about the API versions)
604- wrongbuild: unmatched build versions (buildneeded / buildinstalled attributes give information about the build versions)
605- registerfailure: registering module failed
606- startupfailure: couldn't startup Zend extension / module
607- initfailure: couldn't initialize module
608- nophpso: passed shared object is not a valid Zend extension nor module
609
610- errors may have the module or extension attribute when their name is already known at the point of failure
611
612Other tags
613==========
614
615<signal>
616-----------
617
618- received caught signal
619
620### attributes ###
621
622- type: type of signal (e.g. SIGINT)
623
624### by type ###
625
626- SIGINT: interactive mode is entered...
627
628<watch*>
629-----------
630
631- generally emitted on hit watchpoint
632- <watchdelete variable="" />: when a variable was unset, the watchpoint is removed too
633- <watchhit variable="" />: when ever a watched variable is changed, followed by a <watchdata> container
634- <watchdata> may contain
635 - for watchpoints on variables:
636  - each of these <watch*> tags conatins a type attribute whose value is either "old" or "new")
637  - <watchvalue type="" inaccessible="inaccessible" />: old value is inaccessible
638  - <watchvalue type=""> may contain a <stream> element which indicates the old/new (type attribute) value of the variable
639  - <watchrefcount type="" refcount="" isref="" />: old/new (type attribute) refcount and isref, both numbers
640   - isref: if the value is 0, it's not a reference, else it is one
641 - for watchpoints on arrays:
642  - <watchsize> inspects size variations of an array (the sum):
643   - removed: number of elements removed
644   - added: number of elements added
645  - <watcharrayptr>: if this tag appears, the internal pointer of the array way changed
646
647<signalsegv>
648---------------
649
650- generally emitted when data couldn't be fetched (e.g. by accessing inconsistent data); only used in hard interrupt mode
651- it might mean that data couldn't be fetched at all, or that only incomplete data was fetched (e.g. when a fixed number of following attributes are fetched, this tag will mark a stop of fetching if none or not all tags were printed)
652