Debugging Output And Previewing Html Using Ray

Ray Skill

Overview

Ray is Spatie's desktop debugging application for developers. Send data directly to Ray by making HTTP requests to its local server.

This can be useful for debugging applications, or to preview design, logos, or other visual content.

This is what the ray() PHP function does under the hood.

Connection Details

Request Format

Method: POST Content-Type: application/json User-Agent: Ray 1.0

Basic Request Structure

jsonCopy code
{
  "uuid": "unique-identifier-for-this-ray-instance",
  "payloads": [
    {
      "type": "log",
      "content": { },
      "origin": {
        "file": "/path/to/file.php",
        "line_number": 42,
        "hostname": "my-machine"
      }
    }
  ],
  "meta": {
    "ray_package_version": "1.0.0"
  }
}

Fields

Origin Object

Every payload includes origin information:

jsonCopy code
{
  "file": "/Users/dev/project/app/Controller.php",
  "line_number": 42,
  "hostname": "dev-machine"
}

Payload Types

Log (Send Values)

jsonCopy code
{
  "type": "log",
  "content": {
    "values": ["Hello World", 42, {"key": "value"}]
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Custom (HTML/Text Content)

jsonCopy code
{
  "type": "custom",
  "content": {
    "content": "<h1>HTML Content</h1><p>With formatting</p>",
    "label": "My Label"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Table

jsonCopy code
{
  "type": "table",
  "content": {
    "values": {"name": "John", "email": "john@example.com", "age": 30},
    "label": "User Data"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Color

Set the color of the preceding log entry:

jsonCopy code
{
  "type": "color",
  "content": {
    "color": "green"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Available colors: green, orange, red, purple, blue, gray

Screen Color

Set the background color of the screen:

jsonCopy code
{
  "type": "screen_color",
  "content": {
    "color": "green"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Label

Add a label to the entry:

jsonCopy code
{
  "type": "label",
  "content": {
    "label": "Important"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Size

Set the size of the entry:

jsonCopy code
{
  "type": "size",
  "content": {
    "size": "lg"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Available sizes: sm, lg

Notify (Desktop Notification)

jsonCopy code
{
  "type": "notify",
  "content": {
    "value": "Task completed!"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

New Screen

jsonCopy code
{
  "type": "new_screen",
  "content": {
    "name": "Debug Session"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Measure (Timing)

jsonCopy code
{
  "type": "measure",
  "content": {
    "name": "my-timer",
    "is_new_timer": true,
    "total_time": 0,
    "time_since_last_call": 0,
    "max_memory_usage_during_total_time": 0,
    "max_memory_usage_since_last_call": 0
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

For subsequent measurements, set is_new_timer: false and provide actual timing values.

Simple Payloads (No Content)

These payloads only need a type and empty content:

jsonCopy code
{
  "type": "separator",
  "content": {},
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Combining Multiple Payloads

Send multiple payloads in one request. Use the same uuid to apply modifiers (color, label, size) to a log entry:

jsonCopy code
{
  "uuid": "abc-123",
  "payloads": [
    {
      "type": "log",
      "content": { "values": ["Important message"] },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "color",
      "content": { "color": "red" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "label",
      "content": { "label": "ERROR" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "size",
      "content": { "size": "lg" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    }
  ],
  "meta": {}
}

Example: Complete Request

Send a green, labeled log message:

bashCopy code
curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -H "User-Agent: Ray 1.0" \
  -d '{
    "uuid": "my-unique-id-123",
    "payloads": [
      {
        "type": "log",
        "content": {
          "values": ["User logged in", {"user_id": 42, "name": "John"}]
        },
        "origin": {
          "file": "/app/AuthController.php",
          "line_number": 55,
          "hostname": "dev-server"
        }
      },
      {
        "type": "color",
        "content": { "color": "green" },
        "origin": { "file": "/app/AuthController.php", "line_number": 55, "hostname": "dev-server" }
      },
      {
        "type": "label",
        "content": { "label": "Auth" },
        "origin": { "file": "/app/AuthController.php", "line_number": 55, "hostname": "dev-server" }
      }
    ],
    "meta": {
      "project_name": "my-app"
    }
  }'

Availability Check

Before sending data, you can check if Ray is running:

Copy code
GET http://localhost:23517/_availability_check

Ray responds with HTTP 404 when available (the endpoint doesn't exist, but the server is running).

Getting Ray Information

Get Windows

Retrieve information about all open Ray windows:

Copy code
GET http://localhost:23517/windows

Returns an array of window objects with their IDs and names:

jsonCopy code
[
  {"id": 1, "name": "Window 1"},
  {"id": 2, "name": "Debug Session"}
]

Get Theme Colors

Retrieve the current theme colors being used by Ray:

Copy code
GET http://localhost:23517/theme

Returns the theme information including color palette:

jsonCopy code
{
  "name": "Dark",
  "colors": {
    "primary": "#000000",
    "secondary": "#1a1a1a",
    "accent": "#3b82f6"
  }
}

Use Case: When sending custom HTML content to Ray, use these theme colors to ensure your content matches Ray's current theme and looks visually integrated.

Example: Send HTML with matching colors:

bashCopy code

# First, get the theme

THEME=$(curl -s http://localhost:23517/theme)
PRIMARY_COLOR=$(echo $THEME | jq -r '.colors.primary')

# Then send HTML using those colors

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "theme-matched-html",
    "payloads": [{
      "type": "custom",
      "content": {
        "content": "<div style=\"background: '"$PRIMARY_COLOR"'; padding: 20px;\"><h1>Themed Content</h1></div>",
        "label": "Themed HTML"
      },
      "origin": {"file": "script.sh", "line_number": 1, "hostname": "localhost"}
    }]
  }'

Payload Type Reference