README

gyselroth文档引擎Web服务的客户端库

最低要求

PHP7.1及json扩展
构建工具：git, composer

安装

通过composer安装

composer require gyselroth/document-engine-client:dev-trunk

使用方法

创建最小客户端

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com'
]);

使用HTTP基本认证创建客户端

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com',
    'authenticationType' => 'basic',
    'username'    => 'foo',
    'password'    => 'bar'
]);

使用Bearer认证（例如oauth2、openid connect等）创建客户端

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com',
    'authenticationType' => 'bearer',
    'token'    => 'aBCdeFGHIJKlmnOpq1RsTu',
    'password'    => 'bar'
]);

Document Engine Client 允许您使用自己的http客户端实现。任何选择的实现都必须实现 GuzzleHttp\ClientInterface 接口。

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com'
], new MyHttpClient());

验证模板

$template = new \SplFileObject('template.docx');
$validity = $client->validateTemplate($template);

从模板获取合并字段

$template = new \SplFileObject('template.docx');
$mergefields = $client->getMergefields($template);

以同步方式从模板生成带有给定合并数据的DOCX或PDF

$template = new \SplFileObject('template.docx');
$mergeData = [
        'field1' => 'value1',
        'field2' => 'value2',
];
$docxStream = $client->generateDocx($template, $mergeData);
$pdfStream = $client->generatePdf($template, $mergeData);

注意：文档生成方法返回 Psr\Http\Message\StreamInterface 实例。要将流读取到文件中，可以使用如下代码片段：

fwrite(fopen('result.pdf', 'w+'), $pdfStream->read($pdfStream->getSize()));

以异步方式从模板生成DOCX或PDF，带有给定合并数据

$template = new \SplFileObject('template.docx');
$mergeData = [
        'field1' => 'value1',
        'field2' => 'value2',
];
$jobId = $client->generateDocxAsync($template, $mergeData);
$jobId = $client->generatePdfAsync($template, $mergeData);

检查作业当前状态

注意：Gyselroth\DocumentEngine\Client::getJobStatus 在每个情况下（除了已注释的异常外）都会返回一个等于 Gyselroth\DocumentEngine\JobStatus 常量的字符串。

$jobStatus = $client->getJobStatus($jobId);

获取异步生成的文档

$documentStream = $client->getDocument($jobId);

异常

客户端的所有公共方法都可以抛出以下异常之一

Gyselroth\DocumentEngine\Client\Auth\AuthException
- 授权失败（HTTP 401 未授权），例如缺少认证
Gyselroth\DocumentEngine\Client\ClientException
- 客户端错误（HTTP 4xx，但不是HTTP 401 未授权），例如HTTP 400 请求错误
Gyselroth\DocumentEngine\Client\ServerException
- 服务器错误（HTTP 5xx），例如HTTP 500 服务器内部错误
Gyselroth\DocumentEngine\Client\ConnectionException
- 网络错误，例如服务器不可达

开发笔记

检出后安装

composer update

运行测试

单元测试

composer unittest

系统测试

export DOCENG_CLIENT_TEST_BASEURL=http://example.com
export DOCENG_CLIENT_TEST_AUTH_TYPE=basic
export DOCENG_CLIENT_TEST_BASIC_USER=test
export DOCENG_CLIENT_TEST_BASIC_PASSWORD=secret
composer systemtest

所有测试

export DOCENG_CLIENT_TEST_BASEURL=http://example.com
export DOCENG_CLIENT_TEST_AUTH_TYPE=basic
export DOCENG_CLIENT_TEST_BASIC_USER=test
export DOCENG_CLIENT_TEST_BASIC_PASSWORD=secret
composer test

历史

查看 CHANGELOG.md

作者和许可证

根据 Apache License, Version 2.0 ("许可证") 许可；除非符合许可证规定，否则不得使用此文件。您可以在以下位置获取许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或经书面同意，否则在许可证下分发的软件按“原样”提供，不提供任何明示或暗示的保证或条件。有关许可证的具体语言、权限和限制，请参阅许可证。

使用开源软件

gyselroth文档引擎客户端使用的开源软件包的版权属于其供应商，请参阅供应商包内的相关许可证。

gyselroth / document-engine-client

维护者

详细信息