PHP 和 Laravel

安装 composer require blipit/blipit

安装 blipit/blipit 包(0.3.0 或更高版本),并用项目的公钥调用一次 init。它运行在 Blipit 自有内核上,不会引入任何其他包。未捕获的异常、警告和致命错误会自动上报,并内置 Laravel 和 Symfony 支持。

粘贴到 Claude Code、Cursor 或任何 AI 编程助手中。它包含步骤和代码。在 app.blipit.io 的“API 密钥”页面,同一提示词已填好你的密钥。
视频:在任何技术栈中安装 Blipit,从 1:07 开始

1安装

sh
composer require blipit/blipit

2启动时初始化

纯 PHP:放在前端控制器顶部,在处理任何请求之前。Laravel 会从其配置启动 Blipit,见下一步。密钥在项目的“密钥”页面上。密钥为空时,init 会向错误日志写入一条警告并返回 false,而不会抛出异常。

php
use Blipit\Blipit;

Blipit::init([
    "key" => "<public key>",
    "environment" => "production",
    "release" => "myapp@1.4.2",
]);

3获取密钥

登录 app.blipit.io,打开侧边栏中的“API 密钥”,然后选择你的项目。每个项目有两个密钥。公钥以 blipit_pk_ 开头:它用于浏览器和应用代码,只能发送事件,任何人看到都没关系。私密密钥以 blipit_sk_ 开头:它留在你的服务器或 Odoo 中,切勿放进浏览器,因为它还可以读取和更改问题。私密密钥只在创建后显示一次,请当时就复制;如果丢失,请点击“创建新的密钥”,旧密钥会立即失效。部分 SDK 还需要项目 id,它显示在同一页面上。

app.blipit.io 中的 API 密钥:公钥(blipit_pk_)用于浏览器代码,私密密钥(blipit_sk_)用于服务器和 Odoo。
app.blipit.io 中的 API 密钥:公钥(blipit_pk_)用于浏览器代码,私密密钥(blipit_sk_)用于服务器和 Odoo。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。

4将密钥保存在环境变量中

此 SDK 使用公钥发送数据。Laravel:把它加入 .env 和 config/services.php;Blipit 服务提供者会被自动发现,并从该配置启动 Blipit,无需其他操作。请通过 config 读取这些值,因为配置被缓存后,env() 在应用代码中不会返回任何内容。纯 PHP:用 getenv() 从服务器环境中读取密钥。

.env
BLIPIT_KEY=blipit_pk_your_public_key
config/services.php
'blipit' => [
    'key' => env('BLIPIT_KEY'),
    'environment' => env('APP_ENV'),
    'release' => env('GIT_SHA'),
],

5不要把密钥放进 git

请把密钥保存在环境变量或托管平台的密钥设置中,切勿写进你提交的代码,并把 .env 文件加入 .gitignore。网页中出现公钥是正常的。如果私密密钥曾出现在 git、公开页面、截图或聊天中,请打开“API 密钥”,点击“创建新的密钥”,并在所有用过旧密钥的地方粘贴新密钥:旧密钥会立即失效。

.gitignore
.env
.env.local
.env.*.local

6Laravel 和 Symfony

Laravel:其异常处理器上报的每个异常都会到达 Blipit,因此 404 和验证错误不会被发送。查询、日志行和 HTTP 客户端调用会变成面包屑,队列任务会被追踪。bootstrap/app.php 中已有的 Blipit::captureException 行可以保留:同一个异常绝不会发送两次。Symfony:在 config/services.yaml 中注册监听器,并在 public/index.php 和 bin/console 中尽早调用 Blipit::init。

config/services.yaml
Blipit\Symfony\BlipitListener:
    arguments: ['@router']
    tags:
        - { name: kernel.event_listener, event: kernel.exception, method: onKernelException }
        - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
        - { name: kernel.event_listener, event: kernel.terminate, method: onKernelTerminate }
        - { name: kernel.event_listener, event: console.error, method: onConsoleError }

7手动捕获和登录尝试

登录尝试需要私密密钥:请在服务器上使用私密密钥而不是公开密钥进行初始化,否则接收端会以 403 security_needs_secret_key 拒绝。Scale 套餐。

php
Blipit::captureException($e);
Blipit::captureMessage("cache miss rate above 50%", "warning");
Blipit::setUser(["id" => "42", "email" => "ana@example.com"]);
Blipit::captureSecurity("login_failed", $email, "bad_password", null, $request->ip(), $request->userAgent());

8验证是否生效

打开 app.blipit.io 中的“问题”。首个事件几秒钟内就会出现,并归组为一个问题,负责人会收到邮件。

php
Blipit::captureMessage("Hello from PHP");

须知

  • 在 init 中传入 "traces_sample_rate" => 0.2,请求就会显示在 Pulse 页面。Blipit::trace("import orders", fn () => $importer->run()) 可以为已追踪的请求或任务中的任意代码块计时。
  • 从 0.2 升级:不再需要 project(仍然可以传入),Blipit::dsn() 和 Blipit::notice() 已移除,before_send 现在以 Blipit 格式的数组接收并返回事件。
  • 让 Blipit 保持最新:《让 Blipit 保持最新》指南(docs.blipit.io/updates)介绍了更新横幅、重要版本的邮件、开发控制台中的提示以及此平台的更新命令。
  • 每个应用每个平台一个项目:每个项目在创建时选择自己的平台(Android、iOS、React Native、Flutter、Web、Backend 或 Odoo),Blipit 会以明确的错误拒绝来自其他平台的数据,所以 iOS 应用和 Android 应用需要两个项目、两个密钥。各平台的发布、版本、崩溃率和商店构建都不同,混在一个项目里会让这些数据全部失真。Web 项目也接收同一 Web 应用的服务器端数据(Next.js 服务器或 Node),React Native 或 Flutter 项目也接收它自己的 Android 和 iOS 原生崩溃报告。

遇到问题?发邮件至 support@blipit.io。每个项目的密钥和项目 id 在 app.blipit.io 的“API 密钥”下。