README

项目简介

guolei19850528/laravel-tjbrhk-toolkit 是一个基于 Laravel 框架的设备服务扩展，用于集成天津博瑞皓科 (Tjbrhk) 设备服务。该扩展提供了简洁的 API 接口，方便开发者通过 HTTP 与天津博瑞皓科的设备进行通信，目前主要支持向设备发送 notify 消息。

主要功能

与天津博瑞皓科设备服务进行 HTTP 通信
支持向设备发送 notify 消息
支持多设备配置，可同时管理多个设备实例
提供链式 setter / getter，调用方式简洁
支持自定义响应处理回调与 Laravel Validator 校验规则
配置灵活，敏感信息通过 .env 注入

技术栈

PHP 8.x
Laravel 7.x ~ 13.x（依赖 illuminate/support）
GuzzleHttp 7.x（由 Laravel HTTP 门面使用）

项目结构

laravel-tjbrhk-toolkit/
├── config/
│   └── laravel-tjbrhk-toolkit.php   # 配置文件（设备参数）
├── src/
│   ├── HasSpeaker.php               # 通信能力 Trait（属性 + notify）
│   ├── Client.php                   # 设备客户端（组合 HasSpeaker）
│   └── ExtensionServiceProvider.php # 服务提供者（发布配置）
├── .gitignore
├── LICENSE
├── README.md
└── composer.json

安装方法

1. 安装依赖

通过 Composer 安装扩展：

composer require guolei19850528/laravel-tjbrhk-toolkit

2. 发布配置文件

安装完成后，使用以下任一命令发布配置文件：

# 方式一：通过 provider 发布
php artisan vendor:publish --provider="Guolei19850528\Laravel\Tjbrhk\Toolkit\ExtensionServiceProvider"

# 方式二：通过 tag 发布
php artisan vendor:publish --tag=guolei19850528/laravel-tjbrhk-toolkit

发布后，配置文件将保存在 config/laravel-tjbrhk-toolkit.php 中。

说明：服务提供者已通过 composer.json 的 extra.laravel.providers 配置自动注册，Laravel 会在启动时自动发现并注册，无需手动添加到 config/app.php。

配置说明

1. 基础配置

打开 config/laravel-tjbrhk-toolkit.php 文件，根据实际情况配置天津博瑞皓科设备的相关参数：

return [
    'your device' => [
        'id' => '',
        'token' => '',
        'version' => '1',
        'baseUrl' => 'https://speaker.17laimai.cn/',
    ],
];

字段	说明	默认值
`id`	设备 ID，天津博瑞皓科设备的唯一标识	空
`token`	认证令牌，用于设备服务 API 身份验证	空
`version`	API 版本号	`1`
`baseUrl`	API 基础 URL	`https://speaker.17laimai.cn/`

2. 环境变量配置

建议在 .env 文件中配置敏感信息，再由配置文件读取：

TJBRHK_DEVICE_ID=your-device-id
TJBRHK_DEVICE_TOKEN=your-device-token

// config/laravel-tjbrhk-toolkit.php
return [
    'default' => [
        'id' => env('TJBRHK_DEVICE_ID', ''),
        'token' => env('TJBRHK_DEVICE_TOKEN', ''),
        'version' => '1',
        'baseUrl' => 'https://speaker.17laimai.cn/',
    ],
];

3. 多设备配置

扩展支持配置多个天津博瑞皓科设备实例，每个实例拥有独立的参数：

return [
    'default' => [
        'id' => env('TJBRHK_DEFAULT_DEVICE_ID', ''),
        'token' => env('TJBRHK_DEFAULT_DEVICE_TOKEN', ''),
        'version' => '1',
        'baseUrl' => 'https://speaker.17laimai.cn/',
    ],
    'device_a' => [
        'id' => env('TJBRHK_DEVICE_A_ID', ''),
        'token' => env('TJBRHK_DEVICE_A_TOKEN', ''),
        'version' => '1',
        'baseUrl' => 'https://speaker.17laimai.cn/',
    ],
    'device_b' => [
        'id' => env('TJBRHK_DEVICE_B_ID', ''),
        'token' => env('TJBRHK_DEVICE_B_TOKEN', ''),
        'version' => '1',
        'baseUrl' => 'https://speaker.17laimai.cn/',
    ],
];

使用示例

1. 基本使用

use Guolei19850528\Laravel\Tjbrhk\Toolkit\Client;

// 从配置创建设备客户端实例
$client = new Client(
    id: config('laravel-tjbrhk-toolkit.default.id'),
    token: config('laravel-tjbrhk-toolkit.default.token'),
    version: config('laravel-tjbrhk-toolkit.default.version'),
    baseUrl: config('laravel-tjbrhk-toolkit.default.baseUrl')
);

// 发送 notify 消息
try {
    $result = $client->notify(message: 'Hello, this is a test message from Laravel Tjbrhk Toolkit!');
    echo $result ? '消息发送成功！' : '消息发送失败！';
} catch (\Exception $e) {
    echo '发送过程中发生错误：' . $e->getMessage();
}

2. 在控制器中使用

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Guolei19850528\Laravel\Tjbrhk\Toolkit\Client;

class DeviceController extends Controller
{
    /**
     * 发送设备消息
     */
    public function sendMessage()
    {
        $config = config('laravel-tjbrhk-toolkit.default');

        $client = new Client(
            id: $config['id'],
            token: $config['token'],
            version: $config['version'],
            baseUrl: $config['baseUrl']
        );

        $message = '欢迎光临！这是一条来自 Laravel Tjbrhk Toolkit 的消息。';

        try {
            $result = $client->notify($message);

            return response()->json([
                'status' => $result ? 'success' : 'error',
                'message' => $result ? '消息发送成功' : '消息发送失败'
            ]);
        } catch (\Exception $e) {
            return response()->json([
                'status' => 'error',
                'message' => '发送失败: ' . $e->getMessage()
            ], 500);
        }
    }
}

3. 使用自定义配置（链式调用）

use Guolei19850528\Laravel\Tjbrhk\Toolkit\Client;

// 创建实例后手动设置参数
$client = (new Client())
    ->setId('your-device-id')
    ->setToken('your-device-token')
    ->setVersion('1')
    ->setBaseUrl('https://speaker.17laimai.cn/');

try {
    $result = $client->notify('这是一条使用自定义配置发送的消息');
    echo $result ? '发送成功' : '发送失败';
} catch (\Exception $e) {
    echo '错误: ' . $e->getMessage();
}

4. 使用自定义响应处理

默认 notify() 返回 bool，若需要获取响应原文或自定义判定逻辑，可传入 $responseHandler：

use Guolei19850528\Laravel\Tjbrhk\Toolkit\Client;
use Illuminate\Http\Client\Response;

$client = new Client(/* ... */);

// 自定义处理：直接返回响应 JSON
$result = $client->notify(
    message: '带自定义响应处理的消息',
    responseHandler: function (Response $response) {
        return $response->json();
    }
);

// 自定义校验规则：要求 errcode 为 0 且 errmsg 存在
$result = $client->notify(
    message: '带自定义校验的消息',
    validatorRules: [
        'errcode' => 'required|integer|size:0',
        'errmsg'  => 'required|string',
    ]
);

API 文档

Client 类

命名空间：Guolei19850528\Laravel\Tjbrhk\Toolkit

Client 通过 use HasSpeaker 获得全部属性与 notify() 方法，自身只提供构造函数。

构造函数

public function __construct(
    string|int|null $id = '',
    ?string         $token = '',
    string|int|null $version = '1',
    ?string         $baseUrl = 'https://speaker.17laimai.cn/'
)

参数说明：

$id：设备 ID
$token：认证令牌
$version：API 版本号（默认：'1'）
$baseUrl：API 基础 URL（默认：'https://speaker.17laimai.cn/'）

notify 方法

public function notify(
    ?string   $message = '',
    ?string   $url = '/notify.php',
    ?array    $urlParameters = [],
    ?array    $options = [],
    ?\Closure $responseHandler = null,
    ?array    $validatorRules = ['errcode' => 'required|integer|size:0']
): mixed

参数说明：

$message：要发送的消息内容
$url：API 请求路径（默认：'/notify.php'）
$urlParameters：附加到 URL 的查询参数数组
$options：GuzzleHttp 请求选项
$responseHandler：自定义响应处理回调，返回值会被 value() 解包
$validatorRules：响应 JSON 的 Laravel Validator 校验规则，默认要求 errcode 为 0

返回值：

默认返回 bool：成功 true，失败 false
提供 $responseHandler 时，返回回调处理后的结果

属性 setter / getter

// 设备 ID
public function getId(): string|int|null
public function setId(string|int|null $id): self

// 认证令牌
public function getToken(): ?string
public function setToken(?string $token): self

// API 版本号
public function getVersion(): ?string
public function setVersion(?string $version): self

// API 基础 URL（getter 会去除末尾斜杠）
public function getBaseUrl(): ?string
public function setBaseUrl(?string $baseUrl): self

注意：所有 setter 均返回 $this，支持链式调用。

HasSpeaker Trait

命名空间：Guolei19850528\Laravel\Tjbrhk\Toolkit

通信能力 Trait，可被任意类 use。宿主类无需自行声明 $id / $token / $version / $baseUrl 属性（在 PHP 中由 trait 上下文隐式提供，运行时通过动态属性赋值）。提供与 Client 完全一致的 setter / getter 与 notify() 方法。

ExtensionServiceProvider

命名空间：Guolei19850528\Laravel\Tjbrhk\Toolkit

继承 Illuminate\Support\ServiceProvider，仅实现 boot()，用于将 config/laravel-tjbrhk-toolkit.php 发布到宿主应用。由 composer.json 的 extra.laravel.providers 自动注册。

注意事项

确保已正确配置设备 ID 和认证令牌
API 默认地址为 https://speaker.17laimai.cn/，如有变化请在配置文件中修改
notify() 会以表单形式提交 id / token / version / message，请避免在不可信环境暴露令牌
默认校验规则要求响应 JSON 中 errcode 为 0，如设备服务返回结构不同，请通过 $validatorRules 或 $responseHandler 自定义
支持多设备配置，可在同一项目中通过不同的 Client 实例操作多个设备

开发说明

核心类说明

Client：天津博瑞皓科设备客户端，组合 HasSpeaker Trait，对外暴露构造函数与 notify() 方法
HasSpeaker：通信能力 Trait，封装 setter / getter 与 notify() 的 HTTP 调用逻辑
ExtensionServiceProvider：Laravel 扩展服务提供者，负责发布配置文件

版本历史

v1.0.0 (2026-02-05)
- 初始版本
- 实现天津博瑞皓科设备 notify 消息发送功能
- 支持多设备配置
- 提供链式 setter / getter 与自定义响应处理

许可证

本扩展采用 MIT 许可证，详情请查看 LICENSE 文件。

联系方式

开发者：郭磊
邮箱：174000902@qq.com

贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进这个扩展！

guolei19850528 / laravel-tjbrhk-toolkit

Maintainers

Package info

Statistics

Security

README

项目简介

主要功能

技术栈

项目结构

安装方法

1. 安装依赖

2. 发布配置文件

配置说明

1. 基础配置

2. 环境变量配置

3. 多设备配置

使用示例

1. 基本使用

2. 在控制器中使用

3. 使用自定义配置（链式调用）

4. 使用自定义响应处理

API 文档

Client 类

构造函数

notify 方法

属性 setter / getter

HasSpeaker Trait

ExtensionServiceProvider

注意事项

开发说明

核心类说明

版本历史

许可证

联系方式

贡献指南