About
Docs
Support
{

FastDebug Documentation

NOTE: FastDebug is currently experimental. While using it you may experience crashes or your code might not work as expected.

Installation

  • Download the binary file for the extension for your Operating System, PHP Version and Architecture from the Extension Download page.
    (Note: you will need to be logged in and have been accepted into our beta program before you can access that page)
  • Copy that binary file to the extension folder of your PHP installation. To find the location of this folder you can run the following command:

php-config --extension-dir

  • If php-config is not available in your PHP installation you can use this other command:

php -i | grep ^extension_dir

  • Note that under some installations, the PHP config used for running web requests may be different from the one use to run CLI commands. In that case you also need to add this binary file to the folder used for web requests. The best way to locate the folder for this case is to run a request that returns the output of the phpinfo() function and look for "extension_dir" in this output.
  • Load the extension in PHP. You need to add the following line to one of your php .ini files:

extension=fastdebug

  • You can add this configuration either directly in your main php.ini file or by adding a new configuration file (for example fastdebug.ini) in the folder where additional ini files are kept, usually "conf.d" under the folder where the php.ini file can be located.
  • To find the location of your php.ini file you can run the following command:

php-config --ini-dir

  • If php-config is not available in your PHP installation you can use this other command:

php -i | grep "php.ini"

  • Note again that under some installations, the PHP config used for running web requests may be different from the one use to run CLI commands. In that case you also need to add this configuration to the folder used for web requests. The best way to locate the folder for this case is to run a request that returns the output of the phpinfo() function and look for "php.ini" in this output.
  • Confirm that the extension is loaded and working fine. Run this command:

php -v

  • You should see some output similar to:

PHP 8.2.1 (cli) (built: Jan 25 2023 17:53:51) (ZTS)
Copyright (c) The PHP Group
Zend Engine v4.2.1, Copyright (c) Zend Technologies
    with Zend OPcache v8.2.1, Copyright (c), by Zend Technologies
    with FastDebug v0.3.1, Copyright(c) 2023 FastDebug, by Carlos Granados

  • The important part is the last line which shows that the extension has been loaded and is working fine.

Configuration

  • FastDebug offers the same configuration options as Xdebug for step debugging, only that the prefix will be "fastdebug" instead of "xdebug". These are the configuration options available in your .ini file:

fastdebug.client_discovery_header
fastdebug.client_host
fastdebug.client_port
fastdebug.connect_timeout_ms
fastdebug.discover_client_host
fastdebug.idekey
fastdebug.log
fastdebug.log_level
fastdebug.start_upon_error
fastdebug.start_with_request
fastdebug.trigger_value

  • Please refer to Xdebug's documentation to understand what each of these options does. However, many of these options are available so that Xdebug can be started on request. But since FastDebug is so performant, there is usually no need for all this. We recommend just setting fastdebug.start_with_request to "yes" so that FastDebug is always available, the overhead is so low that you can forget about it and then always have a debugger ready when you need it.
  • FastDebug can be further configured by setting some environment variables or by sending these values as request parameters or in cookies. These are the variables that FastDebug supports:

DBGP_IDEKEY
DBGP_COOKIE
FASTDEBUG_CONFIG
FASTDEBUG_SESSION
FASTDEBUG_SESSION_START
FASTDEBUG_SESSION_STOP
FASTDEBUG_SESSION_STOP_NO_EXEC
FASTDEBUG_TRIGGER
HTTP_X_FORWARDED_FOR
REMOTE_ADDR

  • Again please refer to Xdebug's documentation to understand what each of these does.
  • Apart from the configuration variables prefixed with FASTDEBUG_ you can also use those variables with an XDEBUG_ prefix. In this way, we support these variables:

XDEBUG_CONFIG
XDEBUG_SESSION
XDEBUG_SESSION_START
XDEBUG_SESSION_STOP
XDEBUG_SESSION_STOP_NO_EXEC
XDEBUG_TRIGGER

  • This means that you will not need to change anything on the client side. You should be able to continue using your IDE configs, plugins or browser add-ons without any change.

Functions

  • FastDebug's extension provides the following functions:

fastdebug_break()
fastdebug_connect_to_client()
fastdebug_is_debugger_active()
fastdebug_notify()

  • These provide the same functionality as their xdebug equivalents, please see its documentation for more info.

Compatibility with Xdebug

  • FastDebug can run alongside Xdebug as lomg as Xdebug is not in debug mode. Xdebug can take care of other functionality like profiling or code coverage. However, we do not recommend this setup as you will lose some of the speed advantage offered by FastDebug. So we recommend that you locate the place in your ini file where Xdebug is loaded with a line similar to this one and that you remove it so that xdebug is fully disabled:

extension=xdebug

Beta program

We are currently offering FastDebug under a private beta program. If you would like to participate in this program and be one of the first developers to be able to test this amazing tool, please sign up by clicking the button below.

Join the beta
}