Getting started with Dropbox Sign-embedded signing using PHP

You can either clone this repo and work on the basic branch, or you can access the complete code for the final output of this tutorial on the main branch.

git clone https://github.com/rexfordnyrk/documenter.git

Switch to the basic branch:

cd documenter && git checkout basic

Install both the PHP and JavaScript dependencies:

​​​​composer install && npm install

Create a .env file from the existing .env.example file:

cp .env.example .env

Then create an APP_KEY:

php artisan key:generate

The APP_KEY is a random string used for cryptographic operations, such as encrypting your application's user password for secure storage.

php artisan serve

In a different terminal, run the Node.js server:

npm run dev

The application will be served on http://localhost:8000. Upon opening the application in a browser, you should see an output like the image below:

A default user was created as part of the migration seeding. This default user’s username is documenter@yopmail.com and the password is 123456. You can directly log in to the application’s dashboard using these details.

Fill out the form’s General Information section of the form; the other sections are optional, so complete them if you like. In the General Information section, give your application a name and set the domain field to your app’s top level domain (TLD) (eg example.com). This information will be used in production for signing requests, but it won’t affect anything on development, such as your localhost.

Here, let’s add the Dropbox Sign PHP SDK to your existing application using Composer. Execute the require command in a terminal at the root of your project directory:

composer require "dropbox/sign:1.1.*"

Now you need to create two environment variables in the .env file to hold your API key and client ID. This is a recommended best practice in order to avoid exposing them by embedding them directly in your code.

Add the following lines to the end of the .env file in the root of your project directory:

DS_API_KEY=YOUR_API_KEY_HERE
DS_CLIENT_ID=YOUR_CLIENT_ID_HERE

Before you can create your first signature request, you need to add the required code to the app/Http/Controllers/SignatureRequestController.php file and the signature-requests/show blade template.

To get started, add the following code at the top of the SignatureRequestController.php file beneath the existing imports:

use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Redirect;
...

use Dropbox\Sign\Api\EmbeddedApi;
use Dropbox\Sign\Api\SignatureRequestApi;
use Dropbox\Sign\ApiException;
use Dropbox\Sign\Configuration;
use Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest;
use Dropbox\Sign\Model\SignatureRequestGetResponse;
use Dropbox\Sign\Model\SubSignatureRequestSigner;
use Dropbox\Sign\Model\SubSigningOptions;

use SplFileObject;
...

This imports the various classes from the SDK that you’ll be using to interact with the Dropbox Sign API.

Next, you want to add a function for making an API call to create your embedded signature request. You’ll use the information from the Create Signature Request form available in the resources/views/signature-requests/create.blade.php file. All the user-submitted information will be extracted into two variables passed on to the function. The parties who need to sign are extracted into the $signatories array and the rest of the form values in the $signaturerequest object.

Add the following performDSRequest function definition as a new method in the SignatureRequestController.php file:

public function performDSRequest(Array $signatories, SignatureRequest $request){
        //getting default configuration
        $config = Configuration::getDefaultConfiguration();
        // Configure HTTP basic authorization: api_key
        $config->setUsername(env('DS_API_KEY'));
        $signatureRequestApi = new SignatureRequestApi($config);

        $signers = [];
        for ($i = 0; $i < count( $signatories); $i++) {
            //creating a new Dropbox Sign Signer
            $signer = new SubSignatureRequestSigner();
            //Setting Signer Properties from Signatories Specified in the form
            $signer->setEmailAddress($signatories[$i]->email)
                ->setName($signatories[$i]->name)
                ->setOrder($i);
            //adding signer to list (array) of signers
            $signers[] = $signer;
        }

        //Setting option to determine how the user signs
        $signingOptions = new SubSigningOptions();
        $signingOptions->setDraw(true)
            ->setType(true)
            ->setUpload(true)
            ->setPhone(true)
            ->setDefaultType(SubSigningOptions::DEFAULT_TYPE_DRAW);

        //Creating a Dropbox Sign Embedded signature request and assigning the necessary properties
        $data = new SignatureRequestCreateEmbeddedRequest();
        //using client id place in .env file
        $data->setClientId(env('DS_CLIENT_ID'))
            ->setTitle($request->title)
            ->setSubject($request->title)
            ->setMessage($request->description)
            ->setSigners($signers)
            ->setCcEmailAddresses([
                "legal@wehire.io",
            ])
            ->setFiles([new SplFileObject(storage_path('app/' . $request->document))])
            ->setSigningOptions($signingOptions)
            ->setTestMode(true);

        try {
            //Making API call to Dropbox Sign to create Embedded signature request and returning response
            return $signatureRequestApi->signatureRequestCreateEmbedded($data);
        } catch (ApiException $e) {
            // if there is an error return the error
            return $e->getResponseObject()->getError();
        }
    }
    

The method above sets the configuration for the SDK using the DS_API_KEY and DS_CLIENT_ID environment variables you recently added. The configuration creates a signature request API object, which will be used later to make the API request.

The behavior of the signing process is defined, allowing the user to draw, type, or upload their signature. An object is created to hold the body of the request, and the title, subjects, and message are set. These details are used to send email notifications to the cc’d email addresses included in the embedded request. Generally, embedded workflows do not provide email notifications to the signers. However, by including the cc_email_addresses parameter, notifications of the final signed document will be sent to those emails included in the request. As you can see, this example cc’s the legal team.

Finally, in the try-catch block, the API request is made to Dropbox Sign, and the response is returned. If there’s an error making the request, it would be caught and returned in the catch block.

You need to call this function in the part of your application that handles the form processing—in this case, it’s the store() method inside the SignatureRequestController.php file. Paste the following code right before the $signatureRequest->signatories()->saveMany($signatories) function call:

$results = $this->performDSRequest($signatories, $signatureRequest);
    if ($results instanceof SignatureRequestGetResponse) {
    
        $signatureRequest->reference_id = $results->getSignatureRequest()->getSignatureRequestId();
        $signatureRequest->save();
        $signers = $results->getSignatureRequest()->getSignatures();
    
        //looping through the signers and assigning their DS signature_id
        // to the signatory to be used to generate signing page.
        if (count($signers) > 1){
            for ($i = 0; $i < count($signers); $i++) {
                $signatories[$signers[$i]->getOrder()]->ds_signature_id = $signers[$i]->getSignatureId();
            }
        }else{
            $signatories[0]->ds_signature_id = $signers[0]->getSignatureId();
        }
    }else{
        return Redirect::to('/dashboard')
            ->with('error', 'There was an error completing your request.Please contact tech support.\n'.$results);
    }

This checks to ensure that the results are a valid response obtained from the API, and extracts the signatureRequestId to be stored as a reference_id. The respective signature IDs of each signer are obtained and stored to the database. You can use these later to check the status of a signature request or download a signed file. The signature ID for individual signers is used to generate temporary unique URLs for accessing and signing the documents.

You’ll use the signature ID of each signer to obtain a temporary unique URL that allows the user to sign a document. But before you can generate a signURL, you need to know the user’s signature_id. This is returned as part of the response when you make an embedded signature request.

The `show()` method of the SignatureRequestController.php file handles all HTTP requests to view the details of a specific `SignatureRequest` in this application. The ID specified through the URL fetches that SignatureRequest record from the database, which is in turn used to populate the frontend.

Paste the following snippet right before the return statement of the show() method in the SignatureRequestController.php file:

//getting default configuration
$config = Configuration::getDefaultConfiguration();
// Configure HTTP basic authorization: api_key
$config->setUsername(env('DS_API_KEY'));
$embeddedApi = new EmbeddedApi($config);

//obtaining signing id if the current user is a signatory
$signatory = $signatureRequest->signatories->where('email', Auth::user()->email)->first();
if ($signatory != null){
    //if the current user is a valid signatory then generate embedded sign url using their signature_id
    try {
        $result = $embeddedApi->embeddedSignUrl($signatory->ds_signature_id);
        $signatureRequest['sign_url']=$result->getEmbedded()->getSignUrl();
    } catch (ApiException $e) {
        $error = $e->getResponseObject();
        return view('signature-requests.show', compact('signatureRequest'))
            ->with('error', 'There was an error completing your request. Please contact tech support.\n'.$error);
    }
}

This snippet initializes the SDK and an EmbeddedAPI object. If the current user is recognized as a signatory on the request, their signature ID is extracted and used to obtain a signURL for that SignatureRequest. The URL string is then passed to the frontend to be used later.

Now you can open the resources/views/signature-requests/show.blade.php file. This file contains the code that shows the details of a single signature request. Paste the following snippet at the bottom of the file, right before the closing x-app-layout tag.

    <script src="/embedded.production.min.js"></script>
    <script>
        //obtaining clientID from .env file
        const clientid = '{!! env('DS_CLIENT_ID')  !!}';
        //assigning the url
        const signUrl = '{!! $signatureRequest->sign_url !!}';

        function signDoc() {
            const client = new HelloSign();
            client.open( signUrl, {
                clientId: clientid,
                skipDomainVerification: true,
                testMode: true
            });
        }
    </script> 

@if (isset($signatureRequest->sign_url))
    <a href="#" onclick="signDoc()" class="bg-green-500 hover:bg-green-700 text-white font-bold py-2 px-4 rounded">Sign Document</a>
@endif