ray-skill

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 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/`	-

设置项	默认值	环境变量
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

字段说明

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`	数组	待发送的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" }
}

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

这类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类型参考

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