<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.27 $ -->
 <appendix id="debugger">
  <title>Debugging PHP</title>

  <sect1 id="debugger-about">
   <title>About the debugger</title>
   <simpara>
    PHP 3 includes support for a network-based debugger.
   </simpara>
   <simpara>
    PHP 4 does not have an internal debugging facility.
    You can use one of the external debuggers though. The
    <ulink url="&url.zend.ide;">Zend IDE</ulink> includes
    a debugger, and there are also some free debugger extensions
    like DBG at <ulink url="&url.dbg;">&url.dbg;</ulink>, the 
    <ulink url="&url.apd;">Advanced PHP Debugger</ulink> (APD) or
    <ulink url="&url.xdebug;">Xdebug</ulink> which even has a compatible
    debugger interface as PHP 3's debugging functionality as is described
    in this section.
   </simpara>
  </sect1>

  <sect1 id="debugger-using">
   <title>Using the Debugger</title>

   <para>
    The internal debugger in PHP 3 is useful for tracking down
    evasive bugs. The debugger works by connecting to a
    <acronym>TCP</acronym> port for every time PHP 3 starts up.
    All error messages from that request will be sent to this
    TCP connection.  This information is intended for
    "debugging server" that can run inside an
    <acronym>IDE</acronym> or programmable editor (such as Emacs).
   </para>
   <para>
    How to set up the debugger:
    <orderedlist>
     <listitem>
      <simpara> 
       Set up a TCP port for the debugger in the <link
       linkend="configuration.file">configuration file</link> (<link
       linkend="ini.debugger.port">debugger.port</link>) and enable it
       (<link linkend="ini.debugger.enabled">debugger.enabled</link>).
      </simpara>
     </listitem>
     <listitem>
      <simpara> 
       Set up a TCP listener on that port somewhere (for example
       <command>socket -l -s 1400</command> on Unix systems).
      </simpara>
     </listitem>
     <listitem>
      <simpara> 
       In your code, run
       "debugger_on(<replaceable>host</replaceable>)", where
       <replaceable>host</replaceable> is the IP number or name of the
       host running the <acronym>TCP</acronym> listener.
      </simpara>
     </listitem>
    </orderedlist>
    Now, all warnings, notices etc. will show up on that listener
    socket, <emphasis>even if you turned them off with
    <function>error_reporting</function></emphasis>.  
   </para>
  </sect1>

  <sect1 id="debugger-protocol">
   <title>Debugger Protocol</title>
   <para>
    The PHP 3 debugger protocol is line-based. Each line has a
    <emphasis>type</emphasis>, and several lines compose a
    <emphasis>message</emphasis>. Each message starts with a line of
    the type <literal>start</literal> and terminates with a line of
    the type <literal>end</literal>. PHP 3 may send lines for different
    messages simultaneously.
   </para>
   <para>
    A line has this format:
    <informalexample>
     <programlisting>
<![CDATA[
date time host(pid) type: message-data
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    <variablelist>
     <varlistentry>
      <term><replaceable>date</replaceable></term>
      <listitem>
       <simpara>
        Date in ISO 8601 format
        (<replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>)
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>time</replaceable></term>
      <listitem>
       <simpara>Time including microseconds:
        <replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>uuuuuu</replaceable>
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>host</replaceable></term>
      <listitem>
       <simpara>
        DNS name or IP address of the host where the script error was
        generated.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>pid</replaceable></term>
      <listitem>
       <simpara>
        PID (process id) on <replaceable>host</replaceable> of the
        process with the PHP 3 script that generated this error.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>type</replaceable></term>
      <listitem>
       <para>
        Type of line. Tells the receiving program about what it
        should treat the following data as:
        <table>
         <title>Debugger Line Types</title>
         <tgroup cols="2">
          <thead>
           <row>
            <entry>Name</entry>
            <entry>Meaning</entry>
           </row>
          </thead>
          <tbody>
           <row>
            <entry><literal>start</literal></entry> 
            <entry>
             Tells the receiving program that a debugger message
             starts here. The contents of
             <replaceable>data</replaceable> will be the type of error
             message, listed below.
            </entry>
           </row>
           <row>
            <entry><literal>message</literal></entry>
            <entry>The PHP 3 error message.</entry>
           </row>
           <row>
            <entry><literal>location</literal></entry>
            <entry>
             File name and line number where the error occurred. The
             first <literal>location</literal> line will always
             contain the top-level location.
             <replaceable>data</replaceable> will contain
             <literal><replaceable>file</replaceable>:<replaceable>line</replaceable></literal>.
             There will always be a <literal>location</literal> line
             after <literal>message</literal> and after every
             <literal>function</literal>.
            </entry>
           </row>
           <row>
            <entry>
             <literal>frames</literal></entry> <entry>Number of frames
             in the following stack dump. If there are four frames,
             expect information about four levels of called functions.
             If no "frames" line is given, the depth should be assumed
             to be 0 (the error occurred at top-level).
            </entry>
           </row>
           <row>
            <entry>
             <literal>function</literal></entry> 
            <entry>
             Name of function where the error occurred. Will be
             repeated once for every level in the function call
             stack.
            </entry>
           </row>
           <row>
            <entry><literal>end</literal></entry> 
            <entry>
             Tells the receiving program that a debugger message ends
             here.
            </entry>
           </row>
          </tbody>
         </tgroup>
        </table>
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>data</replaceable></term>
      <listitem>
       <simpara>Line data.</simpara>
      </listitem>
     </varlistentry>
    </variablelist>

    <table>
     <title>Debugger Error Types</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Debugger</entry>
        <entry>PHP 3 Internal</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><errortype>warning</errortype></entry>
        <entry><errortype>E_WARNING</errortype></entry>
       </row>
       <row>
        <entry><errortype>error</errortype></entry>
        <entry><errortype>E_ERROR</errortype></entry>
       </row>
       <row>
        <entry><errortype>parse</errortype></entry>
        <entry><errortype>E_PARSE</errortype></entry>
       </row>
       <row>
        <entry><errortype>notice</errortype></entry>
        <entry><errortype>E_NOTICE</errortype></entry>
       </row>
       <row>
        <entry><errortype>core-error</errortype></entry>
        <entry><errortype>E_CORE_ERROR</errortype></entry>
       </row>
       <row>
        <entry><errortype>core-warning</errortype></entry>
        <entry><errortype>E_CORE_WARNING</errortype></entry>
       </row>
       <row>
        <entry><errortype>unknown</errortype></entry>
        <entry>(any other)</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    
    <example>
     <title>Example Debugger Message</title>
     <literallayout>
<![CDATA[
1998-04-05 23:27:400966 lucifer.guardian.no(20481) start: notice
1998-04-05 23:27:400966 lucifer.guardian.no(20481) message: Uninitialized variable
1998-04-05 23:27:400966 lucifer.guardian.no(20481) location: (null):7
1998-04-05 23:27:400966 lucifer.guardian.no(20481) frames: 1
1998-04-05 23:27:400966 lucifer.guardian.no(20481) function: display
1998-04-05 23:27:400966 lucifer.guardian.no(20481) location: /home/ssb/public_html/test.php3:10
1998-04-05 23:27:400966 lucifer.guardian.no(20481) end: notice
]]>
     </literallayout>
    </example>
   </para>
  </sect1>

 </appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->