net.sourceforge.phpeclipse.help/docbook-src/guide/src/en/user-manual/install_debugger.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- jEdit buffer-local properties: -->
   3 <!-- :indentSize=2:noTabs=true: -->
   4 <!-- :xml.root=docmaster.xml: -->
   5
   6 <sect1 id="sec.install_debugger">
   7   <title>Installing Debugger</title>
   8   <para>
   9     At the moment only DBG is supported by the standard &phpeclipse; release. <application>XDEBUG</application> is only supported by loading the appropriate sources via CVS.
  10   </para>
  11
  12
  13   <sect2 id="sec.install_dbg">
  14     <title>Installing <application>DBG</application></title>
  15     <para><indexterm><primary>install</primary><secondary>DBG</secondary></indexterm>
  16       DBG is a full-featured php debugger engine, an interactive tool that helps you debug PHP scripts. It works with a production and/or development web server and allows you to debug your scripts locally or remotely, from an IDE or the console. &phpeclipse; has a built-in, pure Java debugging client that operates the DBG debugging engine.
  17     </para>
  18
  19     <para>
  20       To get the debugger to work you need to install the debugger engine to run in the PHP interpreter, and configure the debugger client to communicate with the engine.
  21     </para>
  22
  23     <para>
  24       Make sure you download the appropriate DBG binaries for your OS and your release of PHP (from 4.0.6 up to 4.3.10 and from 5.0.0 up to 5.0.3) (Note that the 5.0.3 debugger binary seems to work for the 5.0.4 and 5.05 interpreters.) If you are using Mac OS X you will have to build the debugger from source.
  25     </para>
  26
  27
  28     <sect3 id="sec.find_dbg_dll">
  29       <title>Getting the right php_dbg.dll</title>
  30       <para>
  31         DBG can be downloaded from <ulink url="http://dd.cron.ru/dbg/downloads.php">DBG&nbsp;Downloads</ulink>. You need to download the dbg modules packet for the appropriate operating system. Unpack the zipped packet and  take the dll (or so) file which matches the PHP version you have currently running. E.g. for PHP 5.1.2 the correct file is <filename>php_dbg.dll-5.1.2</filename>. Rename the appropriate file to <filename>php_dbg.dll</filename> and read <xref linkend="sec.find_extension_dir"/> to find out the right destination location for the file.
  32       </para>
  33     </sect3>
  34
  35
  36     <sect3 id="sec.find_extension_dir">
  37       <title>Find the extension directory</title>
  38
  39       <para>
  40         The best way to find out is via the <quote>phpinfo()</quote> command. Create a PHP-file called <filename>phpinfo.php</filename> with the following content:
  41         <programlisting><![CDATA[<?php phpinfo(); ?>]]></programlisting> and start it via your web browser. Then search for <quote>extension_dir</quote>. The right column shows the path to the directory where you have to place the <filename>php_dbg.dll</filename> (see <xref linkend="fig.extension_dir"/>).
  42       </para>
  43
  44       <figure id="fig.extension_dir">
  45         <title>The information about the extension directory</title>
  46         <mediaobject>
  47           <imageobject role="html">
  48             <imagedata align="center" fileref="img/en/xo-002/extension_dir_1.png" format="PNG"/>
  49           </imageobject>
  50           <imageobject role="fo">
  51             <imagedata align="center" fileref="img/en/xo-002/extension_dir_1.png" format="PNG" width="12cm"/>
  52           </imageobject>
  53         </mediaobject>
  54       </figure>
  55     </sect3>
  56
  57
  58     <sect3 id="sec.install_dbg_php_ini">
  59       <title>Setup &phpini;</title>
  60       <para>
  61         Where is the &phpini; which needs to be set up?
  62       </para>
  63
  64       <para>
  65         The simplest way to find out the path of the &phpini; is again with the help of the phpinfo function as described in <xref linkend="sec.find_extension_dir"/>
  66       </para>
  67
  68       <tip>
  69         <para>
  70           Another possibility to find out where an application searches specific files is by using a tool called <application>Filemon</application> which you can get from <ulink url="http://www.sysinternals.com">Sysinternals</ulink>.
  71         </para>
  72       </tip>
  73
  74       <para>
  75         The resulting output shows the path of the &phpini; file within the topmost header. See <xref linkend="fig.php_ini_path"/>
  76       </para>
  77
  78       <para>
  79         Now open <filename>php.ini</filename> and search for <quote>implicit_flush</quote>, and set it to <quote>On</quote>.
  80         <programlisting><![CDATA[; this is to see output while debugging
  81 implicit_flush = On]]> </programlisting>
  82       </para>
  83
  84       <para>
  85         copy the following lines into <filename>php.ini</filename> (they can go at the end of the file). For linux it is a php_dbg.so instead of php.dbg.dll.
  86         <programlisting><![CDATA[
  87 [debugger]
  88 extension=php_dbg.dll
  89 debugger.enabled=on
  90 debugger.profiler_enabled=on
  91 debugger.hosts_allow=localhost
  92 debugger.hosts_deny=ALL
  93 debugger.ports=7869, 10000/16
  94 ]]></programlisting>
  95       </para>
  96
  97       <para>
  98         Disable <ulink url="http://eaccelerator.net">eAccelerator</ulink> if it is installed and enabled:
  99         <programlisting><![CDATA[eaccelerator.enable="0"]]></programlisting>
 100       </para>
 101
 102       <para>
 103         Disable the <ulink url="http://xdebug.org/">Xdebug</ulink> extension if installed (usually via pear) by commenting out
 104         <programlisting><![CDATA[;zend_extension=/usr/lib/php4/20020429/xdebug.so]]></programlisting>
 105       </para>
 106       <para>
 107         Also if you have Zend Extension Manager installed (You should find a [Zend] section) make sure you add this line before any other zend_extension_ts (windows) or zend_extension (linux) lines: For Windows:
 108         <programlisting><![CDATA[zend_extension_ts = "C:\path\to\php_dbg.dll"]]></programlisting>
 109         For linux:
 110         <programlisting><![CDATA[zend_extension=/var/lib/php4/dbg.so]]></programlisting>
 111       </para>
 112
 113       <para>
 114         Restart web server
 115       </para>
 116
 117       <figure id="fig.php_ini_path">
 118         <title>Get the &phpini; path</title>
 119         <mediaobject>
 120           <imageobject role="html">
 121             <imagedata align="center" fileref="img/en/xo-002/phpinfo_php_ini.png" format="PNG"/>
 122           </imageobject>
 123           <imageobject role="fo">
 124             <imagedata align="center" fileref="img/en/xo-002/phpinfo_php_ini.png" format="PNG" width="12cm"/>
 125           </imageobject>
 126         </mediaobject>
 127       </figure>
 128     </sect3>
 129
 130
 131     <sect3 id="sec.install_dbg_test">
 132       <title>Test the DBG Installation</title>
 133       <para>
 134         When you have done all steps, restart your web server and again submit the <function>phpinfo</function> function as described in <xref linkend="sec.find_extension_dir"/>. Search the browser output for <quote>dbg</quote> and you should find a section like you can see in <xref linkend="fig.test_dbg"/>
 135       </para>
 136
 137       <figure id="fig.test_dbg">
 138         <title>phpinfo showing the DBG section</title>
 139         <mediaobject>
 140           <imageobject role="html">
 141             <imagedata align="center" fileref="img/en/xo-002/phpinfo_dbg_section.png" format="PNG"/>
 142           </imageobject>
 143           <imageobject role="fo">
 144             <imagedata align="center" fileref="img/en/xo-002/phpinfo_dbg_section.png" format="PNG" width="12cm"/>
 145           </imageobject>
 146         </mediaobject>
 147       </figure>
 148
 149       <para>
 150         In addition you can submit the following URL within your browser: <ulink url="http://localhost/index.php?DBGSESSID=1@localhost:10001"></ulink>. Now, as there is no client running listening to dbg, you should see the following error message
 151       </para>
 152
 153       <figure id="fig.dbg_error">
 154         <title>DBG Error Message</title>
 155         <mediaobject>
 156           <imageobject role="html">
 157             <imagedata align="center" fileref="img/en/xo-002/dbg_error.png" format="PNG"/>
 158           </imageobject>
 159           <imageobject role="fo">
 160             <imagedata align="center" fileref="img/en/xo-002/dbg_error.png" format="PNG" width="8cm"/>
 161           </imageobject>
 162         </mediaobject>
 163       </figure>
 164
 165       <note>
 166       <para>
 167         For setting up a debug configuration and doing real debugging with &phpeclipse;, see <xref linkend="sec.debug_php" />.
 168       </para>
 169       </note>
 170
 171
 172     </sect3>
 173   </sect2>
 174
 175
 176   <sect2 id="sec.install_xdebug">
 177     <title>Installing <application>XDEBUG</application></title>
 178     <para><indexterm><primary>install</primary><secondary>XDEBUG</secondary></indexterm>
 179       The XDebug support is only available through direct checkout of the &phpeclipse; CVS repository.
 180     </para>
 181
 182     <para> <!-- todo: Get info from wiki -->
 183       More to come.
 184     </para>
 185   </sect2>
 186 </sect1>