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 &quot;help&quot; 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 attribue 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 conatins 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)