21 Developing PHP Applications

21.3.2.1 Snippets

Snippets enable the user to generate code for various elements automatically.

1. Choose Tools > Palette > HTML/JSP Code Clips. A palette containing various user interface elements appears in the right-hand panel.

2. Drag the required icon on the palette to the relevant position in the code. A dialog box for specifying the parameters of the corresponding elements appears. Fill in the data.

3. The code that displays the chosen element is generated and inserted in the chosen location.

21.3.2.2 Context-Sensitive Proposals

The editor provides context-sensitive proposals for completing any number of starting symbols of the following:

• A PHP keyword (for example, if, else, elseif, while, switch, function, and so on)

• A PHP built-in function (for example, substr, count, and so on)

• A pre-defined or user-defined variable

The editor not only suggests expansions but also provides parameter hints.

To apply Code Completion:

1. Type the starting symbols of the required character string.

2. Press Ctrl+Space. A drop-down list shows the context-sensitive proposals. Each proposal is supplied with a description and parameter hints. The contents of the list change as you continue typing.

3. To obtain a list of the PHP key words that are available in the current context, press Ctrl+Space without any previous typing.

4. To obtain a hint on a variable, type the dollar symbol "$". A list of all the currently available local and global variables appears.

21.3.2.3 Code Templates and Abbreviations

In the current context, the term ”abbreviations” refers to a set of predefined character strings that correspond to the key words used in a programming language. Each abbreviation is associated with an expanded text which contains the full key word and a code template for the key word with parameter hints. To apply this functionality, type an abbreviation and press Tab. The abbreviation is replaced with the corresponding key word and the code template for the key word is provided.

To view the list of defined abbreviations with code templates:

1. Choose Tools > Options > Editor > Code Templates.

2. From the Language drop down list, select PHP. The list of PHP abbreviations and code template defined for them is displayed.

3. To add or remove a definition from the list, use the New or Remove buttons respectively.

4. To edit a definition, select the relevant row and edit the text in the edit field below the list.

For more information, see the following entry on the PHP blog: https://netbeans.org/kb/docs/php/code-templates.html.

21.3.2.4 Code Completion for Constructors

After the new keyword, the code completion window is displayed with constructors and parameters for all available classes in the project.

21.3.2.5 SQL Code Completion

SQL code completion displays when a string begins with the SQL keyword "select." The first step is to select the database connection.

All database connections registered with the IDE are displayed. After you select the connection, SQL code completion offers all tables from that database connection. If the table has columns, those are displayed as well.

SQL code completion also works with table aliases.

21.3.2.6 PHP Namespaces

Code completion supports fully qualified, partially qualified, and unqualified namespace names. The IDE also helps you resolve missing namespace use statements. Inside a namespace where you want to fix missing use statements, either right-click and select Fix Uses..., or press Ctrl+Shift+I and go to Source > Fix Uses... A dialog opens offering fully qualified names for each needed use statement. For more information, see the following entry on the PHP blog:

https://blogs.oracle.com/netbeansphp/entry/how_to_fix_your_use

21.3.2.7 Overridden and Implemented Methods

Code completion between class members offers to override or implement methods.

21.3.2.8 Annotations

NetBeans IDE code completion supports the following types of PHP annotations:

• ApiGen (legacy PHPDoc annotations)

• PHPUnit

• Doctrine 2 (ORM and ODM)

• Symfony 2

Every annotation can be associated with a context. NetBeans IDE recognizes four contexts:

• function

• class/interface (type)

• method

• field

You can add more annotations to code completion in Tools > Options > PHP > Annotations.

21.3.2.9 PHP Traits

Traits are a mechanism of code reuse introduced in PHP 5.4.0. The IDE recognizes traits syntax and code completion includes methods, functions, and anything else inherited from or declared in a trait. For more information, see the blog post at https://blogs.oracle.com/netbeansphp/entry/php_5_4_support_traits.

21.3.7.1 Constructors

You can generate constructors by pressing Alt+Insert (Ctrl+I on Mac) when the caret is inside a class body, but not inside any functions contained in that body. When you select Generate... Constructor, a dialog opens listing the fields you can initialize by the constructor. The field names are used as parameters of the constructor.

You can decide not to select any fields. In this case, the IDE generates an empty constructor, with no parameters. If the field is a class with properties, you can either select individual properties, or you can select the class, in which case all the class' properties are selected automatically.

For more information, see the following NetBeans PHP blog post: https://blogs.oracle.com/netbeansphp/entry/generate_constructor_getters_and_setters.

21.3.7.2 Getters and Setters

You can generate getters and setters by pressing Alt+Insert (Ctrl+I on Mac) when the caret is inside a class body and selecting Getter, Setter, or Getters and Setters. Only the possible functions are displayed. For example, if you already have setters for the available properties, only the getter option appears.

When you select Generate... Getter/Setter/Getter and Setter, a dialog appears with the properties for which you can generate a getter or setter. The properties are displayed in a tree. If you select a parent class, you automatically select all that class' properties.

You can name a getter or setter according to either the convention getName or the convention get_name.

For more information, see the following NetBeans PHP blog post: https://blogs.oracle.com/netbeansphp/entry/generate_constructor_getters_and_setters.

21.3.7.3 Overridden and Implemented Methods

You can generate overridden or implemented methods by pressing Alt+Insert (Ctrl+I on Mac) when the caret is inside a class declaration and there are multiple class members. A dialog opens showing the methods you can insert and indicating whether they are overridden or implemented.

This feature complements the "Implement all abstract methods" hint and code completion for overridden and implemented methods.

For more information, see the following NetBeans PHP blog post: https://blogs.oracle.com/netbeansphp/entry/generate_overriden_implemented_methods

21.4.2.1 Check If XDebug Is Installed

The first step you should take is to see if XDebug is already installed on your system. Some AMP packages come with XDebug. Run phpinfo(). If there is an XDebug section in your PHP info, XDebug is installed. If XDebug is installed, see Section 21.4.2.3, "Setting Up XDebug."

21.4.2.2 Install XDebug

The NetBeans IDE for PHP community consensus is that the XDebug installation wizard should be used to install XDebug.

1. Run phpinfo().

2. Copy the results of phpinfo() from your browser into the clipboard.

3. In a browser window, open the following URL: http://xdebug.org/wizard.php

4. Paste your PHP info into the XDebug wizard form and click Analyze.

5. Follow the instructions that appear.

21.4.2.3 Setting Up XDebug

The following section assumes you have XDebug installed and you need to set it up.

1. Run phpinfo().

2. In the PHP info, find the entries for Loaded Configuration File and Additional .ini Files Parsed.

3. For each php.ini or xdebug.ini file you find, open that file and perform the following steps:

   1. Make sure the file contains the following settings:

      zend_extension=[path to xdebug .so or .dll]
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000

      These settings are usually in a section labeled [XDebug]. If such a section does not exist, create one. However, some AMPs may differ. For example, in some versions of XAMPP AMP, the line zend_extension = "G:\xampp\php\ext\php_xdebug.dll" is outside of the [XDebug] section, and the name of the .dll file is nonstandard (php_xdebug.dll instead of xdebug.dll).

   2. Comment out all entries for Zend Optimizer, Zend Studio Debugger, or other Zend extensions.

21.4.2.4 Testing XDebug

Before trying out XDebug from the IDE you should test your XDebug installation from the command-line. One way to test XDebug is to write a test in PHP and run a debug session on it.

1. You need an arbitrary PHP file. If you do not have one, create a file called index.php, put any code into it and save it.

2. Using a text editor, create a file called dbgtest.php and type or paste the following code into the file (save the file afterward):

   <?php
$address = '127.0.0.1';
$port = '9000';
$sock = socket_create(AF_INET, SOCK_STREAM, 0);
socket_bind($sock, $address, $port) or die();
socket_listen($sock);
$client = socket_accept($sock);
echo "Connection established: $client";
socket_close($client);
socket_close($sock);
?>

3. Run the code from the command line (for example, /usr/bin/php dbgtest.php).

4. Start a debug session for an arbitrary PHP file from within a browser window (for example, http://localhost/index.php?XDEBUG_SESSION_START=mysession).

If XDebug is properly configured, the script started in step 3 should print a message similar to "Connection established: Resource id #5". If no message is printed and the script is still running, XDebug is not properly configured or uses a different port or has another problem. In this case, kill the running process and investigate where the problem is.

21.4.2.5 Setting Up Debugging Options in NetBeans IDE

After you install, configure, and successfully test XDebug, you can set up XDebug options in the IDE. To learn more about these options, open Tools > Options (NetBeans Preferences on Mac), go to the PHP category, select the Debugging tab, and click Help.

21.4.3.1 Setting Breakpoints

To set a breakpoint for a line in your PHP code, left-click the left margin or line number of the line. To remove the breakpoint, left-click the breakpoint icon.

To temporarily disable a breakpoint, right-click a breakpoint badge and deselect Breakpoint > Enabled in the popup menu. This toggles the breakpoint into a disabled state and the breakpoint badge in the left margin is now grey.

The Source Editor indicates a line breakpoint by highlighting the line at which the breakpoint is set in red and placing an annotation in the left margin. Users of other languages supported in the IDE may be familiar with other types of breakpoints but only line breakpoints are supported in PHP projects. For a table of breakpoint annotations that are used in the editor, see Section 10.9.4, "Managing Breakpoints."

You can view and organize all IDE breakpoints by choosing Windows > Debugging > Breakpoints (Alt+Shift+5). For details on organizing breakpoints, see Section 10.9.4.3, "How to Organize Breakpoints Into a Group."

21.4.4.1 Debugger Windows and Context

Most debugger windows depend on the current context. When you change the current context, the contents of these windows are updated to reflect the new context.

For example, the Debugging window shows the threads in the current session, while the Call Stack window shows the call stack for the current thread. The Variables window shows the variables that are local to the current call.

The exceptions are the Breakpoints and Watches windows. These windows list all breakpoints and watches set in the IDE. While the set of watches is shared by all sessions, an individual watch expression is evaluated and displayed based on the current context.

21.4.4.2 The Source Editor and Context

When a variable is active in the current context, the Source Editor displays the value of the variable when you move the pointer over it. In cases where a program includes different variables with the same name, the Source Editor displays the value based on the current context, and not on the instance of the variable in the source code.

21.4.5.1 Starting a PHP Debugging Session

The IDE starts the debugger, then runs the application inside the debugger. When you start a debugging session, the IDE automatically opens the debugger windows, opens a browser window, and prints debugger output to the Output window. You start the debugging session in the browser window.

By default, the debugging session stops at the first line of the PHP code. You can disable stopping at the first line in the Debugging tab in the PHP category of the Options window. When the session stops, you have a number of options for stepping through/into or continuing the debugging session.

To start debugging a project:

1. Locate the project's node in the Projects window.

2. Either right-click the project node and select Debug, or select the project node and run the Debug Project command (Ctrl+F5).

Alternatively, you can debug an individual PHP file:

1. Expand the project's node in the Projects window. Navigate the tree until you locate the file you want.

2. Either right-click the file node and select Debug, or select the file node and run the Debug File command (Ctrl+Shift+F5).

The process for starting a debugging session is the same for local and remote projects. However, path mapping must be set up to debug remote projects.

21.4.5.2 Remote PHP Debugging and Path Mapping

It is possible to debug both scripts and web pages, and web pages can be debugged either locally or remotely. For Remote Debugging, unfortunately the debugged PHP file on the remote server is not the same as the file opened in the IDE running on a local machine. Debugger support in the IDE must thus be able to map server paths to local paths. However, due to many complications, path mapping cannot be resolved automatically for every individual scenario. Therefore, you must manually define path mapping through the project setup for individual run configurations. You can also specify the proxy server, if any, and the URL at which the debugging session starts. If you do not specify this URL, debugging starts at your index file.

To set up path mapping and enable custom debugging URLs:

1. Right-click the project's node in the Projects window and open the project's Properties from the context menu.

2. In the Project Properties dialog, go to the Run Configuration category.

3. Click the Advanced button. The Advanced Web Configuration dialog opens.

4. Add the server path and the project path for path mapping.

5. Under "Debug URL", select one of the following (do not leave the default selected):

   • Ask Every Time, which has the IDE prompt you for the URL when you start a debugging session.

   • Do Not Open Web Browser, which requires you to open the browser and enter the URL manually (you need the GET/POST XDEBUG_SESSION_START variable).

6. If you are using a proxy server for debugging, enter the server's host name and port in the Debugger Proxy section.

For more information, please see the following post in the NetBeans for PHP blog:

https://blogs.oracle.com/netbeansphp/entry/path_mapping_in_php_debugger

21.4.5.3 Stepping Through Your Program

By default, the debugging session stops at the first line of the PHP code. You can disable stopping at the first line in the Debugging tab in the PHP category of the Options window. When the session stops, you can step through your lines of code using the following commands on the Debug menu or toolbar:

You should set breakpoints before you start a debugging session or you will have to step over/into/out of your entire application. If you disable Stop at First Line and do not set any breakpoints, your application never stops during debugging and you get no useful results.

For more details, see the following document:

https://netbeans.org/kb/docs/php/debugging.html

21.4.5.4 Finishing a PHP Debugging Session

If necessary, you can stop the current debugging session using the Shift+F5 shortcut. You can also close a specific debugging session using the Sessions window.

To finish the current debugging session:

1. Choose Debug > Finish Debugger Session (Shift+F5).

To finish one of several debugging sessions:

1. Open the Sessions window by choosing Window > Debugging > Sessions (Alt+Shift+6).

2. Right-click the debugging session you want to stop and choose Finish.

21.4.6.1 Using the Breakpoints Window

The Breakpoints window lists all the breakpoints that you set in your projects. You can open the Breakpoints window by choosing Window > Debugging > Breakpoints. If you open the Breakpoints window when a debugging session is running, it closes automatically when you end the debugging session. If you open the window when no debugging session is running, it stays open until you close it.

By default, each entry contains a short text description of the breakpoint and a checkbox indicating whether the breakpoint is enabled or disabled. You can enable or disable a breakpoint directly in the Breakpoints window by selecting or deselecting the checkbox.

21.4.6.2 Using the Call Stack Window

The Call Stack window lists the sequence of calls made during execution. When the debugger is suspended, the Call Stack window shows the sequence of function calls (that is, the call stack). On initial suspension, the top-most stack frame is selected automatically.

Double-click on a function call in the window to go to that line in the editor. If the call is made to a PHP class, the Navigator window will also go to that line when you double-click the call.

You can double-click on a call stack frame to select it, then explore any variable or expression values for that frame in the Variables and Watches windows.

21.4.6.3 Using the Threads Window

The Threads window lists all threads in the current debugging session. You open the Threads window by choosing Window > Debugging > Threads.

The information given for each thread is the thread name, state and if the thread is suspended. One thread is the current thread. By default, the current thread is the thread in the current session from which the debugger gained control. When you select a different current session, the Threads window is updated to show the threads for that session.

21.4.6.4 Using the Variables Window

The Variables window lists the local variables in the current call. By default, the Variables window opens automatically whenever you start a debugging session. You can open the Variables window by choosing Window > Debugging > Variables.

If you open the Variables window when a debugging session is running, it closes automatically when you end the debugging session. If you open the window when no debugging session is running, it stays open until you close it.

The information given for each variable includes the variable name, type, and value. You can click the control to the left of the name to expand or collapse the variable. If the object type is displayed in blue underlined text, clicking the text jumps to the object type in the source code. You can click the Value cell to edit the value directly in the Variables window.

In some cases, the debugger assigns a pound sign (#) and a number as the variable's value. This number is a unique identifier of the given instance. You can use this identifier to determine if a variable points to the same or to a different instance. You cannot edit this value.

21.4.6.5 Using the Watches Window

The Watches window lists all variables and expressions that you have specified to watch while debugging. By default, the Watches window opens automatically whenever you start a debugging session. You can open the Watches window by choosing Window > Debugging > Watches.

If you open the Watches window when a debugging session is running, it closes automatically when you end the debugging session. If you open the window when no debugging session is running, it stays open until you close it.

The information given for each watch includes the variable or expression name, type, and value. If the variable has a control to its left, you can click the control to expand or collapse the object. If the object type is displayed in blue underlined text, clicking the text jumps to the object type in the source code. You can click in the Value cell to edit the value directly in the Watches window.

When you add a new variable or expression to the Watches window, the value of the variable or expression is immediately evaluated and displayed. The value of a watch is based on the current context. As you move through your program code, the Watches window is updated to show the value of the watch for that context.

In some cases, the debugger assigns a pound sign (#) and a number as the variable's value. This number is a unique identifier of the given instance. You can use this identifier to determine if a variable points to the same or to a different instance. You cannot edit this value.

21.4.7.1 Viewing Variables When Debugging PHP Applications

In the IDE, local variables are listed in the Variables window, however it is also possible to evaluate variables directly in the Source Editor.

Using the Variables Window

For each variable within the current call, the Variables window displays information including the variable name, type, and value. The Variables window also displays all of the static fields from the present class and all superclasses for each variable, as well as all of the inherited fields from all superclasses.

You can change the value of a local variable directly in the Variables window and then continue running your program with the new value in place.

In some cases, the debugger assigns a pound sign (#) and a number as the variable's value. This number is an unique identifier of the given instance. You can use this identifier to determine if a variable points to the same instance or to a different instance. You cannot edit this value.

Evaluating Variables in the Source Editor

You can also evaluate a variable directly in the Source Editor by moving the insertion point over the variable. If the variable is active in the current context, the value of the variable is displayed in a tool tip. In cases where a program includes different variables with the same name, the Source Editor displays the value based on the current context, and not on the instance of the variable in the source code.

You can track the changes in the value of a variable during program execution by setting a watch on the variable. When you create a watch, the value of the variable is immediately evaluated and displayed in the Watches window.

21.4.7.2 Enabling and Creating Watches in PHP Code

A watch enables you to track the changes in the value of a variable or expression during program execution. The Watches window lists all of the watches you defined for all IDE projects, of all programming languages. You can open the Watches window by choosing Window > Debugging > Watches (Alt+Shift+2).

Before you can set watches in PHP code, you must enable PHP watches in the Options window. Watches can destabilize XDebug, especially if a watch is set on invalid code.

To enable watches for PHP:

1. Open Tools > Options (NetBeans Preferences on Mac).

2. Click the PHP icon.

3. Open the Debugging tab.

4. Select Watches and Balloon Evaluation.

5. Optionally, change the Maximum Depth of Structures and/or the Maximum Number of Children. These numbers set the visibility of nested structures and array items, respectively, during Watch evaluation.

6. Click OK.

For more information about PHP Debugging Options, click Help at the bottom of the Debugging tab.

If watches and balloon evaluation is enabled in PHP Options, you can create watches in the Source Editor.

To create a watch from the Source Editor:

1. Select the variable or expression in the Source Editor, right-click, and choose New Watch (Ctrl+Shift+F7).

   The New Watch dialog box opens with the variable or expression entered in the text field.

2. Click OK.

The Watches window opens with the new watch selected.

For more details, see the following document: https://netbeans.org/kb/docs/php/debugging.html#usingAdditionalWatches