README

此软件包提供SetaPDF-Signer组件的模块，允许您使用葡萄牙国家的“电子发票签名服务”(SAFE)，以纯PHP的方式对PDF进行数字签名。

关于实现的注释和说明

• 虽然文档称API符合CSC API，但我们注意到一些差异，这使得我们无法使用现有的CSC API模块。
• 由于我们不理解或说葡萄牙语，而官方文档仅提供葡萄牙语版本，我们尝试根据自动翻译和项目官方GitHub仓库中找到的OpenAPI规范定义来实现API。
• 我们还无法以葡萄牙公民的身份进行身份验证，因此依赖于用户提供测试凭据/令牌。
• 根据文档和/credentials/info端点提供的信息，散列算法固定为SHA256。

需求

您需要具有凭据和访问SAFE API端点的有效访问令牌。

此软件包在PHP >= 8.0上开发和测试。可以在此处找到SetaPDF-Signer组件的需求这里。

我们使用PSR-17 (HTTP Factories)和PSR-18 (HTTP Client)进行请求。因此，您需要实现这些。我们建议使用Guzzle。

    "require" : {
        "guzzlehttp/guzzle": "^7.0",
        "http-interop/http-factory-guzzle": "^1.0"
    }

安装

将以下内容添加到您的composer.json文件中

{
    "require": {
        "setasign/setapdf-signer-addon-safe": "^1.0"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://www.setasign.com/downloads/"
        }
    ]
}

然后执行composer update。您需要定义repository以解决对SetaPDF-Signer组件的依赖（有关更多详细信息，请参阅此处）。

用法

此软件包中所有类都位于命名空间setasign\SetaPDF\Signer\Module\SAFE中。有关工作示例，请参阅examples/文件夹。

Client类

此类是SAFE API的一种代理类。其构造函数需要以下参数

• $apiUri API的基本URL，例如https://pprsafe.autenticacao.gov.pt
• $basicAuthUsername HTTP基本身份验证的用户名
• $basicAuthPassword HTTP基本身份验证的密码
• $httpClient PSR-18 HTTP客户端实现。
• $requestFactory PSR-17 HTTP工厂实现。
• $streamFactory PSR-17 HTTP工厂实现。

如果您需要调用代理方法未覆盖的端点，可以使用 call(string $path, ?string $accessToken = null, array $inputData = []) 方法。

Module 类

这是 SetaPDF-Signer 的主模块，它实现了 SetaPDF_Signer_Signature_Module_ModuleInterface 接口。

内部通过使用 SetaPDF_Signer_Signature_Module_PadesProxyTrait 创建符合 PAdES 标准的签名。

其构造函数需要以下参数

• $accessToken - 通过自定义头 SAFEAuthorization 传递的访问令牌。
• $client - Client 类的实例。
• $credentialId - 凭据的 id（可以如 list-credentials.php 中演示的那样接收）。
• $processId - 进程 id（每次调用都有一个新的全局唯一标识符 (GUID)）。
• $clientName - clientName 字段的值。

此外，模块提供了一个 setDocumentName() 方法。此方法允许您定义与发送到 SAFE API 的哈希相关的文档名称。默认情况下，文档名称设置为 "document.pdf"。

Batch 类

此类允许您在单个签名流程中为多个 PDF 文件进行数字签名。

其构造函数需要以下参数

• $accessToken - 通过自定义头 SAFEAuthorization 传递的访问令牌。
• $client - Client 类的实例。
• $credentialId - 凭据的 id（可以如 list-credentials.php 中演示的那样接收）。
• $processId - 进程 id（每次调用都有一个新的全局唯一标识符 (GUID)）。
• $clientName - clientName 字段的值。

您可以将多个文件作为数组传递给 sign($files) 方法。

$files = [
    [
        'in' => string|SetaPDF_Core_Reader_ReaderInterface,
        'out' => 'path/to/result.pdf'    
    ]   
];

此外，sign() 方法接受回调，例如添加单个签名外观或签名属性。有关示例，请参阅 batch-complex.php 示例。

许可

此软件包是开源软件，根据 MIT 许可 许可。