XR

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

Crocanty.mp4

🦄 View demo

XR is a dump debug server utility for PHP. No extras required, debug your PHP code anywhere.

Features

• 💎 Colorful, typed, easy-on-the eye dump variable highlight
• ✨ Dump n arguments
• 🐘 One-click PHP server run (no extras required)
• 👻 Filter messages by Topics and Emotes
• ✍️ Re-name "XR Session" to anything you want
• 🏁 Resume, Pause, Stop and Clear debug window controls
• 🥷 Keyboard shortcuts for ninjas (Resume R, Pause P, Stop S and Clear C)
• 😊 Export message to clipboard (plain text) or as inline-download PNG image
• 📟 Generates dump backtrace
• ⏸ Pause and resume your code execution (*not implemented)
• 🌚 Dark / 🌝 Light mode follows your system preferences
• 👽 Ephemeral, it doesn't store any persistent data
• 🍒 HTML based (save page, search, shortcuts, etc.)
• 🔥 Uses FiraCode font for displaying beautiful looking dumps ™
• 😅 Handle exceptions (hook or replace your existing handler)

Contributing

Feel free to contribute on issues and discussions with your thoughts in how to improve XR.

Getting started

• Add chevere/xr as a dev dependency in your project:

composer require --dev chevere/xr

🚧 Min stability dev

You will require to add this to your composer.json file.

    "minimum-stability": "dev",
    "prefer-stable": true

Start the server

php vendor/chevere/xr/server.php -p 27420

The server will be available at http://localhost:27420

Demo

Open the debugger and then run:

php vendor/chevere/xr/demo.php

XR Helpers

Dump variables

Use xr($var1, $var2,...) to dump any variable from your code.

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

Topic

Add a topic passing t:.

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

Emote

Add an emote passing e:.

xr(
    $var,
    'Hola, mundo!',
    t: 'Epic win',
    e: '😎'
);

Flags

Pass bitwise flags to trigger special behavior.

• f: XR_BACKTRACE to dump debug backtrace.

xr(
    $var,
    'Hola, mundo!',
    t: 'Epic win',
    e: '😎',
    f: XR_BACKTRACE
);

• f: XR_PAUSE to pause code execution (*not implemented).

xr(
    $var,
    'Hola, mundo!',
    t: 'Epic win',
    e: '😎',
    f: XR_PAUSE
);

Send raw message

Use xrr to send a raw message to the server.

💡 xrr also supports topic t, emote e and flags f arguments.

xrr(
    '<h1>Hola, mundo!</h1>',
    t: 'Greet'
);

Exception handling

Use registerThrowableHandler to enable XR to handle throwables.

use Chevere\Xr\registerThrowableHandler;

// True append XR's to your existing handler
// False use only XR's handler
registerThrowableHandler(true);

Alternatively, you can use throwableHandler in any existing exception handler logic:

use Chevere\Xr\throwableHandler;

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

Error handling

You will require to handle errors as exceptions and from there use Exception handling.

use use Chevere\ThrowableHandler\ThrowableHandler;

set_error_handler(
    ThrowableHandler::ERRORS_AS_EXCEPTIONS
);
register_shutdown_function(
    ThrowableHandler::FATAL_ERROR_HANDLER
);

Configuration

Optionally configure XR by creating a file named xr.php in your project directory with the following options:

• enable
  • bool Controls sending messages to the server. Set true to enable, false to disable.
• host
  • string The hostname/IP address where XR server is running.
• port
  • int Port to connect to the host.

The following example is a xr.php file with default settings.

<?php

return [
    'enable' => true,
    'host' => 'localhost',
    'port' => 27420,
];

For software providers

If you want to handle XR settings somewhere within your existing application logic (not depend on the xr.php file) you can do:

use Chevere\Xr\XrInstance;

// (...) your logic sets $enable, $host and $port

new XrInstance(
    new Xr(enable: $enable, host: $host: port: $port)
);

Docker

See DOCKER.

Message reference

The XR dump server can receive messages from anywhere:

POST http://localhost:27420/message
    body=Hola, mundo
    file_path=/var/www/file.php
    file_line=123
    ...

• body - The message raw body (HTML).
• file_path - The file path.
• file_line - The file line.
• emote - emote (emojis/symbols)
• topic - Topic as message context.

License

Copyright 2022 Rodolfo Berrios A.

XR 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.