README

YG Operation Service PHP SDK 是用于访问 YG 运营服务 API 的 PHP 开发工具包，提供了便捷的接口调用方式，帮助开发者快速集成 YG 运营服务。

目录结构

YGOperationServicePHPSDK/
├── README.md          # SDK 文档
├── composer.json      # Composer 配置文件
├── src/               # 源码目录
│   ├── Client.php     # 客户端核心类
│   ├── Auth/          # 认证相关
│   └── Services/      # 业务服务
├── examples/           # 使用示例
│   └── ...            # 示例代码文件
└── tests/              # 测试代码
    └── ...            # 单元测试文件

安装

依赖要求

PHP >= 7.4
Guzzle HTTP Client >= 7.0 (guzzlehttp/guzzle)

使用 Composer 安装

composer require yungangunite/operation-service-sdk

快速开始

初始化客户端

<?php

require_once __DIR__ . '/vendor/autoload.php';

use YG\OperationService\Client;

// 初始化客户端
$client = new Client([
    'access_key' => 'your_access_key',
    'access_secret' => 'your_access_secret',
    'base_uri' => 'https://api.example.com', // API 基础地址（可选，有默认值）
]);

注意：base_uri 参数为可选，如果不提供，SDK 会使用默认的 API 地址。

提示：更多完整的使用示例请查看 examples/ 目录。

认证机制

获取访问令牌

通过 access_key 和 access_secret 获取访问令牌，用于后续业务接口调用。

接口说明

方法	HTTP 请求	接口地址
`getToken`	POST	`/api/v1/third-applications/auth/token`

请求参数

参数名	类型	是否必填	描述
`access_key`	string	是	访问密钥
`access_secret`	string	是	访问密钥（Secret）

返回结果

{
    "code": 0,
    "msg": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expires_in": 7200
    }
}

使用示例

<?php

// 获取访问令牌
$response = $client->auth()->getToken();

// 输出结果
print_r($response);

业务接口

项目管理

获取项目列表

<?php

// 获取项目列表
$response = $client->project()->getList([
    'page' => 1,
    'page_size' => 10,
    // 其他查询参数
]);

print_r($response);

看货二维码管理

创建看货二维码

<?php

// 创建看货二维码
$response = $client->qrCode()->create([
    'project_id' => '123',
    'expires_at' => time() + 3600,
    // 其他参数
]);

print_r($response);

获取看货二维码列表

<?php

// 获取看货二维码列表
$response = $client->qrCode()->getList([
    'page' => 1,
    'page_size' => 10,
    'project_id' => '123',
    // 其他查询参数
]);

print_r($response);

查看看货二维码详情

<?php

// 查看看货二维码详情
$response = $client->qrCode()->getDetail('qr_code_id');

print_r($response);

看货记录管理

获取看货记录列表

<?php

// 获取看货记录列表
$response = $client->viewRecord()->getList([
    'page' => 1,
    'page_size' => 10,
    'project_id' => '123',
    'start_time' => '2023-01-01',
    'end_time' => '2023-01-31',
    // 其他查询参数
]);

print_r($response);

查看看货记录详情

<?php

// 查看看货记录详情
$response = $client->viewRecord()->getDetail('record_id');

print_r($response);

错误处理

SDK 会抛出以下类型的异常：

YG\OperationService\Exceptions\ApiException - API 调用错误
YG\OperationService\Exceptions\AuthException - 认证错误
YG\OperationService\Exceptions\ClientException - 客户端配置错误

异常处理示例

<?php

try {
    $response = $client->project()->getList();
    print_r($response);
} catch (\YG\OperationService\Exceptions\ApiException $e) {
    echo "API 错误：" . $e->getMessage() . " (" . $e->getCode() . ")\n";
} catch (\YG\OperationService\Exceptions\AuthException $e) {
    echo "认证错误：" . $e->getMessage() . "\n";
} catch (\YG\OperationService\Exceptions\ClientException $e) {
    echo "客户端错误：" . $e->getMessage() . "\n";
} catch (\Exception $e) {
    echo "未知错误：" . $e->getMessage() . "\n";
}

API 文档

完整的 API 文档请访问：

开发环境：http://127.0.0.1:8001/docs?api-docs.json
生产环境：请替换为实际的生产环境地址

注意事项

请妥善保管您的 access_key 和 access_secret，避免泄露
访问令牌有过期时间（默认 7200 秒），过期后需要重新获取
建议在应用中实现令牌自动刷新机制
所有 API 调用都需要在请求头中携带有效的 Authorization: Bearer {access_token}
请根据实际业务需求合理设置请求超时时间
建议在生产环境中使用环境变量来管理敏感配置信息

版本更新

v1.0.0

初始版本
实现获取访问令牌功能
实现项目管理接口
实现看货二维码管理接口
实现看货记录管理接口

示例代码

SDK 提供了丰富的示例代码，位于 examples/ 目录中，包括：

基础使用示例
认证流程示例
各业务接口调用示例
错误处理示例

您可以参考这些示例来快速上手 SDK 的使用。

测试

运行测试套件：

composer test

或者使用 PHPUnit 直接运行：

./vendor/bin/phpunit

测试代码位于 tests/ 目录中。

常见问题

Q: 如何配置请求超时时间？

A: 在初始化客户端时，可以通过 timeout 参数设置：

$client = new Client([
    'access_key' => 'your_access_key',
    'access_secret' => 'your_access_secret',
    'timeout' => 30, // 超时时间（秒）
]);

Q: 如何处理令牌过期？

A: SDK 会自动处理令牌刷新，您也可以手动获取新令牌：

$tokenResponse = $client->auth()->getToken();

贡献

欢迎提交 Issue 和 Pull Request 来帮助改进 SDK。

许可证

MIT License

yungangunite / operation-service-sdk

Maintainers

Details