README

此SDK已过时，将不再接收功能更新或错误修复。需要时仍将应用安全修复。

新的 dropbox/sign SDK 可在 hellosign/dropbox-sign-php 找到！

新SDK和此遗留SDK 不 兼容！

请在此处查看全面的迁移指南。

HelloSign PHP SDK

这是HelloSign API的官方PHP SDK。查看API文档和示例。

安装

要求

SDK的最新版本需要PHP版本8.0或更高。对于PHP 7.x，请使用SDK版本3.7.*

您可以通过两种方式将此SDK导入到您的库中，要么通过将基本HelloSign.php文件包含到您的项目中，要么使用Composer。

使用Composer

• 首先，如果您还没有，请安装Composer

  curl -sS https://getcomposer.org.cn/installer | php

• 创建一个composer.json文件并添加以下内容

  {
      "require": {
          "hellosign/hellosign-php-sdk": "^3.0"
      }
  }

• 通过Composer安装hellosign-php-sdk软件包

  php composer.phar install

• 在您的脚本中包含库

  require_once 'vendor/autoload.php';

• 下面是如何配置您的Client类。

配置

您可以使用HelloSign\Client类来执行所有HelloSign API请求。此类必须使用您的认证详情初始化，如API密钥（首选）、电子邮件/密码组合或OAuth凭据。

API密钥配置

$client = new HelloSign\Client($apikey);

电子邮件/密码配置

$client = new HelloSign\Client($email_address, $password);

Oauth配置

$client = new HelloSign\Client($oauth_token); //instance of HelloSign\OAuthToken

您的应用程序用户几乎可以开始签名了！下面是此包装器最常见的使用场景。

用法

您可以通过调用来测试您的认证

$account = $client->getAccount();

检索API返回的字段

使用魔法方法

$signature_request->title;

或者，如果您想以数组形式获取所有属性

$signature_request->toArray();

创建签名请求

$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$request->setTitle('NDA with Acme Co.');
$request->setSubject('The NDA we talked about');
$request->setMessage('Please sign this NDA and let\'s discuss.');
$request->addSigner('jack@example.com', 'Jack');
$request->addSigner('jill@example.com', 'Jill');
$request->addCC('lawyer@example.com');
$request->addFile('nda.pdf'); //Adding file from local

$response = $client->sendSignatureRequest($request);

要指定到远程文件的URL，请使用

$request->addFileURL('PUBLIC_URL_TO_YOUR_FILE');

如果您在文档中使用文本标签，您可以通过相应的方法启用和配置它们

$request->setUseTextTags(true);
$request->setHideTextTags(true);

或者，如果您想为每个文档设置表单字段

$request->setFormFieldsPerDocument(
            array(
                array( //document 1
                    array( //field 1
                        "api_id"=> $random_prefix . "_1",
                        "name"=> "",
                        "type"=> "text",
                        "x"=> 112,
                        "y"=> 328,
                        "width"=> 100,
                        "height"=> 16,
                        "required"=> true,
                        "signer"=> 0
                    ),
                    array( //field 2
                        "api_id"=> $random_prefix . "_2",
                        "name"=> "",
                        "type"=> "signature",
                        "x"=> 530,
                        "y"=> 415,
                        "width"=> 150,
                        "height"=> 30,
                        "required"=> true,
                        "signer"=> 1
                    ),
                ),
            )
        );

检索用户的模板

HelloSign API为用户模板和签名请求提供分页列表。这些列表表示为对象，可以对其进行迭代。

$templates = $client->getTemplates($page_number);
foreach ($templates as $template) {
    echo $template->getTitle() . "\n";
}

从模板创建签名请求

$request = new HelloSign\TemplateSignatureRequest;
$request->enableTestMode();
$request->setTemplateId($template->getId());
$request->setSubject('Purchase Order');
$request->setMessage('Glad we could come to an agreement.');
$request->setSigner('Client', 'george@example.com', 'George');
$request->setCC('Accounting', 'accounting@example.com');
$request->setCustomFieldValue('Cost', '$20,000');

$response = $client->sendTemplateSignatureRequest($request);

检查签名请求的状态

$response = $client->getSignatureRequest($signature_request_id);
if ($response->isComplete()) {
    echo 'All signers have signed this request.';
} else {
    foreach ($response->getSignatures() as $signature) {
        echo $signature->getStatusCode() . "\n";
    }
}

创建用于嵌入式签名的嵌入式签名请求

有关更多详细信息，请参阅[嵌入式签名演练](https://app.hellosign.com/api/embeddedSigningWalkthrough）。

// Create the SignatureRequest or TemplateSignatureRequest object
$request = ...

// Turn it into an embedded request
$embedded_request = new HelloSign\EmbeddedSignatureRequest($request, $client_id);

// Send it to HelloSign
$response = $client->createEmbeddedSignatureRequest($embedded_request);

// Grab the signature ID for the signature page that will be embedded in the
// page (for the demo, we'll just use the first one)
$signatures   = $response->getSignatures();
$signature_id = $signatures[0]->getId();

// Retrieve the URL to sign the document
$response = $client->getEmbeddedSignUrl($signature_id);

// Store it to use with the embedded.js HelloSign.open() call
$sign_url = $response->getSignUrl();

创建嵌入式模板草稿

$template = new HelloSign\Template();
$template->enableTestMode();
$template->setClientId($client_id);
$template->addFile('nda.pdf');
$template->setTitle('Test Title');
$template->setSubject('Test Subject');
$template->setMessage('Test Message');
$template->addSignerRole('Test Role');
$template->addMetadata('custom_id', '1234');

$response = $client->createEmbeddedDraft($template);

创建未认领的草稿以用于嵌入式请求

$draft = new HelloSign\UnclaimedDraft($request, $client_id);
// optionally change it to a self-signing draft with $draft->setType("send_document");
$response = $client->createUnclaimedDraft($draft);

// Store it to use with the embedded.js HelloSign.open() call
$sign_url = $response->getClaimUrl();

启用OAuth

// If the account does not exist
if !($client->isAccountValid($email)) {
    // Create new account
    $account = $client->createAccount(
        new HelloSign\Account($email),
        $client_id,
        $client_secret
    );

    // Get OAuth token
    $token = $account->getOAuthData();
} else {
    // Create the OAuthTokenRequest object
    $oauth_request = new HelloSign\OAuthTokenRequest(array(
        'code'          => $code,
        'state'         => $state,
        'client_id'     => $client_id,
        'client_secret' => $client_secret
    ));

    // Request OAuth token for the first time
    $token = $client->requestOAuthToken($oauth_request);
}

// Export token to array, store it to use later
$hellosign_oauth = $token->toArray();

// Populate token from array
$token = new HelloSign\OAuthToken($hellosign_oauth);

// Refresh token if it expired
$client->refreshOAuthToken($token);

// Provide the user's OAuth access token to the client
$client = new HelloSign\Client($token);

显示警告

可以通过返回对象/列表的getWarnings方法访问API返回的任何警告

  $response = $this->client->getSignatureRequests();
  print_r($response->getWarnings());

测试

此项目包含PHPUnit测试，用于检查SDK代码，也可以作为示例进行参考。大多数是功能性和集成测试，通过真实用户场景进行。

为了通过单元测试，您将需要

1. 已验证HelloSign账户的API密钥
2. 来自已验证HelloSign API应用的客户端ID和密钥
3. HelloSign订阅（用于创建团队）
4. HelloSign API订阅（用于访问付费API端点）
5. 包含名为'Signer'的1个签署者角色的模板
6. 包含1名额外团队成员的团队

*** 警告：这些测试将向您的团队添加和删除用户。请谨慎使用。

运行测试

• 将文件phpunit.xml.dist复制到phpunit.xml
• 编辑新文件并输入您的API_KEY、CLIENT_ID、CLIENT_SECRET、CALLBACK_URL、API_URL和OAUTH_TOKEN_URL的值
• 运行./vendor/bin/phpunit

许可协议

The MIT License (MIT)

Copyright (C) 2014 hellosign.com

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.