highlight.io PHP 后端集成指南：使用 highlight/php-sdk 接入错误监控、日志与 Trace

• 可观测性
• 后端

本篇指南基于 highlight.io 仓库中的服务端接入文档 10_php-other.md 展开，覆盖该 PHP 后端快速上手页面的完整步骤：通过 Composer 安装highlight/php-sdk、三种 SDK 初始化方式、错误上报、日志接入与 Trace 记录，并逐条核对文档内容在仓库源码中的真实定义位置。读完后，你不仅能在任意 PHP 框架（框架无关的 "other" 路径）中接入 Highlight 的 Errors、Logs、Traces 三类能力，还能理解这类 QuickStart 文档页面是如何由仓库中的 TSX 组件渲染出来的。

文档定位：这是一个组件驱动的 QuickStart 页面

先说明这篇文档在仓库中的组织方式，有助于理解后续每一步内容的出处。

10_php-other.md 的正文非常简短，只有一行 MDX 嵌入（见 该文件第 8 行）：

<QuickStart content={quickStartContent["server"]["php"]["other"]}/>

其 frontmatter 声明了页面元信息：toc: "PHP: All Frameworks"、title: Using highlight.io with PHP Frameworks、slug: other、quickstart: true。页面的真实步骤内容并非写在 Markdown 里，而是定义在仓库源码 server/php/other.tsx 导出的PHPOtherReorganizedContent对象中（该文件第 12-55 行）：

• title: 'PHP'、subtitle: 'Learn how to set up highlight.io on your PHP backend.'
• products: ['Errors', 'Logs', 'Traces']—— 即该 PHP 后端路径支持的产品能力是错误、日志与 Trace；
• entries数组按顺序组织了 8 个步骤：前端联动（可选）→ 安装 SDK → 初始化 SDK → 验证错误 → 自定义错误上报（可选）→ 添加 Highlight 日志 → 验证日志 → 记录 Trace 并验证。

渲染机制可以在文档页入口highlight.io/pages/docs/[[...doc]].tsx中找到：getFilteredQuickStartContent函数（第 361-387 行）用正则/\{(\w+(?:\["[^"]+"\])+)\}/从 Markdown 中解析出quickStartContent["server"]["php"]["other"]这样的键路径，再从 QuickstartContent.tsx 导出的quickStartContent注册表中取出对应内容注入 MDX 作用域。该注册表中 PHP 服务端的入口位于 第 465-471 行：

server: { ... php: { title: 'PHP', subtitle: 'Select your PHP framework to install Highlight for your application.', logoUrl: siteUrl('/images/quickstart/php.svg'), [QuickStartType.Other]: PHPOtherReorganizedContent, },

从源码结构看，QuickStartType.Other（即'other'）是 PHP 目前唯一的服务端框架选项——该文档页对应的是"不绑定特定框架"的通用 PHP 后端接入路径。

步骤一：通过 Composer 安装 PHP SDK

安装步骤定义在 server/php/shared-snippets-monitoring.tsx 第 4-13 行 的installSdk片段中，命令为：

composer require highlight/php-sdk

在 PHP 项目的根目录（含composer.json的目录）执行该命令即可将 Highlight PHP SDK 加入依赖。

步骤二：初始化 SDK（三种方式）

initializeSdk片段（shared-snippets-monitoring.tsx 第 15-47 行）给出了同一份文档中的三种初始化写法，可按项目情况择一使用：

use Highlight\SDK\Common\HighlightOptions; use Highlight\SDK\Highlight; $projectId = '<YOUR_PROJECT_ID>'; // 方式一：仅用 projectId 引导 Highlight if (!Highlight::isInitialized()) { Highlight::init($projectId); } // 方式二：使用 HighlightOptions 实例引导 $options = HighlightOptions::builder($projectId)->build(); if (!Highlight::isInitialized()) { Highlight::initWithOptions($options); } // 方式三：在 HighlightOptions 中预先设置 serviceName $options = HighlightOptions::builder($projectId)->serviceName('test-service-01')->build(); if (!Highlight::isInitialized()) { Highlight::initWithOptions($options); }

要点说明：

• <YOUR_PROJECT_ID>需要替换为 Highlight 控制台中对应项目的 ID，文档示例中统一以此占位符表示；
• 三种写法都先用Highlight::isInitialized()做幂等保护，避免在请求多次进入初始化代码（如框架引导文件被重复 include）时重复初始化；
• HighlightOptions::builder($projectId)是链式构建器，.serviceName('...')可为服务显式命名（示例值为test-service-01），命名后的服务在控制台的数据面板中更易区分。

步骤三：错误监控与自定义错误上报

文档中的验证步骤verifyErrors（shared-snippets-monitoring.tsx 第 64-68 行）原文为："Now that you've set up the Middleware, verify that the backend error handling works by consuming an error from traced code."，即完成初始化后，触发一段会抛错的代码，然后访问 Highlight 控制台的 Errors 页面，确认错误已被采集。

对于希望在业务代码中显式上报异常的场景区，文档提供Highlight::captureException()（可选步骤customError，第 49-62 行）：

use Highlight\SDK\Highlight; Highlight::captureException(new \Exception('This is a test exception'));

该方式适合在catch块中把被捕获的异常主动上报，而不仅依赖框架层的错误处理。

步骤四：接入日志（Logs）

日志部分包含两个步骤，均定义在 server/php/other.tsx 第 23-38 行：

1. 添加 Highlight 日志记录。文档该步骤的说明文字是 "Highlight.captureLog() will record and send logs to Highlight."，其给出的示例代码为：

use Highlight\SDK\Highlight; $logger = Highlight::HighlightLogger(Highlight::$highlight) $logger->process(Highlight::HighlightLogRecordBuilder()->build());

从示例结构看，日志通过HighlightLogRecordBuilder()构建日志记录对象，再经由 logger 的process()方法发送；代码按文档原样保留（示例本身省略了分号等书写细节）。

2. 验证日志上报。verifyLogs片段定义在 server/shared-snippets-logging.tsx 第 13-17 行：访问 Highlight 控制台的 Logs 页面，确认后端日志已经到达。

步骤五：记录 Trace 并验证

Record a trace步骤（server/php/other.tsx 第 39-53 行）的说明是 "Use the Highlight SDK to create spans and events."，文档中给出的示例代码为：

use Highlight\SDK\Highlight; $tracer = Highlight::HighlightLogger(Highlight::$highlight) $tracer->process(Highlight::HighlightErrorRecord()->build());

验证步骤verifyTraces定义在 server/shared-snippets-tracing.tsx：访问 Highlight 控制台的 Traces 页面，确认后端 Trace 数据已接入。

可选前置步骤：前端联动

该文档entries的第一项frontendInstallSnippet（server/shared-snippets-monitoring.tsx 第 7-10 行）标题为 "Configure client-side Highlight. (optional)"：如果同时在前端使用 Highlight，需要先完成前端初始化，并按 fullstack mapping 指南将前端会话与后端数据关联起来。这一步对纯后端项目可以跳过。

仓库中的相关源码索引

如需进一步核对本篇所述内容的原始定义，可参考以下仓库文件：

其中 shared-snippets-logging.tsx 第 19-78 行 还提供了不经 SDK、直接以 OTLP/HTTPS 协议发送日志的curl通用示例（curlExample），可作为 PHP 场景之外、任何语言向 Highlight 直发日志的参照。

适用前提与限制

• 本指南严格以当前仓库中该文档页及其引用的 QuickStart 组件源码为准；<YOUR_PROJECT_ID>、test-service-01等均为文档示例中的占位值，实际使用时需替换。
• 文档中日志与 Trace 的示例代码按仓库原样呈现，个别语句省略了分号等书写细节，实际接入时请以 SDK 发布包的 API 与官方代码风格为准。
• 该文档页（slug: other）对应的是 PHP 下不绑定特定框架的通用路径；仓库的QuickStartType枚举中 PHP 目前没有为具体框架（如 Laravel 等）单列的服务端选项（见 QuickstartContent.tsx 第 166-232 行），因此"其他 PHP 框架"统一走本篇流程。

• 可观测性
• 后端