Back to Details

ray-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ray Skill

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 is what the 
ray()
PHP function does under the hood.
Ray是Spatie为开发者打造的桌面调试应用。通过向其本地服务器发送HTTP请求，可直接将数据发送至Ray。这正是
ray()
PHP函数的底层实现逻辑。

Connection Details

连接详情

SettingDefaultEnvironment Variable
Host
localhost
RAY_HOST
Port
23517
RAY_PORT
URL
http://localhost:23517/
-
设置项默认值环境变量
Host
localhost
RAY_HOST
Port
23517
RAY_PORT
URL
http://localhost:23517/
-

Request Format

请求格式

Method: POST Content-Type: 
application/json
User-Agent: 
Ray 1.0
请求方法： POST Content-Type： 
application/json
User-Agent： 
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

字段说明

FieldTypeDescription
uuid
stringUnique identifier for this Ray instance. Reuse the same UUID to update an existing entry.
payloads
arrayArray of payload objects to send
meta
objectOptional metadata (ray_package_version, project_name, php_version)
字段类型描述
uuid
字符串当前Ray实例的唯一标识符。复用相同UUID可更新现有条目。
payloads
数组待发送的Payload对象数组
meta
对象可选元数据（ray_package_version、project_name、php_version）

Origin Object

Origin对象

Every payload includes origin information:
json
{
  "file": "/Users/dev/project/app/Controller.php",
  "line_number": 42,
  "hostname": "dev-machine"
}
每个Payload都包含来源信息：
json
{
  "file": "/Users/dev/project/app/Controller.php",
  "line_number": 42,
  "hostname": "dev-machine"
}

Payload Types

Payload类型

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" }
}
设置Ray界面的背景色：
json
{
  "type": "screen_color",
  "content": {
    "color": "green"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

Label

添加标签

Add a label to the entry:
json
{
  "type": "label",
  "content": {
    "label": "Important"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
为条目添加标签：
json
{
  "type": "label",
  "content": {
    "label": "Important"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

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)

无内容的简单Payload

These payloads only need a 
type
and empty 
content
:
json
{
  "type": "separator",
  "content": {},
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
TypePurpose
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
这类Payload仅需指定
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

组合多个Payload

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": {}
}
可在单个请求中发送多个Payload。使用相同
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状态码（该端点不存在，但服务器处于运行状态）。

Payload Type Reference

Payload类型参考

TypeContent FieldsPurpose
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窗口