README

易签宝（e签宝）开放平台 V3 API 的非官方 PHP SDK。

注意: 本 SDK 基于易签宝 V3 版本 API 开发，兼容 PHP 7.0+。

✨ 特性

完整覆盖: 支持实名认证、文件管理、合同模板、签署流程等核心业务。
兼容性好: 支持 PHP 7.0 及以上版本，兼容 Laravel、ThinkPHP、FastAdmin 等主流框架。
强类型支持: 代码中广泛使用 PHP 7 类型提示，提高代码质量和开发体验。
易于使用: 采用领域服务模式设计，调用逻辑清晰直观。
自动签名: 内置 API 请求签名逻辑，开发者无需关心鉴权细节。
重试机制: 内置 HTTP 请求自动重试机制，提高网络波动下的稳定性。

📦 安装

使用 Composer 安装：

composer require qingze-lab/esignbao-sdk-php-7.0

🚀 快速开始

1. 初始化客户端

use QingzeLab\ESignBao\Client;
use QingzeLab\ESignBao\Config\Configuration;

$config = new Configuration(
    'your_app_id',
    'your_app_secret',
    'https://smlopenapi.esign.cn' // 沙箱环境
);

$client = new Client($config);

2. 发起一份签署流程

// 1. 上传文件
$uploadResult = $client->file()->uploadFileByPath('./contract.pdf');
$fileId = $uploadResult['data']['fileId'];

// 2. 创建签署流程
$flowResult = $client->signFlow()->createByFile(
    [
        ['fileId' => $fileId, 'fileName' => '合同.pdf']
    ],
    null, // attachments
    [
        'signFlowTitle' => '测试合同签署',
        'autoStart' => true,
        'autoFinish' => true
    ],
    null, // signFlowInitiator
    [
        [
            'signerType' => 0, // 个人签署
            'psnSignerInfo' => ['psnAccount' => '188****8888'],
            'signFields' => [
                ['fileId' => $fileId, 'posPage' => '1', 'posX' => 100, 'posY' => 100]
            ]
        ]
    ]
);
$signFlowId = $flowResult['data']['signFlowId'];

// 3. 获取签署链接
$signUrl = $client->signFlow()->getSignUrl(
    $signFlowId,
    ['psnAccount' => '188****8888']
);

echo "签署链接: " . $signUrl['data']['shortUrl'];

🛠 框架集成

Laravel

在 Laravel 中，你可以将 Client 绑定到服务容器中。

在 AppServiceProvider 的 register 方法中：

use QingzeLab\ESignBao\Client;
use QingzeLab\ESignBao\Config\Configuration;
use QingzeLab\ESignBao\Log\LaravelLogger;

public function register()
{
    $this->app->singleton(Client::class, function ($app) {
        $config = new Configuration(
            env('ESIGN_APP_ID'),
            env('ESIGN_APP_SECRET'),
            env('ESIGN_API_URL', 'https://openapi.esign.cn')
        );
        
        // 使用 Laravel 的日志系统
        $config->setLogger(new LaravelLogger(app('log')));
        
        return new Client($config);
    });
}

使用时注入：

public function sign(Client $client)
{
    // ...
}

ThinkPHP / FastAdmin

在 ThinkPHP 或 FastAdmin 中，你可以创建一个公共的服务类或直接在控制器中实例化。

1. 基础集成

use QingzeLab\ESignBao\Client;
use QingzeLab\ESignBao\Config\Configuration;

class ESignService
{
    protected static $client;

    public static function getClient()
    {
        if (!self::$client) {
            $config = new Configuration(
                config('esign.app_id'),
                config('esign.app_secret'),
                config('esign.api_url')
            );
            self::$client = new Client($config);
        }
        return self::$client;
    }
}

2. 日志集成 (ThinkPHP 5.0)

ThinkPHP 5.0 的日志系统是静态调用的，你可以实现一个简单的适配器类来接入 SDK 的日志。

首先定义适配器类 Tp5Logger：

namespace app\common\library; // 命名空间根据实际情况调整

use QingzeLab\ESignBao\Log\LoggerInterface;
use think\Log;

/**
 * 适配 ThinkPHP 5.0 的日志类
 */
class Tp5Logger implements LoggerInterface
{
    public function info(string $message, array $context = [])
    {
        // 记录 info 级别日志
        // JSON_UNESCAPED_UNICODE 确保中文不被转义
        $contextStr = !empty($context) ? ' ' . json_encode($context, JSON_UNESCAPED_UNICODE) : '';
        Log::record('[ESignBao] ' . $message . $contextStr, 'info');
    }

    public function error(string $message, array $context = [])
    {
        // 记录 error 级别日志
        $contextStr = !empty($context) ? ' ' . json_encode($context, JSON_UNESCAPED_UNICODE) : '';
        Log::record('[ESignBao] ' . $message . $contextStr, 'error');
    }
}

然后在初始化 SDK 时注入该日志类：

// 在 ESignService::getClient() 中
$config = new Configuration(
    config('esign.app_id'),
    config('esign.app_secret'),
    config('esign.api_url')
);

// 注入日志适配器
$config->setLogger(new \app\common\library\Tp5Logger());

self::$client = new Client($config);

📖 文档

详细的接口说明和使用文档请查阅 Wiki。

🤝 贡献

欢迎提交 Issue 或 Pull Request 来改进本项目。

📄 许可证

本项目基于 MIT 许可证开源。详情请参阅 LICENSE 文件。

qingze-lab / esignbao-sdk-php-7.0

Maintainers

Package info

Statistics

Security