goletter/hyperf-sls-log

Structured Aliyun SLS logging for Hyperf 3.1 (Client / Writer / Monolog Handler).

v1.0.1 2026-08-29 19:11 UTC

Requires

• php: >=8.1
• ext-json: *
• ext-zlib: *
• hyperf/contract: ~3.1.0
• hyperf/coroutine: ~3.1.0
• hyperf/guzzle: ~3.1.0
• hyperf/support: ~3.1.0
• monolog/monolog: ^3.0
• psr/container: ^1.0 || ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• hyperf/config: ~3.1.0
• hyperf/di: ~3.1.0
• hyperf/framework: ~3.1.0
• mockery/mockery: ^1.0
• phpunit/phpunit: ^10.0
• swoole/ide-helper: dev-master

MIT

• goletter

• log
• php
• monolog
• aliyun
• SLS
• hyperf

Published on Packagist.org on 2026-08-29 19:12 UTC

README

Hyperf 3.1 阿里云 SLS 日志组件（结构化分层）。

App / Monolog
    │
    ▼
Handler\SlsHandler  ──►  Writer\SlsWriter  ──►  Client\SlsClient
                              │                      │
                         batch/async            HttpTransport
                         sensitive filter       Signer
                         fallback               ProtobufEncoder

目录结构

目录	职责
Contract/	对外接口
Client/	SLS HTTP API（签名、传输、Protobuf 编码）
Writer/	业务直写 + 批量缓冲
Handler/	Monolog 适配（很薄）
Model/	LogEntry / QueryResult
Support/	配置、脱敏、落盘、IP
Protobuf/	协议细节（内部，应用层不要依赖）

安装

composer require goletter/hyperf-sls-log
php bin/hyperf.php vendor:publish goletter/hyperf-sls-log

配置

ALIYUN_SLS_ENABLED=true
ALIYUN_SLS_ENDPOINT=cn-shenzhen.log.aliyuncs.com
ALIYUN_SLS_PROJECT=
ALIYUN_SLS_LOGSTORE=
ALIYUN_SLS_ACCESS_KEY_ID=
ALIYUN_SLS_ACCESS_KEY_SECRET=
ALIYUN_SLS_TOPIC=app
ALIYUN_SLS_SCHEME=https
ALIYUN_SLS_BATCH_SIZE=20
ALIYUN_SLS_ASYNC=true

用法

1）Monolog（推荐）

config/autoload/logger.php：

use Goletter\AliYun\Sls\Handler\SlsHandler;
use Monolog\Level;

return [
    'default' => [
        'handler' => [
            'class' => SlsHandler::class,
            'constructor' => [
                'level' => Level::Info,
            ],
        ],
    ],
];

$logger->info('支付成功', ['order_id' => 1, 'user_id' => 42, 'request_id' => $rid]);

2）Writer / Facade

use Goletter\AliYun\Sls\Contract\LogWriterInterface;
use Goletter\AliYun\Sls\Sls;

public function __construct(private LogWriterInterface $sls) {}

$this->sls->info('业务日志', ['foo' => 'bar']);
$this->sls->flush(); // 请求结束前可主动刷缓冲

Sls::error('失败', ['reason' => 'timeout']);

3）底层 Client（查询 / 自定义批量）

use Goletter\AliYun\Sls\Contract\SlsClientInterface;
use Goletter\AliYun\Sls\Model\LogEntry;

$client->putLogs([
    LogEntry::make(['message' => 'hello', 'level' => 'INFO']),
]);

$result = $client->getLogs(time() - 3600, time(), 'level: ERROR', line: 50);
foreach ($result->logs as $row) {
    // ...
}

行为说明

• 批量：缓冲到 batch_size 再 PutLogs
• 异步：协程内默认异步推送
• 脱敏：password/token/secret/... 替换为 ***
• 失败落盘：runtime/logs/sls_fallback.log
• 未就绪：缺 project/logstore/密钥时静默跳过，不影响主流程

破坏性变更（相对旧版）

旧的扁平 API 已移除，请改用：

旧	新
Goletter\AliYun\Sls\ClientInterface	Contract\SlsClientInterface
Goletter\AliYun\Sls\Client	Client\SlsClient
PutLogsRequest / LogItem	putLogs(LogEntry[])
自己复制的 SLSMonologHandler	Handler\SlsHandler