1 files changed, 651 insertions, 0 deletions

diff --git a/sapi/phpdbg/xml.md b/sapi/phpdbg/xml.md
new file mode 100644
index 0000000000..7871b31376
--- /dev/null
+++ b/sapi/phpdbg/xml.md
@@ -0,0 +1,651 @@
+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 heigher 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 choosen 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 futher 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)