How to Use Xdebug for PHP with Netbeans on FreeBSD

Netbeans itself ships with PHP Xdebug support enabled by default. To get the two working together correctly there are additional steps required. The following is a clear set of instructions on how configure Xdebug, Netbeans, and PHP on FreeBSD using best practices.

Requirements

PHP 5.2 or greater
Netbeans 8.0 or greater
Root access is needed to install the PHP Xdebug extension via pkg

Note: If you do not have root access check if you already have Xdebug installed. If not then ask your sysadmin to install it for you. Failing that, it is possible to have the module load from your home directory. However, that's outside the scope of this article.

Setup User INI Files in PHP

PHP on FreeBSD is compiled to scan for additional INI files in /usr/local/etc/php. With modern versions of PHP this behavior can be manipulated with the environmental variable: PHP_INI_SCAN_DIR.

export PHP_INI_SCAN_DIR=:~/.config/php

To enable it globally for your user create or edit ~/.login_conf using your preferred text editor. Add or edit the setenv option so that it includes the variable and value as shown below.

me:\
    :setenv=PHP_INI_SCAN_DIR=\c~/.config/php:

Important: The "\c" above is not a typo. Since a colon (:) is used to separate entries, a "\c" escape sequence must be used to embed a literal colon in the value.

Note: Multiple variables are separated by a comma in case you already have that option defined with another variable. If setenv is not the only entry then you must a append a '\' and the end of all lines except the last. For example:

me:\
    :path=/sbin /bin /usr/sbin /usr/bin /usr/local/sbin /usr/local/bin ~/bin ~/.local/bin:\
    :setenv=OTHER_VAR=xxxx,PHP_INI_SCAN_DIR=\c~/.config/php:

For a full explanation of the syntax of this file refer to the man page for login.conf.

The file needs to be compiled into a binary version. This is done with cap_mkdb.

cap_mkdb ~/.login_conf

Logoff and log back in to apply the changes. To confirm it's working try to print out the value of the variable:

echo $PHP_INI_SCAN_DIR
:/home/directory/.config/php

Alternatively you could modify /etc/login.conf under the 'default' or 'standard' classes to make the change system wide. Once again refer to the login.conf man page for the correct usage.

Install Packages

You only need to install the devel/pecl-xdebug extension package. Like most of the PHP extensions in the ports tree it's flavored. The exact syntax used to install depends on the PHP version you are using. If you are using PHP 7.4 then your installation command will be as follows:

pkg install php74-pecl-xdebug

If you are using PHP 7.3:

pkg install php73-pecl-xdebug

If you are not sure what version of PHP you have, you can find out by inspecting the currently installed packages that match PHP.

 pkg info -g php\*

The output of that command should make it obvious what version of PHP is installed.

Enable Xdebug

Xdebug won't be enabled by default and it needs to be turned on using an INI file entry. You could create a file under /usr/local/etc/php/, but that requires root access and affects all users. The preferred way would be to enable this for yourself. This was the purpose behind setting up per-user PHP INI files.

Create a file named xdebug.ini in .config/php under your home directory.

mkdir -p ~/.config/php
edit ~/.config/php/xdebug.ini

Save the file with the following contents:

[xdebug]
xdebug.remote_enable=1

If you are on xdebug 3^[1] or later, you will instead need to use:

[xdebug]
xdebug.mode=debug

Make sure PHP is able to read it by checking the output of php --ini. Your output might differ depending on what other PHP packages you have installed.

# php --ini
Configuration File (php.ini) Path: /usr/local/etc
Loaded Configuration File:         /usr/local/etc/php.ini
Scan for additional .ini files in: :/home/directory/.config/php/
Additional .ini files parsed:      /usr/local/etc/php/ext-20-ctype.ini,
/usr/local/etc/php/ext-20-curl.ini,
/usr/local/etc/php/ext-20-filter.ini,
/usr/local/etc/php/ext-20-iconv.ini,
/usr/local/etc/php/ext-20-intl.ini,
/usr/local/etc/php/ext-20-json.ini,
/usr/local/etc/php/ext-20-mbstring.ini,
/usr/local/etc/php/ext-20-openssl.ini,
/usr/local/etc/php/ext-20-phar.ini,
/usr/local/etc/php/ext-20-xdebug.ini,
/home/directory/.config/php/xdebug.ini

Notice the last line shows it loaded our custom ini file /home/directory/.config/php/xdebug.ini.

Try Xdebug in Netbeans

Although it should be enabled already, verify that xdebug is indeed setup in Netbeans. By default xdebug 2 will listen on port 9000 and xdebug 3 and later uses 9003^[1].

Try to debug a PHP file in Netbeans:

If you need to use a different port number, you can change it by adding the following line to your ~/.config/php/xdebug.ini file.

xdebug.remote_port=9000

Note: Xdebug's default debugging port has changed from 9000 to 9003 in version 3^[1]. It's preferable to change it in Netbeans instead of xdebug.

Checkout the Xdebug documentation for a list of additional settings.

Closing Thoughts

The per-user PHP INI files feature that was enable here is not limited just to Xdebug. You can have additional INI files that PHP will read overridable configuration entries in other files under the configured directory.

[1] Upgrading from: Xdebug 2 to 3

FreeBSD

Developer