Menjana PDF daripada kod PHP dan menambah eTandatangan

Thinus Swart

July 9, 2024

minit bacaan

Produk hebat yang sama dengan wajah baru! HelloSign kini dikenali sebagai Dropbox Sign.

In the world of digital communications, there is probably no other file format that is as ubiquitous as a PDF file. You've probably received hundreds if not thousands of PDF files in your inbox for all sorts of use cases, both business and personal.

The utilization of PDF files has been increasingly expanding, specifically when it comes to adopting electronic signatures (aka eSignatures). An eSignature is an electronic way of signing a document to make it legally binding between multiple parties. Integrating eSignature functionality directly into your PDF reduces friction for end users and streamlines your document workflow.

In this tutorial, you'll learn all about Dropbox Sign and how you can use their official PHP SDK to create and send signable PDFs via the Dropbox Sign API.

‍

Dropbox Sign use cases

The Dropbox Sign API can be used to simplify, enhance, and automate any existing processes you might already have in your organization that require a signature.

For instance, financial institutions can generate signable loan agreements or consulting agreements straight from a web form or an online client inquiry. Human resources departments can send eSignature-enabled contracts to prospective hires straight from a database without needing to fill in any paperwork. Or a possible conflict-of-interest document can be sent straight to an employee's inbox for signing.

These time-consuming processes, which typically involve numerous steps, can be streamlined by integrating eSignatures, making virtually any document that normally requires an in-person signature convertible to one using eSignatures, unless governed by specific laws that mandate physical signatures.

‍

Implementing an eSignature workflow using PHP and the Dropbox Sign API

In this article, you'll learn how to create a backend PHP application to interface with the Dropbox Sign API so that you can automate the procedure of sending documents that require a signature.

In this scenario, you're dealing with a nondisclosure agreement (NDA). An NDA is a binding agreement between your organization and another party that states that the signing party will keep secret any information they might be able to gather while working on your premises or working with your codebase. Contractors or developers who need access to your existing code, infrastructure, or other intellectual property are usually required to sign one.

Normally, this process would be tedious, with documents being emailed around, printed, signed, scanned, and so forth.

In the following hypothetical use case, you're a developer for "The Company". You've been tasked with automating the process of onboarding external developers, specifically the part of the process where the external developers need to sign an NDA before they can begin working on existing projects.

You've decided to automate the process using a PHP application and the Dropbox Sign PHP SDK.

‍

Prerequisites

Before you begin writing your application, you need the following:

‍A Dropbox Sign account
- ‍‍You will need to subscribe to one of the paid plans to enable uploading signable templates via the web interface.

‍Your Dropbox Sign API key.
A template PDF file that can be signed. Or you can use the template file supplied in this GitHub repository.
‍PHP 7.4 or newer.

‍

Create your template file

The easiest way to prepare a document for signing is by using the Dropbox Sign template system.

Once you've signed in to your Dropbox Sign console, you have to click on Templates, which will show you a list of all your uploaded templates:

‍

From the Templates page, click the Create template button at the top right-hand corner to get started:

Combined Menu and Create template button

‍

While you can use any PDF, this tutorial uses the Non-Disclosure Agreement.pdf file that is available in this GitHub repository. Upload that file (or your own file) to the template and then select Choose:

‍

Next, you need to create a signer role. Enter "Recipient" and click Next:

‍

When your editor loads, you'll be able to add fields to the PDF file. Start with the Auto-fill fields and add a Date signed field on top of the Date Signed line on your form:

‍

You may have to scroll to the bottom of the uploaded form to get to the section where you want to place your fields.

Next, add the Signature field:

‍

Once you've placed the Signature field, you need to set some options. Select the field on the form, and then set the options on the right-hand side of the designer screen:

‍

Once you're done placing your fields, click Next on the bottom-right corner of the designer.

At this point, you are asked to review your template before you save it and give it a name:

‍

Once completed, click on Save template, and it's ready to be used for signature requests.

‍

Install Composer

‍Composer is a dependency manager for PHP projects. It manages any libraries that your project depends on, and it installs and/or updates the packages your project needs on your behalf.

The installation instructions are a bit more involved than just running an APT command, so make sure to follow the instructions carefully.

Download the Composer package as specified on the Download page.

Once you've followed those instructions, there should be a composer.phar file in the directory where you ran the commands. It's recommended to make this executable available globally so you can move it to a directory that's in your $PATH variable:


sudo mv composer.phar /usr/local/bin/composer

‍

While you don't need to install Composer, it's highly recommended as it makes the process of installing the Dropbox Sign SDK much easier. The rest of this tutorial assumes that Composer is installed. If you are using a different PHP dependency manager, adjust your commands accordingly.

Once you've downloaded Composer, everything is ready for your PHP application.

‍

Write your PHP application

The next part of this tutorial teaches you how to get started writing an application that can interface with the Dropbox API, retrieve the template ID for your uploaded NDA template, and then initiate the signature request process. Ultimately, the application checks on the progress of a signature request and downloads the signed PDF once the signature process has been completed.

‍

Install your dependencies

The first thing you need to do is create a composer.json file that contains the following lines:


{
    "require": {
        "dropbox/sign": "^1.2.0"
    },
    "minimum-stability": "dev"
}

‍

This composer.json file tells your dependency manager (Composer) which external packages you would like to download and include in your PHP application. If you're expanding on your application and it needs other packages, you use the same composer.json file to add the other packages to your application.

Now, you can run composer install to install the packages listed in composer.json.

Depending on your system setup, it might work immediately, or composer might tell you that other prerequisites are required. On the test system, it needs the PHP curl and mbstring extensions to be installed first. Resolve any errors you might have on your side:


sudo apt install php-curl php-mbstring

‍

Then run composer install again:


Loading composer repositories with package information
Updating dependencies
Lock file operations: 9 installs, 0 updates, 0 removals
  - Locking dropbox/sign (1.2.0)
  - Locking guzzlehttp/guzzle (7.9.x-dev 41042bc)
  - Locking guzzlehttp/promises (2.0.x-dev bbff78d)
  - Locking guzzlehttp/psr7 (2.6.x-dev 45b30f9)
  - Locking psr/http-client (dev-master bb5906e)
  - Locking psr/http-factory (dev-master 7037f4b)
  - Locking psr/http-message (dev-master 402d35b)
  - Locking ralouphie/getallheaders (3.0.3)
  - Locking symfony/deprecation-contracts (dev-main 7c3aff7)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 9 installs, 0 updates, 0 removals
  - Downloading ralouphie/getallheaders (3.0.3)
  - Downloading psr/http-message (dev-master 402d35b)
  - Downloading psr/http-factory (dev-master 7037f4b)
  - Downloading guzzlehttp/psr7 (2.6.x-dev 45b30f9)
  - Downloading symfony/deprecation-contracts (dev-main 7c3aff7)
  - Downloading psr/http-client (dev-master bb5906e)
  - Downloading guzzlehttp/promises (2.0.x-dev bbff78d)
  - Downloading guzzlehttp/guzzle (7.9.x-dev 41042bc)
  - Downloading dropbox/sign (1.2.0)
  - Installing ralouphie/getallheaders (3.0.3): Extracting archive
  - Installing psr/http-message (dev-master 402d35b): Extracting archive
  - Installing psr/http-factory (dev-master 7037f4b): Extracting archive
  - Installing guzzlehttp/psr7 (2.6.x-dev 45b30f9): Extracting archive
  - Installing symfony/deprecation-contracts (dev-main 7c3aff7): Extracting archive
  - Installing psr/http-client (dev-master bb5906e): Extracting archive
  - Installing guzzlehttp/promises (2.0.x-dev bbff78d): Extracting archive
  - Installing guzzlehttp/guzzle (7.9.x-dev 41042bc): Extracting archive
  - Installing dropbox/sign (1.2.0): Extracting archive
3 package suggestions were added by new dependencies, use composer suggest to see details.
Generating autoload files
4 packages you are using are looking for funding.
Use the composer fund command to find out more!

‍

Your application directory should now have a vendor directory inside it that contains the SDK packages that you need to start writing your application.

‍

Retrieve your template ID

Create the first of your PHP scripts and call it getTemplates.php:


<?php

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

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("<API_KEY_HERE>");

$templateApi = new Dropbox\Sign\Api\TemplateApi($config);

$accountId = "<EMAIL_ADDRESS_YOU_SIGNED_UP_WITH>";

try {
    $result = $templateApi->templateList($accountId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

‍

Make sure you replace <API_KEY_HERE> and <EMAIL_ADDRESS_YOU_SIGNED_UP_WITH> with the correct values.

Run the following command from the command line:


php getTemplates.php

‍

Your response should include the template you created with its template_id:


Dropbox\Sign\Model\TemplateListResponse Object
(
    [container:protected] => Array
        (
            [templates] => Array
                (
                    [0] => Dropbox\Sign\Model\TemplateResponse Object
                        (
                            [container:protected] => Array
                                (
                                    [template_id] => acd0...
                                    [title] => Standard NDA
                                    [message] => Please sign our standard NDA before we can move on to other business
                                    [updated_at] => 1701696775
                                    [is_embedded] => 
                                    [is_creator] => 1
                                    [can_edit] => 1
                                    [is_locked] => 
                                    [metadata] => Array
                                        (
                                        )

                                    [signer_roles] => Array
                                        (
                                            [0] => Dropbox\Sign\Model\TemplateResponseSignerRole Object
                                                (
                                                    [container:protected] => Array
(
                                                            [name] => Recipient
                                                            [order] => 
                                                        )
                                                )
  )

                                    [cc_roles] => Array
                                        (
                                        )
...

‍

In this example output, you can see the template ID that starts with acd0. Copy that value somewhere. You need it to send the document for signing.

‍

Send your first signature request

Create another PHP file called sendRequestWithTemplate.php:


<?php

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

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("<API_KEY_HERE>");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
$signer1->setRole("Recipient")
    ->setEmailAddress("<RECIPIENT_EMAIL_ADDRESS>")
    ->setName("<RECIPIENT_NAME>");

$signingOptions = new Dropbox\Sign\Model\SubSigningOptions();
$signingOptions->setDraw(true)
    ->setType(true)
    ->setUpload(true)
    ->setPhone(false)
    ->setDefaultType(Dropbox\Sign\Model\SubSigningOptions::DEFAULT_TYPE_DRAW);

$data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
$data->setTemplateIds(["acd0e66d82692a5de20fd4af0544e20231d224da"])
    ->setSubject("Non-Disclosure Agreement")
    ->setMessage("Please sign our standard NDA before we can move on to other business")
    ->setSigners([$signer1])
    ->setSigningOptions($signingOptions)
    ->setTestMode(true);

try {
    $result = $signatureRequestApi->signatureRequestSendWithTemplate($data);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

‍

Again, replace the values for the placeholders <API_KEY_HERE>, <RECIPIENT_EMAIL_ADDRESS>, and <RECIPIENT_NAME>. In a production setup, you would probably be interfacing with a database of some kind to pull in those values instead of editing and running the PHP script manually.

Also, notice the option ->setTestMode(true). This indicates that the file you're sending now is not legally binding. Remember to change that value to false once you have an application ready to use in production.

Now, run the file:


php sendRequestWithTemplate.php

‍

If it's successful, the output should look something like this:

‍

Notice that you have test_mode with a value of 1. This is a parameter that tells the API you are testing the signature request system. Any request generated with this parameter is considered to be not legally binding. Remember to update or remove the parameter once you’re ready to move your code to production.

The response you received contains a lot of information. It basically tells you that the system has fired off a signature request and that the request is on its way to the person you specified. However, you don't need most of the information. The most important information is the signature_request_id. You need that to check on the status of the signature.

‍

Verify the progress of the signature

Create another file called getRequestProgress.php:


<?php

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

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("<API_KEY_HERE>");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "<SIGNATURE_REQUEST_ID>";

try {
    $result = $signatureRequestApi->signatureRequestGet($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

‍

Running this command shows you the progress of the signature request. You're really interested in only the [status_code], so you can make your life easier using grep (a standard Linux utility) to look for the lines with only that value:


php getRequestProgress.php | grep "status_code"

‍

If you want to see the full output, omit the | grep "status_code" part of the command. Otherwise, the output looks like this:


[status_code] => awaiting_signature

‍

As you can see, you're still waiting for the signer to sign the NDA. They should have received the signature request with a link in their email that takes them through to a website where they can sign the document. Once they've completed the signature process, the status of the signature request ID will look like this:


php getRequestProgress.php | grep "status_code"
[status_code] => signed

‍

Download and save the signed document

In order to retrieve the signed document, you need to create a file called getSignedDocument.php:


<?php

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

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("<API_KEY_HERE>");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "<SIGNATURE_REQUEST_ID>";
$fileType = "pdf";

try {
    $result = $signatureRequestApi->signatureRequestFiles($signatureRequestId, $fileType);
    copy($result->getRealPath(), __DIR__ . '/signed_response.pdf');
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

‍

Don't forget to replace the values for <API_KEY_HERE> and <SIGNATURE_REQUEST_ID> with your values and run the file:


php getSignedDocument.php

‍

There won't be any output, but once the script has run, you can check for PDF files in the application directory:


ls *pdf
signed_response.pdf

‍

Open the signed_response.pdf file using any PDF viewer:

‍

And the signed file is now in your possession.

Something to note: While you can query the endpoint for a specific signature ID’s status, this method does not scale well with many signature requests, and you might end up getting rate-limited. Dropbox recommends that you set up your application with a callback URL, and you will receive notifications of events that have occurred, like a signature request being completed. You can then act on these events, rather than polling the endpoint constantly.

See this link for more information regarding event callbacks.

‍