This package is abandoned and no longer maintained. The author suggests using the xrdebug/php package instead.

Lightweight debug utility

1.0.1 2023-10-21 23:24 UTC


🔔 Subscribe to the newsletter to don't miss any update regarding Chevere.

Build Code size Apache-2.0 PHPStan Mutation testing badge

Quality Gate Status Maintainability Rating Reliability Rating Security Rating Coverage Technical Debt CodeFactor Codacy Badge

PHP client library for xrDebug.

Quick start

composer require --dev xrdebug/php



Use xr($var1, $var2,...) to dump any 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 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 xri() to interact with the inspector.

Use pause to pause code execution.


Use memory to send memory usage information.



Code-based configuration

Use xrConfig() to configure the xrDebug server connection.

    isEnabled: true,
    isHttps: false,
    host: 'localhost',
    port: 27420,
    key: file_get_contents('private.key')
Property Type Effect
isEnabled bool Controls sending messages to the server
isHttps bool Controls use of https
host string The host where xrDebug server is running
port int The Port to connect to the host
key string Private key

File-based configuration

Configure the client by placing a xr.php file in project's root directory.

We recommend adding xr.php to your .gitignore.


return [
    'isEnabled' => true,
    'isHttps' => false,
    'host' => 'localhost',
    'port' => 27420,
    'key' => file_get_contents('private.key'),

Error handling

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;


Exception handling

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

Register handler

Use registerThrowableHandler to enable xrDebug throwable handling.

use Chevere\Xr\registerThrowableHandler;

// True append xrDebug to your existing handler
// False use only xrDebug handler

Triggered handler

Use throwableHandler in any existing exception handler logic:

use Chevere\Xr\throwableHandler;

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

Custom inspectors

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.


use Chevere\Xr\Inspector\Traits\XrInspectorTrait;
use Chevere\Xr\Interfaces\XrInspectorInterface;

class MyInspector implements XrInspectorInterface
    use XrInspectorTrait;

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

    public function myPause(
        int $f = XR_DEBUG_BACKTRACE,
    ): void {
            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

Null inspector

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.


use Chevere\Xr\Inspector\Traits\XrInspectorNullTrait;
use Chevere\Xr\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 {

Helper function for custom inspector

use Chevere\Xr\Inspector\XrInspectorInstance;
use Chevere\Xr\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:



Documentation available at


Copyright 2023 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.