php-src/sapi/phpdbg/xml.md

phpdbg XML format
=================

Common attributes
=================

severity
--------

- indicates the genre of phpdbg system output
- usually one of these values:
 - normal
 - notice
 - error

msgout
------

- 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" />)

req
---

- 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)

file
----

- refers to a filename

method
------

- format classname::methodname
- refers to a method

function
--------

- refers to a function

symbol
------

- either function or method (is method if "::" are present)

opline
------

- in hexadecimal format
- refers to a specific pointer to a (zend_)op

opcode
------

- refers to an opcode (ZEND_*)

type
----

- general attribute for most errors, describes the genre of the error

General tags
============

intro
-----

- appears on startup if -q flag wasn't provided as command line arg
- before any input possibility
- attributes may be spread over multiple tags
- wrapped in <intros> tag

### attributes ###

- version: current phpdbg version (as string)
- help: command name for help
- report: URL for bug reporting


phpdbg
------

- general text message output from phpdbg system

stream
------

- any output by PHP itself (e.g. <stream type="stdout">test</stream>)

### attributes ###

- type: stderr or stdout

php
---

- php error output

### attributes ###

- msg: the error message


General error tags
==================

command
-------

- general errors about commands

### possible attributes ###

- type
 - toomanyargs: more arguments than allowed
 - noarg: argument missing
 - wrongarg: wrong type of argument (e.g. letters instead of integer)
 - toofewargs: not enough arguments
 - notfound: command (or subcommand) doesn't exist
 - ambiguous: command was ambiguous
 - invalidcommand: command input is totally invalid
 - (nostack: should not happen: is an internal error)
 - (emptystack: should not happen: is an internal error)
- command: passed command
- subcommand: passed subcommand (present if the error is related to the subcommand)
- expected: count of expected arguments
- got: type of argument for type "wrongarg"
- num: if possible, information about which parameter had a wrong argument

inactive
--------

- by type
 - op_array: nothing was yet compiled (probably because no execution context set)
 - symbol_table: no symbol table present (not yet initiailized or already destructed)
 - noexec: not in execution
 - memory_manager: using the native memory manager (malloc, free, realloc) instead of e.g. the Zend MM
 - notfound: file not found
 - nocontext: execution context was not set (or compilation had failed)
 - isrunning: command requires no running script


Commands
========

export
------

- tag: <exportbreakpoint />
- usually triggered by successful export command
- may appear when cleaning to temporary store breakpoints
- errors by type
 - openfailure: could not create file

### attributes ###

- count: number of exported breakpoints

break / info break
------------------

- General tag for breakpoint creation, deletion and hits is "<breakpoint />"

### possible attributes ###

- id: the breakpoint id (if the leave command was executed, the id has the value "leave")
- num: the nth opline of a function/method/file
- add: has value "success"/"fail": a brekpoint was successfully/not added
- pending: the breakpoint is waiting for resolving (e.g. a file opline on a not yet loaded file)
- deleted: has value "success"/"fail": a breakpoint was successfully/not deleted
- eval: the condition on conditional breakpoints
- file
- opline
- opcode
- symbol
- function
- method
- line


- listing breakpoints always in a container element "<breakpoints>"
 - Child nodes:
  - function
  - method
  - file
  - opline
  - methodopline
  - functionopline
  - fileopline
  - evalfunction
  - evalfunctionopline
  - evalmethod
  - evalmethodopline
  - evalfile
  - evalopline
  - eval
  - opcode
 - attributes:
  - name: name of the symbol (function/method/file/opcode)
  - disabled: empty value if enabled, non-empty if enabled

- errors (by type)
 - exists: the breakpoint already exists
 - maxoplines: tries to break at an opline (usedoplinenum) higher than the number of present oplines (in maxoplinenum)
 - nomethod: method doesn't exist
 - internalfunction: one cannot break on an opline of an internal function
 - notregular: tries to set a breakpoint in not a regular file
 - (invalidparameter: should not happen: is an internal error)

frame
-----

- General tag for frames is "<frame>"
- always has id attribute; if it only has id attribute, it just indicates current frame number, no other elements follow
- may contain other elements (of type <arg>) when contained in <backtrace> tag
- <arg> always contains a <stream> element, the value of the variable

### possible attributes ###

- id: the frame id, current frame has id 0 (frames with internal function calls have the same id than their called frame)
- symbol ("{main}" is root frame)
- file
- line
- internal: has value "internal" when being an internal function call (one cannot inspect that frame)

- being an error: (by type)
 - maxnum: tried to access a frame with a number higher than existing (or < 0)

### attributes on <arg> ###

- variadic: has a non-empty value if the argument is variadic
- name: variable name of parameter

info (subcommands)
------------------

### break ###

- See above ("break / info break")

### files ###

- lists included files
- <includedfileinfo num="" /> with num having an integer value, indicating the number of included files
- <includedfile name=""/>: one per file, with name being the file path of the included file

### error ###

- gets last error
- <lasterror error="" (file="" line="") />
- error attribute contains the last error as a string, is empty if there's no last error

### vars / globals ###

- <variableinfo num="" /> with num having an integer value, indicating the number of (local or superglobal) variables
- if info vars was used it'll have also one of these attributes:
 - method
 - function
 - file
 - opline
- for each variable there is a <variable> followed by a <variabledetails> element
- <variable address="" refcount="" type="" name="" />
 - address: pointer to zval (hexadecimal)
 - refcount: refcount of zval
 - type: the variable type (long, string, ...). If the value is "unknown", the other attributes are meaningless
 - name: the name of the variable
 - refstatus: empty if the zval is not a reference
 - class: the class the object in the zval is an instance of
 - resource: the type of the resource in the zval

### literal ###

- <literalinfo num="" /> with num having an integer value, indicating the number of literals, optional arguments are:
 - method
 - function
 - file
 - opline
- for each literal there is a <literal> followed by a <stream type="stdout"> which prints the value of the literal
- <literal id="" />: where id is the internal identifier of the literal

### memory ###

- Format:

    <meminfo />
    <current />
    <used mem="" />
    <real mem="" />
    <peak />
    <used mem="" />
    <real mem="" />

- mem is an attribute whose value is a float. The memory is given in kilobytes (1 kB == 1024 bytes)

### classes ###

- <classinfo num="" /> with num having an integer value, indicating the number of loaded user-defined classes
- Each class is enumerated with first a <class>, then an optional <parents> container and then a <classsource> element
- The <parents> container contains the <class> elements of the parent of the last <class> element.
- <class type="" flags="" name="" methodcount="" />
 - type: either "User" or "Internal"
 - flags: either "Interface", "Class" or "Abstract Class"
- <classsource /> where the class was defined, if there are no attributes, location is unknown, usually defined by
 - file
 - line

### funcs ###

- <functioninfo num="" /> with num having an integer value, indicating the number of loaded user-defined functions
- Each class is enumerated with first a <function> and then a <functionsource> element
- <function name="" />
- <functionsource /> where the function was defined, if there are no attributes, location is unknown, usually defined by
 - file
 - line

list
----

- consists of <line> elements wrapped in a <list> container
- <list file=""> is the container element with file being the filename
- <line line="" code="" /> with value of code being the whole line of code in the line specified in the line attribute
 - current: this attribute is set to "current" if that line is the line where the executor currently is

print
-----

### without a subcommand ###

- <print> elements are wrapped in a <printinfo> element
- there may be a variable number of <print> elements with a variable count of args inside the <printinfo> element
- possible args are:
 - readline: yes/no - readline enabled or disabled
 - libedit: yes/no - libedit enabled or disabled
 - context: current executing context
 - compiled: yes/no - are there actual compiled ops?
 - stepping: @@ TODO (meaningless for now) @@
 - quiet: on/off - should it always print the opline being currently executed?
 - oplog: on/off - are oplines logged in a file?
 - ops: number of opcodes in current executing context
 - vars: number of compiled variables (CV)
 - executing: yes/no - in executor?
 - vmret: the return value of the last executed opcode
  - default: continue
  - 1: return from vm
  - 2: enter stack frame
  - 3: leave stack frame
 - classes: number of classes
 - functions: number of functions
 - constants: number of constants
 - includes: number of included files

### with a subcommand ###

- introduced by <printinfo num="" /> (except for print opline) with num being the number of opcodes and one of these args:
 - file
 - method
 - function
 - class (then also type and flags attributes, see info classes command for their meanings)
 - symbol (also type and flags attributes; here the value of flags is either "Method" or "Function")
- if there is a class method, the methods are all wrapped in a <printmethods> container
- then comes a <printoplineinfo type="" /> where type is either "User" or "Internal"
- the <printoplineinfo> has either a method or a function attribute
- if the type is "Internal"
 - there are no oplines, it's an internal method or function
- if the type is "User"
 - it has these attributes
   - startline: the first line of code where the method or function is defined
   - endline: the lastt line of code where the method or function is defined
   - file: the file of code where the method or function is defined
 - is followed by the oplines of that method or function (<print> elements)
- <print line="%u" opline="%p" opcode="%s" op="%s" />
- in case of print opline it emits a single <opline line="" opline="" opcode="" op="" file="" />

exec
----

- command executing and compiling a given file
 - <exec type="unset" context="" />: indicates unsetting of the old context
 - <exec type="unsetops" />: indicates unsetting of the old compiled opcodes
 - <exec type="unchanged" />: same execution context chosen again
 - <exec type="set" context="" />: indicates setting of the new context
- errors by tag
 - <compile>
  - openfailure: couldn't open file
  - compilefailure: The file indicated in context couldn't be compiled
 - <exec>
  - invalid: given context (attribute) is not matching a valid file or symlink
  - notfound: given context (attribute) does not exist

run / <stop> tag
-------------------

- runs the script (set via exec command)
- <stop type="end" />: script execution ended normally
- (error) <stop type="bailout" /> the VM bailed out (usually because there was some error)
- compile failures see under exec, errors, <compile>

step
----

- steps by one line or opcode (as defined via set stepping) default is one line
- returns back to the executor

continue
--------

- returns back to the executor

until
-----

- temporarily disables all the breakpoints on that line until that line was left once
- returns back to the executor

finish
------

- temporarily disables all the breakpoints until the end of the current frame
- returns back to the executor

leave
------

- temporarily disables all the breakpoints past the end of the current frame and then stops
- returns back to the executor

back
----

- prints backtrace
- see frame command

ev
--

- eval()uates some code
- output wrapped in <eval> tags

sh
--

- executes shell command
- still pipes to stdout ... without wrapping <stream> !!! (@@ TODO @@)

source
------

- executes a file in .phpdbginit format
- errors by type
 - notfound: file not found

register
--------

- registers a function to be used like a command
- <register function="" />: successfully registered function
- errors by type
 - notfound: no such function
 - inuse: function already registered

quit
----

- quits phpdbg
- if successful connection will be closed...

clean
-----

- cleans environment (basically a shutdown + new startup)
- <clean> tags wrapped in a <cleaninfo> container
- possible attributes of <clean> tag
 - classes: number of classes
 - functions: number of functions
 - constants: number of constants
 - includes: number of included files

clear
-----

- removes all breakpoints
- <clear> tags wrapped in a <clearinfo> container
- possible attributes of <clear> tag (value is always the number of defined breakpoints of that type)
 - files
 - functions
 - methods
 - oplines
 - fileoplines
 - functionoplines
 - methodoplines
 - eval

watch
-----

- watchpoints generally are identified by a variable (one may need to switch frames first...)
- <watch variable="" />, <watchrecursive variable="" /> and <watcharray variable="" /> (normal, array, recursive)
- <watch> if error, by type:
 - undefined: tried to set a watchpoint on a not (yet) defined variable
 - notiterable: element which is tried to be accessed as an object or array is nor array nor object
 - invalidinput: generally malformed input
- <watchdelete variable="" />: when "watch delete" was used on a watchpoint
- (error) <watchdelete type="nowatch" />: that watchpoint doesn't exist, so couldn't be deleted
- for hit watchpoints etc., see Other tags, <watch*>
- when using watch list, <watchvariable> elements are wrapped in a <watchlist> container
 - <watchvariable variable="" on="" type="" />
  - variable: watched variable (may be a variable of another scope!)
  - on: values are array or variable, depending on what is watched
  - type: values are recursive or simple, depending on whether the watchpoint is checked recursively or not

set
---

- a general error is type="wrongargs" where a wrong argument was passed to a subcommand; tag is then <set*>

### prompt ###

- without other args, a <setpromt str="" /> tag is emitted where the value of the str attribute is the value of the prompt
- when there is another arg, the prompt is changed to that arg, no further xml answer

### break ###

- enables / disables a given breakpoint silently with no further xml answer
- if the boolean switch is omitted, it emits current state in a <setbreak id="" active="" /> where active is on or off
- error with type="nobreak", when no breakpoint with the given id exists

### breaks ###

- generally enables / disables breakpoint functionality silently with no further xml answer
- if the boolean switch is omitted, it emits current state in a <setbreaks active="" /> where active is on or off

### color ###

- sets the color on prompt, error or notices
- <setcolor type="" color="" code="" />: code is the color code of color, type is either:
 - prompt
 - error
 - notice
- errors by type:
 - nocolor: color doesn't exist
 - invalidtype: type wasn't one of the three allowed types

### colors ###

- generally enables / disables colors silently with no further xml answer
- if the boolean switch is omitted, it emits current state in a <setcolors active="" /> where active is on or off

### oplog ###

- sets oplog
- (error) <setoplog type="openfailure" file="" /> when it couldn't open the passed file path
- <setoplog type="closingold" /> is emitted when there was a previous open oplog (and a file is passed)
- if no further argument is passed, it emits current state in a <setoplog active="" /> where active is on or off

### quiet ###

- generally enables / disables quietness silently with no further xml answer
- if the boolean switch is omitted, it emits current state in a <setquiet active="" /> where active is on or off

### setpping ###

- sets stepping to either opcode or line (so a step command will either advance one op or one line)
- if no further argument is passed, it emits current state in a <setoplog type="" /> where active is opcode or line

### refcount ###

- generally enables / disables showing of refcount in watchpoint breaks silently with no further xml answer
- if the boolean switch is omitted, it emits current state in a <setrefcount active="" /> where active is on or off

wait
----

- internally executes exec, so exec will output first (if binding to socket worked)

### attributes ###

- import: has value "success"/"fail"
- missingmodule/missingextension: modules/extensions loaded in the target SAPI, but not in phpdbg

### errors (by type) ###

- nosocket: couldn't establish socket
- invaliddata: invalid JSON passed to socket

dl
--

- loads a module or Zend extension at a given path
- if a relative path is passed, it's relative to the extension_dir ini setting

### attributes ###

- extensiontype: "Zend extension" or "module"
- name: the extension name
- path: the path where it was loaded

### errors (by type) ###

- unsupported: dynamic extension loading is unsupported
- relpath: relative path given, but no extension_dir defined
- unknown: general error with internal DL_LOAD() (for message see msg attribute)
- wrongapi: wrong Zend engine version (apineeded / apiinstalled attributes give information about the API versions)
- wrongbuild: unmatched build versions (buildneeded / buildinstalled attributes give information about the build versions)
- registerfailure: registering module failed
- startupfailure: couldn't startup Zend extension / module
- initfailure: couldn't initialize module
- nophpso: passed shared object is not a valid Zend extension nor module

- errors may have the module or extension attribute when their name is already known at the point of failure

Other tags
==========

<signal>
-----------

- received caught signal

### attributes ###

- type: type of signal (e.g. SIGINT)

### by type ###

- SIGINT: interactive mode is entered...

<watch*>
-----------

- generally emitted on hit watchpoint
- <watchdelete variable="" />: when a variable was unset, the watchpoint is removed too
- <watchhit variable="" />: when ever a watched variable is changed, followed by a <watchdata> container
- <watchdata> may contain
 - for watchpoints on variables:
  - each of these <watch*> tags contains a type attribute whose value is either "old" or "new")
  - <watchvalue type="" inaccessible="inaccessible" />: old value is inaccessible
  - <watchvalue type=""> may contain a <stream> element which indicates the old/new (type attribute) value of the variable
  - <watchrefcount type="" refcount="" isref="" />: old/new (type attribute) refcount and isref, both numbers
   - isref: if the value is 0, it's not a reference, else it is one
 - for watchpoints on arrays:
  - <watchsize> inspects size variations of an array (the sum):
   - removed: number of elements removed
   - added: number of elements added
  - <watcharrayptr>: if this tag appears, the internal pointer of the array way changed

<signalsegv>
---------------

- generally emitted when data couldn't be fetched (e.g. by accessing inconsistent data); only used in hard interrupt mode
- 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)