Debugger

From HTML5 Builder
Jump to: navigation, search

The Debugger allows you to control the execution flow of your application, and watch and modify its data, so you can locate the source of any logic or runtime error in your application, so you can fix it.

Execution Flow

With the debugger you can control the execution flow of your application. Instead of running your whole script at once, you can take the execution flow line by line, stopping the flow whenever you want, wherever you want, so you can check whether the data of your application is at every moment what you expect it to be, or if at some point something unexpected happens.

You can control you application’s execution flow with basic commands or, if you need more advanced features, you can use breakpoints on top of that.

Note: Script output will not be visible on the web browser until the execution completely finishes.

Basic Commands

To start execution flow control, you can:

  • To run the script and stop execution flow at the first line of code, go to Run > Step Over or Run > Trace Into.
  • To run the script and stop execution flow at a custom line, place the text cursor at that line (just click on it) and go to Run > Run to Cursor.

    Note: To stop execution flow at a line on a script other than the script where execution starts, set the later as main script.

You can continue the execution flow with any of the following commands:

  • Run > Step Over. Stops at the next line of code, either on the current script, or on the script from which the current one was called.
  • Run > Trace Into. If execution flow is currently at a function call or an include function (for example: require_once()), it will be taken to the other script, be it the one where the called function is defined, or the one which has been included.
  • Run > Run to Cursor. Execution flow will stop at the line where the text cursor is located.

    Note: In case the cursor is located on any line before the one where the execution flow currently is, execution will finish.

To stop the execution flow control and finish running the application, go to Run > Program Reset.

If at some point you are not sure of where the execution flow currently is stopped at (execution point), Run > Show Execution Point will take you there.

Breakpoints

Breakpoints let you select lines of code where execution flow should stop. But you can also set conditions that must be matched for a breakpoint to stop the execution flow, as well as an amount of times the breakpoint will be ignored. In combination with the basic execution flow control commands and data watching, breakpoints are the definitive tool to locate the source of code errors.

Manage

Tip: You can use the Gutter and the Breakpoint List as alternative tools to manage breackpoints. The later lets you do it in a centralized way, and take advantage of breakpoint groups.

To start execution flow until the first breakpoint is reached, go to Run > Run. To continue execution flow until the next breakpoint, go to Run > Run again.

To add a breakpoint to any line of any script:

  1. Go to Run > Add Breakpoint….
  2. Enter any properties you want, Filename and Line number fields are mandatory.
  3. Click OK.

To remove a breakpoint, follow the steps to add one to a line where a breakpoint already exists.

You can alternatively right-click on the target line, and go to Debug > Toggle Breakpoint to either add or remove a breakpoint.

Properties

Breakpoint properties.

Every breakpoint has the following properties:

  • Filename: Path to the script where the breakpoint is located.
  • Line number: Number of the line in which the breakpoint is located. There can only be one breakpoint per line.
  • Condition: A PHP expression which will be evaluated whenever the execution flow reaches the breakpoint. Execution flow will then be stopped only if the expression returns true.
  • Pass count: The amount of times the breakpoint will not stop the execution flow until it finally does. For example, if you place a break with a Pass count of 10 inside a for loop, the breakpoint will be ignored the first 10 times, and it will stop the execution flow on the eleventh time. You can combine this property with a Condition, so the breakpoint ignores the given amount of condition matches before stopping the execution flow.
  • Group: Name of the group the breakpoint belongs to. Grouping breakpoints will let you, thorugh the Breakpoint List, disable, enable or remove whole groups of breakpoints at once.

If you want to modify any of those on an existing breakpoint, you will need to use the Gutter or the Breakpoint List.

Data

Watch List.

By watching data while controlling the execution flow, you can notice at which point a variable or expression returns an unexpected value. That way, you can locate the source of the problem and fix it.

Variables

HTML5 Builder includes two widgets which list available variables and display its content:

  • Local Variables. It displays PHP local variables, that is, variables defined by you (or those defined on the RPCL if you are using it). You can get this widget from View > Debug Windows > Local Variables.
  • Global Variables. It displays PHP global variables, such as $GLOBALS or $_POST. You can get this widget from View > Debug Windows > Global Variables.

You can also hover a variable (or a constant) on the Code Editor to get a tooltip with its current value.

Expressions

Sometimes, variables and constants are not enough, and you need to evaluate a whole PHP expression. While you could assign the result of that expression to a variable in code, and then watch the value of that variable, you would be modifying your source code for debugging purposes, which is something you should better avoid. Instead, you can pass the debugger the expression at any point on the execution flow, and it will give you its value.

Right-click on the Code Editor, and go to Debug > Evaluate/Modify…. There, enter a valid PHP expression on the single-line field, and click the Evaluate button. The result of the expression will be printed on the multi-line field.

You can leave the dialog window open while you continue controlling the execution flow. But the result of the expression will not be updated in real-time, you will have to click Evaluate each time.

Watches

Watches are variables or constants whose value you track. While Local Variables and Global Variables widgets let you already track the value of any variable, you can use watches to have a short custom list of variables you need to track, and use some additional features on them (see watches properties).

Manage

Tip: Use the Watch List to properly manage your watches.

To add a watch to a variable:

  1. Go to Run > Add Watch….
  2. Enter any properties you want, Filename and Line number fields are mandatory.
  3. Click OK.

The new watch will be listed on the Watch List widget.

Properties

Every watch has the following properties:

  • Expression: Variable to be watched. For example: $Page1.
  • Group name: Name of the group the watch belongs to. Grouping watches will let you, thorugh the Watch List, disable, enable or remove whole groups of breakpoints at once.
  • Enabled: Whether the watch is enabled or not.

If you want to modify any of those on an existing breakpoint, you will need to use the Gutter or the Breakpoint List.