debugging-output-and-previewing-html-using-ray

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Ray是Spatie为开发者打造的桌面调试应用。通过向其本地服务器发送HTTP请求，可直接将数据发送至Ray。

这在调试应用，或预览设计、标志或其他可视化内容时非常有用。

ray()

PHP函数的底层实现正是如此。

Connection Details

连接详情

Setting	Default	Environment Variable
Host	`localhost`	`RAY_HOST`
Port	`23517`	`RAY_PORT`
URL	`http://localhost:23517/`	-

设置项	默认值	环境变量
主机	`localhost`	`RAY_HOST`
端口	`23517`	`RAY_PORT`
地址	`http://localhost:23517/`	-

Request Format

请求格式

Method: POST Content-Type:

application/json

User-Agent:

Ray 1.0

请求方法: POST 内容类型:

application/json

用户代理:

Ray 1.0

Basic Request Structure

基础请求结构

json

{
  "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"
  }
}

json

{
  "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

字段说明

Field	Type	Description
`uuid`	string	Unique identifier for this Ray instance. Reuse the same UUID to update an existing entry.
`payloads`	array	Array of payload objects to send
`meta`	object	Optional metadata (ray_package_version, project_name, php_version)

字段	类型	描述
`uuid`	字符串	Ray实例的唯一标识符。复用相同UUID可更新已有条目。
`payloads`	数组	要发送的负载对象数组
`meta`	对象	可选元数据（ray_package_version、project_name、php_version）

Origin Object

来源对象

Every payload includes origin information:

json

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

每个负载都包含来源信息：

json

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

Payload Types

负载类型

Log (Send Values)

日志（发送值）

json

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

json

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

Custom (HTML/Text Content)

自定义（HTML/文本内容）

json

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

json

{
  "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

表格

json

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

json

{
  "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:

json

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

Available colors:

green

orange

red

purple

blue

gray

设置前一条日志条目的颜色：

json

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

可用颜色:

green

orange

red

purple

blue

gray

Screen Color

屏幕颜色

Set the background color of the screen:

json

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

设置屏幕背景色：

json

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

Label

Size

尺寸

Set the size of the entry:

json

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

Available sizes:

sm

lg

设置条目的尺寸：

json

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

可用尺寸:

sm

lg

Notify (Desktop Notification)

通知（桌面通知）

json

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

json

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

New Screen

新屏幕

json

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

json

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

Measure (Timing)

测量（计时）

json

{
  "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.

json

{
  "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" }
}

后续测量时，设置

is_new_timer: false

并提供实际计时数值。

Simple Payloads (No Content)

简单负载（无内容）

These payloads only need a

type

and empty

content

json

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

Type	Purpose
`separator`	Add visual divider
`clear_all`	Clear all entries
`hide`	Hide this entry
`remove`	Remove this entry
`confetti`	Show confetti animation
`show_app`	Bring Ray to foreground
`hide_app`	Hide Ray window

这些负载仅需指定

type

和空

content

：

json

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

类型	用途
`separator`	添加视觉分隔线
`clear_all`	清空所有条目
`hide`	隐藏此条目
`remove`	删除此条目
`confetti`	展示彩屑动画
`show_app`	将Ray窗口前置
`hide_app`	隐藏Ray窗口

Combining Multiple Payloads

组合多个负载

Send multiple payloads in one request. Use the same

uuid

to apply modifiers (color, label, size) to a log entry:

json

{
  "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": {}
}

可在一个请求中发送多个负载。使用相同的

uuid

可为日志条目应用修饰符（颜色、标签、尺寸）：

json

{
  "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:

bash

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"
    }
  }'

发送一条绿色、带标签的日志消息：

bash

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:

GET http://localhost:23517/_availability_check

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

发送数据前，可检查Ray是否正在运行：

GET http://localhost:23517/_availability_check

当Ray可用时，会返回HTTP 404（该端点不存在，但服务器正在运行）。

Getting Ray Information

获取Ray信息

Get Windows

获取窗口信息

Retrieve information about all open Ray windows:

GET http://localhost:23517/windows

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

json

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

获取所有已打开Ray窗口的信息：

GET http://localhost:23517/windows

返回包含窗口ID和名称的窗口对象数组：

json

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

Get Theme Colors

获取主题颜色

Retrieve the current theme colors being used by Ray:

GET http://localhost:23517/theme

Returns the theme information including color palette:

json

{
  "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:

bash

undefined

获取Ray当前使用的主题颜色：

GET http://localhost:23517/theme

返回包含调色板的主题信息：

json

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

使用场景: 向Ray发送自定义HTML内容时，可使用这些主题颜色，确保内容与Ray当前主题匹配，视觉上更协调。

示例: 发送匹配主题颜色的HTML：

bash

undefined

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

再发送使用该颜色的HTML

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"} }] }'

undefined

undefined

Payload Type Reference

负载类型参考

Type	Content Fields	Purpose
`log`	`values` (array)	Send values to Ray
`custom`	`content` , `label`	HTML or text content
`table`	`values` , `label`	Display as table
`color`	`color`	Set entry color
`screen_color`	`color`	Set screen background
`label`	`label`	Add label to entry
`size`	`size`	Set entry size (sm/lg)
`notify`	`value`	Desktop notification
`new_screen`	`name`	Create new screen
`measure`	`name` , `is_new_timer` , timing fields	Performance timing
`separator`	(empty)	Visual divider
`clear_all`	(empty)	Clear all entries
`hide`	(empty)	Hide entry
`remove`	(empty)	Remove entry
`confetti`	(empty)	Confetti animation
`show_app`	(empty)	Show Ray window
`hide_app`	(empty)	Hide Ray window

类型	内容字段	用途
`log`	`values` (数组)	向Ray发送值
`custom`	`content` , `label`	HTML或文本内容
`table`	`values` , `label`	以表格形式展示
`color`	`color`	设置条目颜色
`screen_color`	`color`	设置屏幕背景色
`label`	`label`	为条目添加标签
`size`	`size`	设置条目尺寸（sm/lg）
`notify`	`value`	发送桌面通知
`new_screen`	`name`	创建新屏幕
`measure`	`name` , `is_new_timer` , 计时字段	性能计时
`separator`	(空)	添加视觉分隔线
`clear_all`	(空)	清空所有条目
`hide`	(空)	隐藏条目
`remove`	(空)	删除条目
`confetti`	(空)	展示彩屑动画
`show_app`	(空)	显示Ray窗口
`hide_app`	(空)	隐藏Ray窗口