X-Git-Url: http://git.phpeclipse.com diff --git a/net.sourceforge.phpeclipse.help/docbook-src/guide/src/en/user-manual/debug_php.xml b/net.sourceforge.phpeclipse.help/docbook-src/guide/src/en/user-manual/debug_php.xml new file mode 100644 index 0000000..7e10cf0 --- /dev/null +++ b/net.sourceforge.phpeclipse.help/docbook-src/guide/src/en/user-manual/debug_php.xml @@ -0,0 +1,703 @@ + + + + + + + PHP Source Level Debugging + + Besides the method of outputting runtime information by adding echo or var_dump functions to your code, the more sophisticated and convenient method is using a so called Source Level Debugger. + + + + With the current release of &phpeclipse; only DBG is supported. XDebug is currently supported only by directly checking out from the &phpeclipse; CVS repository and setting it up appropriately (see ). + + + + In case you havn't already installed DBG, see . When you are sure the DBG module is correctly installed, you can go forward. + + + + To do debugging in &phpeclipse; you need to set up a so called Debug Configuration. The following sections describe how to set up such a Debug Configuration and how to start a debug session. + + + + Setting up a Debug Configuration + + To set up a Debug Configuration click on + + Run + Debug... + (see . Within the opened dialog click on PHP DBG Script and click on New (see ). This opens the Create, manage, and run configuration dialog. + + + + + The first time you open the configuration dialog, you will see an error message within this dialog, complaining about a missing interpreter setting. For entering the interpreter see . + + + +
+ Open the Debug Configuration dialog + + + + + + + + +
+ +
+ Debug Configuration with the <quote>Perspectives</quote> view + + + + + + + + +
+ + + + Name the Debug Configuration + + Within the Name: text field you should change the name (which is New_configuration per default) to a more reasonable one (see ). + + + + + + Configure File + + Within the File tab you find two entries: + + + + Project: This is the project this debug configuration belongs to. + + + + + File: This is used for Non Remote Debugging. The given file is directly given the interpreter which is entered within the Interpreter tab (see ). And/or is it called when configured for using the internal browser. + + + + + +
+ Set up Debug Configuration - File + + + + + + + + +
+ + + + + Configure Arguments + + These settings are used for Non Remote Debugging. If the given Interpreter is directly called by &phpeclipse; (see ). + + + + + + Working Directory: + + + + + Use default working directory: + + + + + Interpreter Arguments: Here you can specify the arguments which will passed to the interpreter (see Using PHP from the command line). + + + + + Program Arguments: Here you can specify the arguments which will be passed to your script, and can be accessed by the $argv[] - array. + + + + + + + + Configure Environment + + Within this tab you have to enter the most important settings for a successful debugging session. + + + + + Configure Environment Interpreter + + Although the setting of the interpreter isn't really necessary for Remote Debugging, you have to set it up. For a default XAMPP installation this would be C:\Program Files\apachefriends\xampp\php\php.exe. + + + + The interpreter is used when you set a Debug Configuration with Remote Debug deactivated. This is true if you want to debug a script which is started per php cli. + + + + + + Configure Environment Remote Debug + + Here can you have up to five options to enter: + + + + Remote Debug: You activate this if you want to debug a script which is started from an external browser (this is in opposite of the usage of the browser which is build into &phpeclipse;). When you disable this checkbox the appropriate script is forwarded directly to the given interpreter (php.exe) + + + + + Cross Platform debugging: Originally used for converting the path seperator (which are different on *nix and Windows systems). As far as I can remember this isn't necessary anymore. + + + + + Open with DBGSession URL in internal Browser: Activate this if you don't want to use the an external browser but start a debug session in internal browser. + + + + + Remote Sourcepath: An incorrect setting of this path information is responsible for the most annoyances in respect of debugging problems. The Remote Sourcepath is important because it is used for translating the path informations which are exchanged between &phpeclipse; and DBG. So, if this translation is incorrect, &phpeclipse; will not find the correct file when a break occurs, nor will DBG know for which file it should set a breakpoint. More different and detailed examples are to come: + + + + + Mapped Path: Although in most cases a single path mapping is sufficient, but there are situations where this isn't enough. This is when you use PHP files (e.g. phplib) which are located on a total different path. To use this option, it is necessary to leave the Remote Sourcepath field empty. More different and detailed examples are to come: + + + + + + + + + + Configure Environment Variables + + Used within Non Remote Debugging. You can specify variable - value pairs which are passed to the script within the $_ENV and the $HTTP_ENV_VARS array. + + + + + + Configure Common + + Leave all as it is per default. + + + + + Save Configuration + + When you have done all the necessary settings click on Apply to save the configuration. You can recall this configuration by clicking on the name of the desired configuration in the Configurations pane on the left side. + + + + + Start a Debug Configuration + + You can start a Debug Configuration at once within the configuration dialog via the Debug. + + + + + + + + + Remote Debugging + + It is called Remote Debugging if you want to debug php scripts which are started by web server. This is the case if you are doing so called Web Devolepment. In opposite you also can write php scripts and start them from a shell or command line (see ). + + + + + + + + + + + Debugging CLI + + In contrary to Remote Debugging where your php scripts are started by a web server, you could also write scripts and start them from command linecli stands for Command Line Interface. For that task you have to deactivate the Remote Debug checkbox (see ), and set the appropriate php cli application. According the PHP version you use, this is: + + + + phpcli.exe for PHP 4 + + + + + php-win.exe for PHP 5 + + + + + + + The prerequiste for debugging is also that you have installed &dbg; as it is described in . In addition, for the breakpoints to work, you have to add the following line to the [debugger] section of your php.ini: + + And also you need the following code at the top of your php file you want to debug. At least this code snippet should be located before the first breakpoint you want to set. + + + + + + For debugging a php-cli script you need the appropriate &phpeclipse; version, which is > phpeclipse-1.1.9-cvs-20060424. This is due to the fact that older &phpeclipse; versions listen on port 10001, but dbg uses the standard port 7869, and there is no way to submit a different port neither by cli nor through the php.iniThis is true for the free &dbg; version.. + + + + + + If you don't want to change the php.ini which you also do use for your web scripts, you can import the appropriate php.ini to your project, and modify this project related local copy of the php.ini file. To use this local php.ini set the Interpreter Argument (see ) as follows: + -c your_project_name/php.ini. + + + + + + Debug Scenarios + + One of the most important configuration point which is responsible for successfully debugging your PHP code is the correct setting of the Remote Sourcepath. Without a correct setting, you wan't be able to run a debugging session. As the setting of the &remso; is dependent of your working environment, we will first explain why it is needed and how it works and then, we will provide some examples. + + + + How the &remso; works + + Why do we need a &remso; setting? All files are defined by the path relative to the current &eclipse; workspace and project. E.g our workspace is C:\Document and Settings\Robert\workspace. Within this workspace we have a PHP project called MyPHPProject and a file MyPHPFile.php. From &dbg; this file would be reported as C:\Document and Settings\Robert\workspace\MyPHPProject\MyPHPFile.php. The &remso; is now used to remove the full path, so we get a file with a relative path, which would be in this case the filename itself. + + + + In this example the &remso; setting would be C:\Document and Settings\Robert\workspace\MyPHPProject. This is by the way the default setting of the &remso; when you create a new debug configuration. But this setting is only correct if your the webservers &docroot; is set to exactly this folder. + + + + + Same Machine, Workspace is &docroot; + + + + + + + Same Machine, Workspace and &docroot; is Different + + + + + + + + Different Machine, Workspace and &docroot; is Different + + + + + + + + + Running a Debug Session + + Open Debug perspective. Select a existing debug configuration. Or create a new one. Should see following in Debug View. + Internal Browser or external browser. Submit URL in external browser. + + + + + Resume + + + + + + + + Suspend + + + + + + + Terminate + + + + + + + Step Into + + + + + + + Step Into + + + + + + + Step Return + + + + + + + + Breakpoints + + + + + +
+ The &bpview; + + + + + + + + +
+ + +
+ The &bpview; context menu + + + + + + + + +
+ + +
+ The &bpview; icon bar + + + + + + + + +
+ + +
+ The &editview; left ruler context menu + + + + + + + + +
+ + + + Set Breakpoint + + A breakpoint can be set by the following methods: + + + + By double clicking within the left vertical ruler of the editor window + + + + + Via the left vertical ruler context menu item Toggle PHP Breakpoint (see ) + + + + + + + + + Remove Breakpoint + + A breakpoint can be removed by the following methods: + + + + By double clicking within the left vertical ruler of the editor window + + + + + Via the left vertical ruler context menu item Toggle PHP Breakpoint (see ). + + + + + Via the &bpview;, by simple typing Del + + + + + Via the &bpview; context menu item Remove (see ) + + + + + Via the &bpview; icon bar Remove icon (see ). + + + + + + + + + Enable/Disable Breakpoint + + A breakpoint can temporary disabled (and enabled) by the following methods: + + + + By clicking into the check box of the appropriate breakpoint within the &bpview; (see + + + + + Via the &bpview; context menu item Disable (and enabled via Enable) (see ). The context menu commands are related to all selected breakpoints. + + + + + + + + + Conditional Breakpoints + + You can assign a condition to a breakpoint via the &bpview; context menu item Properties (see ). This opens a dialog (see ). Within the text field Break Condition you can set a condition. Don't forget to activate the conditional break via the check box Enable Condition at the bottom of the dialog. + + + For example, if you type $a == 12 as condition, the program will break if the variable $a has the value 12. + + + +
+ The breakpoint <quote>Properties</quote> dialog + + + + + + + + +
+ + + + Breakpoint Skipcounts + + An additional feature to set for breakpoints is the Skipcounts condition. Normally the skipcounts is set to 0, which means the program breaks immediately if it scores a breakpoint. If the Skiptcounts is set to 1 it means, that the first score of a breakpoint is ignored (skipped) and the second score will lead to a break of the program. + + + + The Skipcounts can be set via the same dialog box as the conditional breakpoints (see ). For the Skipcounts the checkbox need not to be activated. + + + + + The Break Condition has precedence over the Skipcounts. + + + + + + + + + Inspect Variables + + Within the Variables View you can see all the variables with their values. + + + To open the Variables View within the Debug Perspective go to + + Window + Show View + Variables + (see ). + + + + + Be sure that your current perspective is the Debug Perspective. Although you can open the Variable View within a different perspective, this doesn't make sense. + + + + +
+ Open the &varview; + + + + + + + + +
+ + +
+ The &varview; context menu + + + + + + + + +
+ + + + + + Show Variable Value by Hovering + + Besides inspecting the value of a variable by looking into the &varview; or the &expview; a simple and quick method is to position the mouse pointer over the variable within the source code. Within a second the value and type of the variable is shown (see ). + + + +
+ Show variable value by hovering + + + + + + + + +
+ + + + + Watch Expressions + + Within the &expview; you can see the result of an expression. In the simplest form, this is just a variable and the corresponding value. But of course an expression can also be more complex, e.g. a mathematical formula. + + + There are different ways to open the Expressions View and to add an expression. + + + + + Open &expview; via Main Menu + + To open the &expview; within the Debug Perspective go to + + Window + Show View + Variables + (see ). + + + + + Be sure that your current perspective is the Debug Perspective. Although you can open the &expview; within a different perspective, this doesn't make sense. + + + + +
+ Open the &expview; via the main menu + + + + + + + + +
+ + + + Open &expview; via the &varview; + + Right clicking on a variable within the &varview; opens the context menu. Then click on Create Watch Expression. This adds the selected variable to the &expview; and opens/activates the &expview;. + + + Window + Show View + Variables + (see ) + + + +
+ Open the &expview; via the &varview; context menu + + + + + + + + +
+ + + + + Open &expview; via context menu + + Unfortunately, yet this isn't implemented. + + + + + Remove a watch expression + + An expression can be removed from the &expview; by activating the appropriate watch expression and typing Del or via the context menu Remove. + + + + + + +