PHP client library for xrDebug. This library provides a set of functions to dump variables, send raw messages, and interact with the inspector from your codebase.

Install using Composer.

composer require --dev xrdebug/php

Use xr() directly in your code to dump any variable. For example:

require_once __DIR__ . '/vendor/autoload.php';

// ...
xr('Hello, world!');

This xrDebug PHP client uses the following default configuration.

Skip this section if running from the xrDebug binary and on the same machine.

[
    'isEnabled' => true,
    'isHttps' => false,
    'host' => 'localhost',
    'port' => 27420,
    'key' => '',
]

host The hostname or IP. When running xrDebug on Docker use host.docker.internal.

Configure the client by placing a xr.php file in project's root directory. Need to define only the properties that override the default config.

We recommend adding xr.php to your .gitignore.

Here some examples of xr.php:

• Run with Docker at a 27980 port:

  <?php
  
  return [
      'host' => 'host.docker.internal',
      'port' => 27980,
  ];

• Run with sign verification:

  <?php
  
  return [
      'key' => file_get_contents('private.key'),
  ];

Use function xrConfig() to configure the xrDebug server connection directly in your logic. Need to define only the properties that override the default config.

Here some examples of xrConfig():

• Run with Docker at a 27980 port:

   xrConfig(
      host: 'host.docker.internal',
      port: 27980,
  );

• Run with sign verification:

   xrConfig(
      key: file_get_contents('private.key'),
  );

This xrDebug PHP client provides the following helper functions in the root namespace. Use these anywhere in your code.

Use function xr($var1, $var2,...) to dump one or more variable(s).

xr($var, 'Hola, mundo!');

Pass a topic using t:.

xr($var, t: 'Epic win');

Pass an emote using e:.

xr($var, e: '😎');

Pass bitwise flags to trigger special behavior.

• f: XR_BACKTRACE to include debug backtrace.

xr($var, f: XR_BACKTRACE);

Use function xrr() to send a raw message.

xrr('<h1>Hola, mundo!</h1>');
xrr('<span>Test</span>', t: 'Epic win');
xrr('<b>test</b>', e: '😎');
xrr('some string<br>', f: XR_BACKTRACE);

Use function xri() to interact with the inspector.

Use pause to pause code execution.

xri()->pause();

Use memory to send memory usage information.

xri()->memory();

This xrDebug PHP client also provides the following helper functions provided by the VarDump package.

Function vd is a drop-in replacement for var_dump. It prints information about one or more variables to the output stream.

vd($var1, $var2,);
// more code

Function vdd does same as vd, but with die(0) which halts further execution.

vdd($var);
// does exit();

The PHP client provides a throwable handler that can hook or replace existing exception handler logic thanks to the ThrowableHandler package.

Use registerThrowableHandler to enable xrDebug throwable handling.

use Chevere\xrDebug\PHP\registerThrowableHandler;

// True append xrDebug to your existing handler
// False use only xrDebug handler
registerThrowableHandler(true);

To handle errors with xrDebug you will require to configure your project to handle errors as exceptions and register a shutdown function:

use Chevere\ThrowableHandler\ThrowableHandler;

set_error_handler(
    ThrowableHandler::ERROR_AS_EXCEPTION
);
register_shutdown_function(
    ThrowableHandler::SHUTDOWN_ERROR_AS_EXCEPTION
);

Use throwableHandler in any existing exception handler logic:

use Chevere\xrDebug\PHP\throwableHandler;

set_exception_handler(
    function(Throwable $throwable) {
        // ...
        try {
            throwableHandler($throwable);
        } catch(Throwable) {
            // Don't panic
        }
    }
);

Extra inspectors can be defined to provide more context aware debug information. To create a custom inspector use XrInspectorTrait to implement the XrInspectorInterface and use sendCommand method.

For code below, myDump defines a method that will stream data from your application logic and myPause sends a pause with debug backtrace by default.

<?php

use Chevere\xrDebug\PHP\Traits\XrInspectorTrait;
use Chevere\xrDebug\PHP\Interfaces\XrInspectorInterface;

class MyInspector implements XrInspectorInterface
{
    use XrInspectorTrait;

    public function myDump(
        string $t = '',
        string $e = '',
        int $f = 0,
    ): void {
        $data = 'my queries from somewhere...';
        $this->sendCommand(
            command: 'message',
            body: $data,
            topic: $t,
            emote: $e,
            flags: $f,
        );
    }

    public function myPause(
        int $f = XR_DEBUG_BACKTRACE,
    ): void {
        $this->sendCommand(
            command: 'pause',
            flags: $f,
        );
    }
}

The method sendCommand enables to interact with the existing xrDebug instance.

private function sendCommand(
    string $command,
    string $body = '',
    string $topic = '',
    string $emote = '',
    int $flags = 0
);

A null inspector is required to void any inspection call if xrDebug is disabled. The null inspector should implement the same methods as the real inspector, but without carrying any action.

💡 Use XrInspectorNullTrait to implement the XrInspectorInterface when providing null inspector.

<?php

use Chevere\xrDebug\PHP\Traits\XrInspectorNullTrait;
use Chevere\xrDebug\PHP\Interfaces\XrInspectorInterface;

class MyInspectorNull implements XrInspectorInterface
{
    use XrInspectorNullTrait;

    public function myDump(
        string $t = '',
        string $e = '',
        int $f = 0,
    ): void {
    }

    public function myPause(
        int $f = XR_DEBUG_BACKTRACE,
    ): void {
    }
}

use Chevere\xrDebug\PHP\XrInspectorInstance;
use Chevere\xrDebug\PHP\Interfaces\XrInspectorInterface;
use LogicException;
use MyInspector;
use MyInspectorNull;

function my_inspector(): MyInspector
{
    try {
        return XrInspectorInstance::get();
    } catch (LogicException) {
        $inspector = getXr()->enable()
            ? MyInspector::class
            : MyInspectorNull::class;
        $client = getXr()->client();
        $inspector = new $inspector($client);
        $instance = new XrInspectorInstance($inspector);

        return $instance::get();
    }
}

To use your custom helper:

my_inspector()->myDump();
my_inspector()->myPause();

Documentation available at docs.xrdebug.com.

Copyright Rodolfo Berrios A.

xrDebug is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.