# PHP

> Use this guide to migrate to the new Dropbox Sign PHP SDK, which is powered by our OpenAPI specification. Contains concepts and examples to help you migrate successfully.

# PHP Migration Guide

## Migrating the PHP SDK from `hellosign/hellosign-php-sdk` to `dropbox/sign`

<SdkIntro sdkLanguage="PHP" sdkRepoUrl="https://packagist.org/packages/dropbox/sign" />

## Architecture and Tooling

<SdkUsage sdkLanguage="PHP" sdkRepoUrl="https://packagist.org/packages/dropbox/sign" sdkPackageManager="packagist" sdkName="dropbox/sign" referenceLink="https://github.com/hellosign/dropbox-sign-php/blob/main/README.md#getting-started" examplesLink="https://github.com/hellosign/dropbox-sign-php/tree/main/examples" />

## Core Concepts and Patterns

This section contains the core concepts and patterns of the new SDK and highlights differences from the legacy SDK.

### Installation

There are two methods for installing the new SDK:

<div justifyContent="space-around">
  <BoxWithLabel color="rainbow" label="Install from Packagist" size="100%">
    <ol>
      <li>
        To install from Packagist run:
        <pre><code>composer require dropbox/sign</code></pre>
      </li>
    </ol>
  </BoxWithLabel>
</div>

<div justifyContent="space-around">
  <BoxWithLabel color="rainbow" label="Build from Source" size="100%">
    <ol>
      <li>
        <a href="https://github.com/hellosign/dropbox-sign-php/archive/refs/heads/main.zip" target="_blank">
          Download
          the package ZIP
        </a>
      </li>

      <li>
        Move the downloaded file (<code>dropbox-sign-php-main.zip</code> or similar) to your project directory
      </li>

      <li>
        In the <code>respositories</code> array of your <code>composer.json</code> file, add
        <pre><code>\{ "type": "artifact", "url": "./PATH\_TO\_DIRECTORY\_WITH\_ZIP\_FILE" }</code></pre>
      </li>

      <li>
        Run <code>composer install</code>
      </li>
    </ol>
  </BoxWithLabel>
</div>

<HR />

### Importing the SDK

Use Composer to autoload the package when needed.

<div justifyContent="space-around">
  <BoxWithLabel color="rainbow" label="Legacy SDK">
    <p>
      Use 

      <b>require</b>

       statement to bring in the entire Dropbox Sign SDK.
    </p>
  </BoxWithLabel>

  <BoxWithLabel color="rainbow" label="New SDK">
    <p>
      Use 

      <b>import</b>

       statement to add the entire SDK or only the pieces you need.
    </p>
  </BoxWithLabel>
</div>

<CodeBlocks>
  ```php Legacy SDK - import
  <?php

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

  use HelloSign;

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

  ```php New SDK - import
  <?php

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

  // import the entire SDK

  use Dropbox;

  $signatureApi = new Dropbox\Sign\Api\SignatureRequestApi();

  // import the entire SDK and create an alias
  use Dropbox\Sign as DropboxSign;

  $signatureApi = new DropboxSign\Api\SignatureRequestApi();

  // or add only what you need
  use Dropbox\Sign\Api\SignatureRequestApi;

  $signatureApi = new SignatureRequestApi();
  ```
</CodeBlocks>

<HR />

### Authentication

| Legacy SDK                                                                                           | New SDK                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The API key, Email/Password combination or access token was needed to instantiate a `Client` object. | The API key or access token are utilized to configure HTTP basic auth or Bearer auth, respectively. Subsequently, this configuration object is used for the instantiation of API group endpoint classes within the SDK. |

<CodeBlocks>
  ```php Legacy SDK - Configuration
  <?php

  require_once 'vendor/autoload.php';

  // API Key config
  $client = new HelloSign\Client($apikey);

  // Email/Password config
  $client = new HelloSign\Client($email_address, $password);

  // OAuth config
  $client = new HelloSign\Client($access_token); //instance of HelloSign\OAuthToken
  ```

  ```php New SDK - Configuration
  <?php

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

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

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

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

  // Configuration object passed to Signature Request object instantiation
  $embeddedSignature = new Dropbox\Sign\Api\SignatureRequestApi($config);
  ```
</CodeBlocks>

<HR />

### Endpoints Grouped into Classes

The new SDK divides endpoints across unique Classes:

| Class Name and Reference                                                                                       | API Reference                                              |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [AccountApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/AccountApi.md)                   | [/account/\* Endpoints](/api/account)                      |
| [ApiAppApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/ApiAppApi.md)                     | [/api\_app/\* Endpoints](/api/api-app)                     |
| [BulkSendJobApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/BulkSendJobApi.md)           | [/bulk\_send\_job/\* Endpoints](/api/bulk-send-job)        |
| [EmbeddedApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/EmbeddedApi.md)                 | [/embedded/\* Endpoints](/api/embedded)                    |
| [OAuthApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/OAuthApi.md)                       | [/oauth/\* Endpoints](/docs/guides/o-auth/overview)        |
| [ReportApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/ReportApi.md)                     | [/report/\* Endpoints](/api/report)                        |
| [SignatureRequestApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/SignatureRequestApi.md) | [/signature\_request/\* Endpoints](/api/signature-request) |
| [TeamApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/TeamApi.md)                         | [/team/\* Endpoints](/api/team)                            |
| [TemplateApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/TemplateApi.md)                 | [/template/\* Endpoints](/api/template)                    |
| [UnclaimedDraftApi](https://github.com/hellosign/dropbox-sign-php/blob/main/docs/Api/UnclaimedDraftApi.md)     | [/unclaimed\_draft/\* Endpoints](/api/unclaimed-draft)     |

<HR />

### Using Models to Pass Parameters

[Models](https://github.com/hellosign/dropbox-sign-php/blob/main/README.md#models) are used to define the structure and value of the parameters being passed. The fully assembled model is passed to the API endpoint method.

**New SDK Using Models to Pass Parameters**

```php
<?php

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

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

$config->setUsername("YOUR_API_KEY");

$apiAppApi = new Dropbox\Sign\Api\ApiAppApi($config);

$oauth = new Dropbox\Sign\Model\SubOAuth();
$oauth->setCallbackUrl("https://example.com/oauth")
    ->setScopes([
        Dropbox\Sign\Model\SubOAuth::SCOPES_BASIC_ACCOUNT_INFO,
        Dropbox\Sign\Model\SubOAuth::SCOPES_REQUEST_SIGNATURE,
    ]);

$whiteLabelingOptions = new Dropbox\Sign\Model\SubWhiteLabelingOptions();
$whiteLabelingOptions->setPrimaryButtonColor("#00b3e6")
    ->setPrimaryButtonTextColor("#ffffff");

$customLogoFile = new SplFileObject(__DIR__ . "/CustomLogoFile.png");

$data = new Dropbox\Sign\Model\ApiAppCreateRequest();
$data->setName("My Production App")
    ->setDomains(["example.com"])
    ->setOauth($oauth)
    ->setWhiteLabelingOptions($whiteLabelingOptions)
    ->setCustomLogoFile($customLogoFile);

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

<HR />

### Path and Query Parameters

In the legacy SDK you would pass Path and Query parameters alongside any POST data to the API endpoint:

**Legacy SDK - Path and Query Parameters**

```php
<?php

require_once 'vendor/autoload.php';

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

$emailAddress = "john@example.com";
$signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";

$response = $client->requestEmailReminder($signatureRequestId, $emailAddress);
print_r($response);
```

The new SDK now requires POST data be an object when calling any API endpoint. Path and Query parameters must be passed individually to these methods.

**New SDK - Path and Query Parameters**

```php
<?php

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

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

$config->setUsername("YOUR_API_KEY");

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

$data = new Dropbox\Sign\Model\SignatureRequestRemindRequest();
$data->setEmailAddress("john@example.com");

$signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";

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

<HR />

### Error Handling and Warnings

The New SDK handles errors and warnings differently.

#### Error Handling

Errors are an instance of [Dropbox\Sign\ApiException](https://github.com/hellosign/dropbox-sign-php/blob/main/src/ApiException.php) with its `getResponseObject()` method returning an instance of [Dropbox\Sign\Model\ErrorResponse](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/ErrorResponse.php) class and should be handled using Try/Catch blocks.

**New SDK - Error Handling**

```php
<?php

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

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

$config->setUsername("YOUR_API_KEY");

$accountApi = new Dropbox\Sign\Api\AccountApi($config);

try {
    $result = $accountApi->accountGet(null, 'jack@example.com');
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}
```

#### Warnings

Warnings are a list of [Dropbox\Sign\Model\WarningResponse](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/WarningResponse.php).

**New SDK - Warnings**

```php
<?php

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

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

$config->setUsername("YOUR_API_KEY");

$api = new Dropbox\Sign\Api\AccountApi($config);

$data = new Dropbox\Sign\Model\AccountCreateRequest();
$data->setEmailAddress("newuser@dropboxsign.com");

try {
    $result = $api->accountCreate($data);
    print_r($result);

    // warning loop
    foreach ($result->getWarnings() as $warning) {
        print_r("Warning Name: {$warning->getWarningName()}");
        print_r("Warning Message: {$warning->getWarningMsg()}");
    }
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}
```

<HR />

### Instantiating Objects From Data

There are three ways to instantiate an object.

* You can instantiate a class directly and pass an array of data
* You can use setter methods
* You can use the `init()` static method

<CodeBlocks>
  ```php New SDK - Using Constructor With Array of Data
  $signer1 = new Dropbox\Sign\Model\SubSignatureRequestSigner([
      "email_address" => "jack@example.com",
      "name"          => "Jack",
      "order"         => 0,
  ]);

  $attachment1 = new Dropbox\Sign\Model\SubAttachment([
      "name"         => "Attachment 1",
      "instructions" => "Please download this file",
      "signer_index" => 0,
      "required"     => true,
  ]);
  ```

  ```php New SDK - Using setter methods
  $signer1 = new Dropbox\Sign\Model\SubSignatureRequestSigner();
  $signer1->setEmailAddress("jack@example.com")
      ->setName("Jack")
      ->setOrder(0);

  $attachment1 = new Dropbox\Sign\Model\SubAttachment();
  $attachment1->setName("Attachment 1")
      ->setInstructions("Please download this file")
      ->setSignerIndex(0)
      ->setRequired(true);
  ```

  ```php New SDK - Using init() Static Method
  $signer1 = Dropbox\Sign\Model\SubSignatureRequestSigner::init([
      "email_address" => "jack@example.com",
      "name"          => "Jack",
      "order"         => 0,
  ]);

  $attachment1 = Dropbox\Sign\Model\SubAttachment::init([
      "name"         => "Attachment 1",
      "instructions" => "Please download this file",
      "signer_index" => 0,
      "required"     => true,
  ]);
  ```
</CodeBlocks>

<Info title="Note">
  `init()` creates a full object using all the data you pass, including nested data to instantiate nested objects. Any parameters that you do not pass data for will be set to their default value (including `null`).
</Info>

<HR />

### Event Callback Helper

A callback helper class is included in the [New SDK repo](https://github.com/hellosign/dropbox-sign-php/blob/main/src/EventCallbackHelper.php) to assist in verifying callbacks. The helper simplifies:

1. Checking event authenticity with built in event hash check
2. Displaying event types (account callback vs. app callback)
3. Displaying event messages

The `EventCallbackHelper` and `EventCallbackRequest` classes facilitate parsing of event data and assist in validating that a callback originated from Dropbox Sign.

We will send event callback payloads to you as a `multipart/form-data` request with a single `json` formfield that contains your event callback as a JSON string.

**Example Event Callback Request From US to YOU**

```bash
curl -X POST 'https://example.com/YOUR_EVENT_CALLBACK_URL' \
  -F 'json={"event":{"event_type":"account_confirmed","event_time":"1669926463","event_hash":"ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f","event_metadata":{"related_signature_id":null,"reported_for_account_id":"6421d70b9bd45059fa207d03ab8d1b96515b472c","reported_for_app_id":null,"event_message":null}}}'
```

**Example JSON Payload**

```json
{
  "event": {
    "event_type": "account_confirmed",
    "event_time": "1669926463",
    "event_hash": "ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f",
    "event_metadata": {
      "related_signature_id": null,
      "reported_for_account_id": "6421d70b9bd45059fa207d03ab8d1b96515b472c",
      "reported_for_app_id": null,
      "event_message": null
    }
  }
}
```

**How to use the EventCallbackHelper**

```php
<?php

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

// use your API key
$api_key = "324e3b0840f065eb51f3fd63231d0d33daa35d4ed10d27718839e81737065782";

// $callback_data represents data we send to you
$callback_data = json_decode($_POST["json"] ?? [], true);

$callback_event = Dropbox\Sign\Model\EventCallbackRequest::init($callback_data);

// verify that a callback came from HelloSign.com
if (Dropbox\Sign\EventCallbackHelper::isValid($api_key, $callback_event)) {
    // one of "account_callback" or "api_app_callback"
    $callback_type = Dropbox\Sign\EventCallbackHelper::getCallbackType($callback_event);

    // do your magic below!
}
```

<HR />

### HTTP Header Info

All methods include a `WithHttpInfo()` variant. This method ensures HTTP header information and status code will be included in the response received from the API.

<CodeBlocks>
  ```php WithHttpInfo Variant Request
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $data = new Dropbox\Sign\Model\SignatureRequestRemindRequest();
  $data->setEmailAddress("john@example.com");

  $signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";

  try {
      // No HTTP headers included:
      // $result = $signatureRequestApi->signatureRequestGet($signatureRequestId);

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

  ```php WithHttpInfo Variant Response
  [0] => Dropbox\Sign\Model\SignatureRequestGetResponse Object
    (...)
  [1] => 200
  [2] => Array(
    // ...
    [X-Ratelimit-Limit] => Array(
      [0] => 100
    )
    [X-Ratelimit-Limit-Remaining] => Array(
      [0] => 99
    )
    [X-Ratelimit-Reset] => Array(
      [0] => 1667941374
    )
    // ...
  )
  ```
</CodeBlocks>

<Info title="Note">
  You can also get the last [response object](https://www.php-fig.org/psr/psr-7/) that includes body, status code, and headers, using the `::getResponse()` method against an API object: `$response = $signatureRequestApi->getResponse();`
</Info>

<HR />

## Differences from Legacy SDK

This section highlights larger changes to be aware of when migrating to the new SDK.

### Form Fields per Document

The Form Fields per Document parameter has changed from a two dimensional array, to a one dimensional array—allowing you to designate which file you to add the field to using `document_index`. You can learn more about this change here: [Form Fields per Document](/docs/sd-ks/open-api/form-fields-per-document).

<CodeBlocks>
  ```php Legacy SDK - Form Fields Per Document
  $request->setFormFieldsPerDocument(
      [
          [ //document 1
              [ //field 1
                  "api_id"   => $random_prefix . "_1",
                  "name"     => "",
                  "type"     => "text",
                  "x"        => 112,
                  "y"        => 328,
                  "width"    => 100,
                  "height"   => 16,
                  "required" => true,
                  "signer"   => 0
              ],
              [ //field 2
                  "api_id"   => $random_prefix . "_2",
                  "name"     => "",
                  "type"     => "signature",
                  "x"        => 530,
                  "y"        => 415,
                  "width"    => 150,
                  "height"   => 30,
                  "required" => true,
                  "signer"   => 1
              ],
          ],
      ],
  );
  ```

  ```php New SDK - Form Fields per Document
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $data = new Dropbox\Sign\Model\SignatureRequestSendRequest();
  $data->setFormFieldsPerDocument([
      Dropbox\Sign\Model\SubFormFieldsPerDocumentText::init([
          "document_index"  => 0,
          "api_id"          => "134asdf",
          "required"        => true,
          "signer"          => 0,
          "width"           => 100,
          "height"          => 16,
          "x"               => 112,
          "y"               => 700,
          "page"            => 1,
          "placeholder"     => "Full Name",
          "validation_type" => "letters_only"
      ]),
      Dropbox\Sign\Model\SubFormFieldsPerDocumentTextMerge::init([
          "document_index" => 0,
          "api_id"         => "5678yuio",
          "name"           => "Address",
          "required"       => true,
          "signer"         => 0,
          "width"          => 100,
          "height"         => 16,
          "x"              => 222,
          "y"              => 700,
          "page"           => 1,
      ]),
      Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature::init([
          "document_index" => 0,
          "api_id"         => "zxcvuip",
          "required"       => true,
          "signer"         => 1,
          "width"          => 150,
          "height"         => 30,
          "x"              => 400,
          "y"              => 715,
          "page"           => 2,
      ]),
  ]);

  try {
      $result = $signatureRequestApi->signatureRequestSend($data);

      print_r($result);
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```
</CodeBlocks>

#### Instantiating the Correct Field Class

There are several different types of form fields you can define, identified by the value of the `type` field and a few ways to instantiate the correct object when making an API request.

The different classes for each type are:

| Field Type     | Class                                                                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| checkbox       | [SubFormFieldsPerDocumentCheckbox](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentCheckbox.php)           |
| checkbox-merge | [SubFormFieldsPerDocumentCheckboxMerge](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentCheckboxMerge.php) |
| date\_signed   | [SubFormFieldsPerDocumentDateSigned](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentDateSigned.php)       |
| dropdown       | [SubFormFieldsPerDocumentDropdown](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentDropdown.php)           |
| hyperlink      | [SubFormFieldsPerDocumentHyperlink](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentHyperlink.php)         |
| initials       | [SubFormFieldsPerDocumentInitials](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentInitials.php)           |
| radio          | [SubFormFieldsPerDocumentRadio](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentRadio.php)                 |
| signature      | [SubFormFieldsPerDocumentSignature](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentSignature.php)         |
| text           | [SubFormFieldsPerDocumentText](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentText.php)                   |
| text-merge     | [SubFormFieldsPerDocumentTextMerge](https://github.com/hellosign/dropbox-sign-php/blob/main/src/Model/SubFormFieldsPerDocumentTextMerge.php)         |

**You can use `::init()` on the base request class**

```php
# instantiates a new `SignatureRequestSendRequest` object
$data = Dropbox\Sign\Model\SignatureRequestSendRequest::init([
    "title"                    => "NDA with Acme Co.",
    "subject"                  => "The NDA we talked about",
    "message"                  => "Please sign this NDA and then we can discuss more.",
    "signers"                  => [
        [
            "email_address" => "jill@example.com",
            "name" => "Jill",
            "order" => 1,
        ],
    ],
    "files"                    => [new SplFileObject(__DIR__ . "/pdf-sample.pdf")],
    "form_fields_per_document" => [
        [
            "type"           => "signature",
            "document_index" => 0,
            "api_id"         => "4688957689",
            "name"           => "signature1",
            "x"              => 5,
            "y"              => 7,
            "width"          => 60,
            "height"         => 30,
            "required"       => true,
            "signer"         => 0,
            "page"           => 1,
        ],
    ],
]);
```

**You can use `::init()` on the field class**

```php
$form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature::init([
    "document_index" => 0,
    "api_id"         => "4688957689",
    "name"           => "signature1",
    "x"              => 5,
    "y"              => 7,
    "width"          => 60,
    "height"         => 30,
    "required"       => true,
    "signer"         => 0,
    "page"           => 1,
]);
```

**You can instantiate the class directly**

```php
$form_field_1 = new Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature();
$form_field_1->setDocumentIndex(0)
    ->setApiId("4688957689")
    ->setName("signature1")
    ->setX(5)
    ->setY(7)
    ->setWidth(60)
    ->setHeight(30)
    ->setRequired(true)
    ->setSigner(0)
    ->setPage(1);
```

**Form Fields per Document Examples using the new SDK:**

<CodeBlocks>
  ```php Signature
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "signature1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
  ]);
  ```

  ```php Initials
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentInitials::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "initials1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
  ]);
  ```

  ```php Date Signed
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentDateSigned::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "date_signed1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
  ]);
  ```

  ```php Text
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentText::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "text1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
  ]);
  ```

  ```php Text Merge
  $first_name = Dropbox\Sign\Model\SubCustomField::init([
      "name"  => "first_name",
      "value" => "John"
  ]);

  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentTextMerge::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "first_name",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
  ]);
  ```

  ```php Checkbox
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentCheckbox::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "checkbox1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
  ]);
  ```

  ```php Checkbox Merge
  $is_registered = Dropbox\Sign\Model\SubCustomField::init([
      "name"  => "is_registered",
      "value" => "1"
  ]);

  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentCheckboxMerge::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "is_registered",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
  ]);
  ```

  ```php Dropdown
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentDropdown::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "dropdown1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
      "options"        => ["Option 1","Option 2"],
      "content"        => "Option 2",
  ]);
  ```

  ```php Hyperlink
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentHyperlink::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "hyperlink1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => "me_now",
      "page"           => 1,
      "content"        => "Click me!",
      "content_url"    => "http://example.com",
  ]);
  ```

  ```php Radio
  $form_field_1 = Dropbox\Sign\Model\SubFormFieldsPerDocumentRadio::init([
      "document_index" => 0,
      "api_id"         => "4688957689",
      "name"           => "radio1",
      "x"              => 5,
      "y"              => 7,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
      "group"          => "RadioItemGroup1",
      "is_checked"     => true,
  ]);

  $form_field_2 = Dropbox\Sign\Model\SubFormFieldsPerDocumentRadio::init([
      "document_index" => 0,
      "api_id"         => "46876587",
      "name"           => "radio2",
      "x"              => 5,
      "y"              => 50,
      "width"          => 60,
      "height"         => 30,
      "required"       => true,
      "signer"         => 0,
      "page"           => 1,
      "group"          => "RadioItemGroup1",
      "is_checked"     => false,
  ]);

  $form_field_group_1 = Dropbox\Sign\Model\SubFormFieldGroup::init([
      "group_id"    => "RadioItemGroup1",
      "group_label" => "Radio Item Group 1",
      "requirement" => "require_0-1",
  ]);
  ```
</CodeBlocks>

<HR />

### "role" Value in `signers` Object

In the Legacy SDK when making a Signature Request using a Template the `signers` property was an object with the role name as the key. In the new SDK the role value has been moved into the signer object itself.

For example for the [/signature\_request/send\_with\_template](/api/signature-request/send-with-template) endpoint the `signers` property could be represented as:

<CodeBlocks>
  ```json Legacy SDK - signers with Roles
  {
    "signers": {
      "Client": {
        "name": "George",
        "email_address": "george@example.com"
      },
      "Manager": {
        "name": "Bob",
        "email_address": "bob@example.com"
      }
    }
  }
  ```

  ```json New SDK - signers with Roles
  {
    "signers": [
      {
        "role": "Client",
        "name": "George",
        "email_address": "george@example.com"
      },
      {
        "role": "Manager",
        "name": "Bob",
        "email_address": "bob@example.com"
      }
    ]
  }
  ```
</CodeBlocks>

Using the new SDK you would now send this data as follows:

<CodeBlocks>
  ```php New SDK - signers with Roles Example #1
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
  $data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
      ->setSubject("Purchase Order")
      ->setMessage("Glad we could come to an agreement.")
      ->setSigners([
          Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
              "role"          => "Client",
              "name"          => "George",
              "email_address" => "george@example.com",
          ]),
          Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
              "role"          => "Manager",
              "name"          => "Bob",
              "email_address" => "bob@example.com",
          ]),
      ]);

  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());
  }
  ```

  ```php New SDK - signers with Roles Example #2
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer1->setRole("Client")
      ->setEmailAddress("george@example.com")
      ->setName("George");

  $signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer2->setRole("Manager")
      ->setEmailAddress("bob@example.com")
      ->setName("Bob");

  $data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
  $data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
      ->setSubject("Purchase Order")
      ->setMessage("Glad we could come to an agreement.")
      ->setSigners([$signer1, $signer2]);

  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());
  }
  ```
</CodeBlocks>

<HR />

### "role" Value in `ccs` Property

In the Legacy SDK when making a Signature Request using a Template the `ccs` property was an object with the role name as the key. In the new SDK the role value has been moved into the cc object itself, alongside a new `email_address` property.

For example for the [/signature\_request/send\_with\_template](/api/signature-request/send-with-template) endpoint the `ccs` property could be represented as:

<CodeBlocks>
  ```json Legacy SDK - ccs
  {
    "ccs": {
      "Client": "george@example.com",
      "Manager": "bob@example.com"
    }
  }
  ```

  ```json New SDK - ccs
  {
    "ccs": [
      {
        "role": "Client",
        "email_address": "george@example.com"
      },
      {
        "role": "Manager",
        "email_address": "bob@example.com"
      }
    ]
  }
  ```
</CodeBlocks>

Using the new SDK you would now send this data as follows:

<CodeBlocks>
  ```php New SDK - ccs Example #1
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
  $data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
      ->setSubject("Purchase Order")
      ->setMessage("Glad we could come to an agreement.")
      ->setSigners([
          Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
              "role"          => "Client",
              "name"          => "George",
              "email_address" => "george@example.com",
          ]),
          Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
              "role"          => "Manager",
              "name"          => "Bob",
              "email_address" => "bob@example.com",
          ]),
      ])
      ->setCcs([
          Dropbox\Sign\Model\SubCC::init([
              "role"          => "Client",
              "email_address" => "george@example.com",
          ]),
          Dropbox\Sign\Model\SubCC::init([
              "role"          => "Manager",
              "email_address" => "bob@example.com",
          ]),
      ]);

  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());
  }
  ```

  ```php New SDK - ccs Example #2
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer1->setRole("Client")
      ->setEmailAddress("george@example.com")
      ->setName("George");

  $signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer2->setRole("Manager")
      ->setEmailAddress("bob@example.com")
      ->setName("Bob");

  $cc1 = Dropbox\Sign\Model\SubCC::init([
      "role"          => "Client",
      "email_address" => "george@example.com",
  ]);

  $cc2 = Dropbox\Sign\Model\SubCC::init([
      "role"          => "Manager",
      "email_address" => "bob@example.com",
  ]);

  $data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
  $data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
      ->setSubject("Purchase Order")
      ->setMessage("Glad we could come to an agreement.")
      ->setSigners([$signer1, $signer2])
      ->setCCs([$cc1, $cc2]);

  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());
  }
  ```
</CodeBlocks>

<HR />

### "name" Value in `custom_fields` Property

In the Legacy SDK when making a Signature Request with the `custom_fields` property it was an object with the name as the key. In the new SDK the name value has been moved into the custom\_field object itself.

For example for the [/signature\_request/send\_with\_template](/api/signature-request/send-with-template) endpoint the `custom_fields` property could be represented as:

<CodeBlocks>
  ```json Legacy SDK - custom_fields
  {
    "custom_fields": {
      "company": {
        "value": "ABC Corp",
        "required": true
      }
    }
  }
  ```

  ```json New SDK - custom_fields
  {
    "custom_fields": [
      {
        "name": "company",
        "value": "ABC Corp",
        "required": true
      }
    ]
  }
  ```
</CodeBlocks>

Using the new SDK you would now send this data as follows:

<CodeBlocks>
  ```php New SDK - custom_fields Example #1
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
  $data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
      ->setSubject("Purchase Order")
      ->setMessage("Glad we could come to an agreement.")
      ->setSigners([
          Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
              "role"          => "Client",
              "name"          => "George",
              "email_address" => "george@example.com",
          ]),
          Dropbox\Sign\Model\SubSignatureRequestTemplateSigner::init([
              "role"          => "Manager",
              "name"          => "Bob",
              "email_address" => "bob@example.com",
          ]),
      ])
      ->setCustomFields([
          Dropbox\Sign\Model\SubCustomField::init([
              "name"     => "company",
              "value"    => "ABC Corp",
              "required" => 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());
  }
  ```

  ```php New SDK - custom_fields Example #2
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer1->setRole("Client")
      ->setEmailAddress("george@example.com")
      ->setName("George");

  $signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer2->setRole("Manager")
      ->setEmailAddress("bob@example.com")
      ->setName("Bob");


  $custom_field_1 = Dropbox\Sign\Model\SubCustomField::init([
      "name"     => "company",
      "value"    => "ABC Corp",
      "required" => true,
  ]);

  $data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
  $data->setTemplateIds(["c26b8a16784a872da37ea946b9ddec7c1e11dff6"])
      ->setSubject("Purchase Order")
      ->setMessage("Glad we could come to an agreement.")
      ->setSigners([$signer1, $signer2])
      ->setCustomFields([$custom_field_1]);

  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());
  }
  ```
</CodeBlocks>

<HR />

### `template_id` to `template_ids`

The `template_id` parameter has been removed. You must now use `template_ids`.

| Legacy SDK version                                                                                                          | New SDK Version                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Template ID (`template_id`) is passed as a singular string: <br /><br /><pre><code>template\_id : "1234567890"</code></pre> | Template ID is passed as an array of strings (`template_ids`): <br /><br /><pre><code>template\_ids:\["1234567890"]</code></pre> |

<HR />

### `file` to `files`

The `file` parameter has been renamed to `files`. Usage remains the same.

Use `->setFiles([...])`;

<HR />

### `file_url` to `file_urls`

The `file_url` parameter has been renamed to `file_urls`. Usage remains the same.

Use `->setFileUrls([...])`;

<HR />

### Interacting with Files

The new SDK version introduces some new patterns around uploading and downloading files. You can read about them more in depth here: [Interacting with Files](/docs/sd-ks/open-api/interacting-with-files).

#### Uploading Files

The file upload process changed with the newly-adopted OpenAPI-specification — it is no longer possible to pass file paths into file upload methods. You can learn more about this update here: [New Patterns: Interacting with Files](/docs/sd-ks/open-api/interacting-with-files).

| Legacy SDK version                                                   | New SDK Version                                                                                                   |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| A file path was passed into the `addFile()` and `setLogo()` methods. | An `SplFileObject` object must be created and then passed into the `setFiles()` or `setCustomLogoFile()` methods. |

<CodeBlocks>
  ```php Legacy SDK - File Uploads
  // Signature request
  $request->addFile('nda.pdf'); // Adding file from local;

  // API app request
  $request->setLogo('logo_file.png'); // Adding file from local;
  ```

  ```php New SDK - File Uploads
  // Signature request
  ...
  ->setFiles([new SplFileObject(__DIR__ . "/nda.pdf")])
  ...

  // API app request
  ...
  ->setCustomLogoFile(new SplFileObject(__DIR__ . "/logo_file.png"))
  ...
  ```
</CodeBlocks>

<HR />

#### Downloading Files

The file retrieval process changed with the newly-adopted OpenAPI-specification — one endpoint was branched off into three separate endpoints. You can learn more about this update here: [New Patterns: Interacting with Files](/docs/sd-ks/open-api/interacting-with-files).

| Legacy SDK                                                                                                                                                                                                                                                                                                  | New SDK                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A single method (`getFiles()`) would be called to retrieve files. If a local destination path and a file type (PDF or ZIP) were passed into the method, a binary stream would be returned to save locally. If no local destination path nor file type were passed, an auto-generated URL would be returned. | Three separate methods are introduced to retrieve files as either a binary stream, an auto-generated URL or as a `base64` string: <ul><li>`signatureRequestFiles()`</li> <li>`signatureRequestFilesAsFileUrl()`</li> <li>`signatureRequestFilesAsDataUri()`</li></ul> |

<CodeBlocks>
  ```php Legacy SDK - Download Files
  // Binary stream
  $client->getFiles(
      $signature_request_id,
      "{$dest_file_path}/{$title}.zip",
      HelloSign\SignatureRequest::FILE_TYPE_ZIP
  );

  // Auto-generated URL
  $client->getFiles($signature_request_id);
  ```

  ```php New SDK - Download Files
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";
  $fileType = "pdf";

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

  ```php New SDK - Download as Data Uri
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

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

  ```php New SDK - File File Url
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

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

**Downloading Templates**

<CodeBlocks>
  ```php Legacy SDK - Get Template Files
  $client->getTemplateFiles(
      $tenokate_id,
      "{$dest_file_path}/{$title}.zip",
      "pdf"
  );
  ```

  ```php New SDK - Download Template Files
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $templateId = "5de8179668f2033afac48da1868d0093bf133266";
  $fileType = "pdf";

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

  ```php New SDK - Template File as Data Uri
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $templateId = "5de8179668f2033afac48da1868d0093bf133266";

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

  ```php New SDK - Template File as File Url
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $templateId = "5de8179668f2033afac48da1868d0093bf133266";

  try {
      $result = $templateApi->templateFilesAsFileUrl($templateId);
      print_r($result);
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

### Endpoint Classes

| Legacy SDK                                                                   | New SDK                                                                                                                                                                                          |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Requests to the API were made by calling methods within the `Client` object. | Each endpoint group has its own [class](https://github.com/hellosign/dropbox-sign-php/tree/main/docs/Api). Within each class, there are specific methods for calls to every single API endpoint. |

<CodeBlocks>
  ```php Legacy SDK - Endpoint Classes
  $client->createEmbeddedSignatureRequest($embedded_request);

  $client->sendSignatureRequest($request);

  $client->getSignatureRequest($signature_request_id);

  $client->getAccount();

  $client->getTemplate($templateId);
  ```

  ```php New SDK - Endpoint Classes
  $config = Dropbox\Sign\Configuration::getDefaultConfiguration();
  $config->setUsername("YOUR_API_KEY");

  $embeddedSignatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);
  $data = new Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest;
  $embeddedSignatureRequest->signatureRequestCreateEmbedded($data);

  $signatureRequestId = "SIGNATURE_REQUEST_ID";
  $signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);
  $signatureRequest->signatureRequestGet($signatureRequestId);

  $signatureId = "SIGNATURE_ID";
  $embeddedSignUrl = new Dropbox\Sign\Api\EmbeddedApi($config);
  $embeddedSignUrl->embeddedSignUrl($signatureId);

  $templateId = "TEMPLATE_ID";
  $template = new Dropbox\Sign\Api\TemplateApi($config);
  $template->templateGet($templateId);

  $account = new Dropbox\Sign\Api\AccountApi($config);
  $account->accountGet();
  ```
</CodeBlocks>

<HR />

## Endpoint Mapping

This section shows you how endpoints in the legacy SDK map to the new SDK. It doesn't cover all endpoints, but gives you an idea of mapping implementations between the two SDKs. Please [reach out](https://faq.hellosign.com/hc/en-us/requests/new) if you think we're missing an important example.

### Update API App with White Labeling Options

<CodeBlocks>
  ```php Legacy SDK - Update API App
  <?php

  require_once 'vendor/autoload.php';

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

  $clientId = "7deab03c18acf4097fb675f2a566d49f";

  $apiApp = new ApiApp();
  $apiApp->setName('Updating Name')
  ->setWhiteLabeling([
    "primary_button_color" => "#00B3E6",
    "primary_button_text_color" => "#FFFFFF"
  ])
  ->setLogo('my_company_logo.png');

  $response = $client->updateApiApp($clientId, $apiApp);
  print_r($response);
  ```

  ```php New SDK - Update API App
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create an API App object
  $apiApp = new Dropbox\Sign\Api\ApiAppApi($config);

  // Set the client ID of the app that will be getting updated
  $clientId = "6dc20f9a710251b8bb6795ae8bf16";

  // Set or update the custom logo
  $customLogo = new SplFileObject(__DIR__ . "/my_company_logo.png");

  // Create a white labeling object with the new or updated white labeling choices
  $whiteLabelingOptions = new Dropbox\Sign\Model\SubWhiteLabelingOptions();
  $whiteLabelingOptions->setPrimaryButtonColor("#00B3E6")
      ->setPrimaryButtonTextColor("#FFFFFF");

  // Create an API App Update request object with the information for the request
  $data = new Dropbox\Sign\Model\ApiAppUpdateRequest();
  $data->setName("New Name")
      ->setWhiteLabelingOptions($whiteLabelingOptions)
      ->setCustomLogoFile($customLogo);

  try {
      // Send the request to Dropbox Sign
      $result = $apiApp->apiAppUpdate($clientId, $data);
      print_r($result);
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: " . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

### Embedded Signature Request and Get Sign URL

<CodeBlocks>
  ```php Legacy SDK - Embedded Signature Request
  <?php
  require_once 'vendor/autoload.php';

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

  // Create the SignatureRequest object
  $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

  // 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();
  ```

  ```php New SDK - Embedded Signature Request
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create a Signature Request object and an Embedded Object
  $embeddedSignatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);
  $embeddedSignUrl = new Dropbox\Sign\Api\EmbeddedApi($config);

  // Create the signer(s) object(s)
  $signer1 = new Dropbox\Sign\Model\SubSignatureRequestSigner();
  $signer1->setEmailAddress("jack@example.com")
      ->setName("Jack")
      ->setOrder(0);

  $signer2 = new Dropbox\Sign\Model\SubSignatureRequestSigner();
  $signer2->setEmailAddress("jill@example.com")
      ->setName("Jill")
      ->setOrder(1);

  // Create a form fields per document object (optional)
  $signatureField4 = new Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature();
  $signatureField4->setApiId("n0ug4r07")
      ->setHeight(16)
      ->setWidth(100)
      ->setRequired(true)
      ->setSigner(2)
      ->setX(200)
      ->setY(715)
      ->setPage(1)
      ->setDocumentIndex(0);

  // Create an Embedded Signature Request object with the information for the request
  $data = new Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest();
  $data->setClientId("YOUR_CLIENT_ID")
      ->setTitle("NDA with Acme Co.")
      ->setSubject("The NDA we talked about")
      ->setMessage("Please sign this NDA and then we can discuss more. Let me know if you have any questions.")
      ->setSigners([$signer1, $signer2]) // Signer objects
      ->setFileUrls(["https://app.hellosign.com/docs/example_signature_request.pdf"])
      // Adding file from local
      //    ->setFiles([new SplFileObject(__DIR__ . "/Mutual-Non-Disclosure-Agreement.pdf")])
      ->setMetadata(["key1" => "metadata1", "key2" => "metadata2"])
      ->setFormFieldsPerDocument([
          // field 1
          Dropbox\Sign\Model\SubFormFieldsPerDocumentText::init([
              "document_index"  => 0,
              "api_id"          => "4lyx",
              "required"        => true,
              "signer"          => 0,
              "width"           => 100,
              "height"          => 16,
              "x"               => 112,
              "y"               => 700,
              "page"            => 1,
              "placeholder"     => "Full Name",
              "validation_type" => "letters_only"
          ]),
          // field 2
          Dropbox\Sign\Model\SubFormFieldsPerDocumentTextMerge::init([
              "document_index" => 0,
              "api_id"         => "pupp37",
              "name"           => "Address",
              "required"       => true,
              "signer"         => 0,
              "width"          => 100,
              "height"         => 16,
              "x"              => 222,
              "y"              => 700,
              "page"           => 1,
          ]),
          // field 3
          Dropbox\Sign\Model\SubFormFieldsPerDocumentSignature::init([
              "document_index" => 0,
              "api_id"         => "s0n4",
              "required"       => true,
              "signer"         => 1,
              "width"          => 150,
              "height"         => 30,
              "x"              => 400,
              "y"              => 715,
              "page"           => 2,
          ]),
          // field 4
          $signatureField4 // Object created above
      ])
      ->setCustomFields([
          Dropbox\Sign\Model\SubCustomField::init([
              "name"  => "Address",
              "value" => "123 Happy Ln.",
          ])
      ])
      ->setTestMode(true);

  try {
      // Send the request to Dropbox Sign
      $result = $embeddedSignatureRequest->signatureRequestCreateEmbedded($data);

      // Signature information is an array of objects
      foreach ($result->getSignatureRequest()->getSignatures() as $signature) {
          // Retrieve each signers' signature ID
          $signatureId = $signature->getSignatureId();

          // Retrieve each signers' sign_url
          try {
              $embeddedSignUrlResponse = $embeddedSignUrl->embeddedSignUrl($signatureId);

              $signUrl = $embeddedSignUrlResponse->getEmbedded()->getSignUrl();

              print_r("\n{$signUrl}\n");
          } catch (Dropbox\Sign\ApiException $e) {
              $error = $e->getResponseObject();
              echo "Exception when calling Dropbox Sign API: "
                  . print_r($error->getError());
          }
      }
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```

  ```php New SDK - Embed Sig Req using init()
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create a Signature Request object and an Embedded Object
  $embeddedSignature = new Dropbox\Sign\Api\SignatureRequestApi($config);
  $embeddedSignUrl = new Dropbox\Sign\API\EmbeddedApi($config);

  // Create an Embedded Signature Request object with the information for the request
  $data = Dropbox\Sign\Model\SignatureRequestCreateEmbeddedRequest::init([
      "title"     => "NDA with Acme Co.",
      "signers"   => [
          [
              "name"          => "Jack",
              "email_address" => "jack@example.com"
          ],
          [
              "name"          => "Jill",
              "email_address" => "jill@example.com"
          ]
      ],
      "file"      => [
          new SplFileObject(__DIR__ . "/file.pdf")
      ],
      "client_id" => "YOUR_CLIENT_ID"
  ]);

  try {
      // Send the request to Dropbox Sign
      $result = $embeddedSignature->signatureRequestCreateEmbedded($data);

      // Signature information is an array of objects
      foreach ($result->getSignatureRequest()->getSignatures() as $signature) {
          // Retrieve each signers' signature ID
          $signatureId = $signature->getSignatureId();

          // Retrieve each signers' sign_url
          try {
              $embeddedSignUrlResponse = $embeddedSignUrl->embeddedSignUrl($signatureId);

              $signUrl = $embeddedSignUrlResponse->getEmbedded()->getSignUrl();

              print_r("\n{$signUrl}\n");
          } catch (Dropbox\Sign\ApiException $e) {
              $error = $e->getResponseObject();
              echo "Exception when calling Dropbox Sign API: "
                  . print_r($error->getError());
          }
      }
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

### Get Signature Request

<CodeBlocks>
  ```php Legacy SDK - Get Signature Request
  <?php

  require_once 'vendor/autoload.php';

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

  $response = $client->getSignatureRequest($signature_request_id);
  print_r($response);
  ```

  ```php New SDK - Get Signature Request
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create a Signature Request object
  $signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

  $signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

  try {
      $result = $signatureRequest->signatureRequestGet($signatureRequestId);
      // or WithHttpInfo() to include HTTP info in the response:
      // $result = $signatureRequest->signatureRequestGetWithHttpInfo($signatureRequestId);
      print_r($result);
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

### Get Template

<CodeBlocks>
  ```php Legacy SDK - Get Template
  <?php
  require_once 'vendor/autoload.php';

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

  $templateId = '11b77b90f5e7156d961d4bbe26b872ca04edddbb';

  $response = $client->getTemplate($templateId);

  print_r($response);
  print_r($response->getTitle());
  print_r($response->getSignerRoles());
  ```

  ```php New SDK - Get Template
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create a Template object
  $template = new Dropbox\Sign\Api\TemplateApi($config);

  $templateId = "f57db65d3f933b5316d398057a36176831451a35";

  try {
      // Send the request to Dropbox Sign
      $result = $template->templateGet($templateId);

      // Store the template object from the response
      $templateObj = $result->getTemplate();
      // Retrieve the Template's title from the template object
      $templateTitle = $templateObj->getTitle();
      // Retrieve the Template's metadata (if any) from the template object
      $templateMetadata = json_encode($templateObj->getMetadata());
      // Retrieve the signer role(s) from the template object
      $templateSignerRoles = json_encode($templateObj->getSignerRoles());

      print_r("
          Template Title: {$templateTitle}\n
          Template Metadata: {$templateMetadata}\n
          Template Signer Roles: {$templateSignerRoles}\n
      ");
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

### Send Signature Request with Template

<CodeBlocks>
  ```php Legacy SDK - Send Signature Request with Template
  $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);
  ```

  ```php New SDK - Send Signature Request with Template
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

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

  $templateId = "7e29568acd78c947b81afa2876ff07e245b";

  // Create the signer(s) objects
  $signer1 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer1->setRole("Role1")
      ->setEmailAddress("jill@example.com")
      ->setName("Jill");

  $signer2 = new Dropbox\Sign\Model\SubSignatureRequestTemplateSigner();
  $signer2->setRole("Role2")
      ->setEmailAddress("jack@example.com")
      ->setName("Jack");

  // Create a custom_fields object
  $customFields = new Dropbox\Sign\Model\SubCustomField();
  $customFields->setName("Cost")
      ->setValue("$20,000");

  // Create an Signature Request with Template object with the information for the request
  $data = new Dropbox\Sign\Model\SignatureRequestSendWithTemplateRequest();
  $data->setTemplateIds([$templateId])
      ->setTitle("Purchase Order")
      ->setMessage("Glad we could come to an agreement.")
      ->setSigners([$signer1, $signer2])
      ->setCustomFields([
          $customFields
      ])
      ->setTestMode(true);

  try {
      // Send the request to Dropbox Sign
      $result = $signatureRequest->signatureRequestSendWithTemplate($data);
      print_r($result);
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: " . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

### Get Account

<CodeBlocks>
  ```php Legacy SDK - Get Account
  <?php
  require_once 'vendor/autoload.php';

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

  $account = $client->getAccount();

  print_r($account->toArray());
  ```

  ```php New SDK - Get Account
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create an Account object
  $account = new Dropbox\Sign\Api\AccountApi($config);

  try {
      // Send the request to Dropbox Sign
      $result = $account->accountGet();

      // Store the account response object
      $accountObj = $result->getAccount();
      // Retrieve the account ID from the account object
      $accountId = $accountObj->getAccountId();
      // Retrieve the account's email address from the account object
      $accountEmailAddress = $accountObj->getEmailAddress();

      print_r($accountObj);
      print_r("
          Account ID: {$accountId} \n
          Account Email Address: {$accountEmailAddress}
      ");
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

### Download Files

<CodeBlocks>
  ```php Legacy SDK - Download Files
  <?php

  require_once 'vendor/autoload.php';

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

  $signature_request_id = "e541d3d8df85c8e944f0793c8530e915d750";

  // Retrieve the signature request object
  $response = $client->getSignatureRequest($signature_request_id);

  // Set the destination path for the file
  $dest_file_path = 'Signature Request Files';
  // Retrieve the title from the signature request object
  $title = $response->getTitle();

  // Save the file locally
  $client->getFiles(
      $signature_request_id,
      "{$dest_file_path}/{$title}.zip",
      HelloSign\SignatureRequest::FILE_TYPE_ZIP
  );

  // Or

  // Retrieve an auto-generated URL
  $client->getFiles($signature_request_id);
  ```

  ```php New SDK - Binary Stream
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create a Signature Request object
  $signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

  $signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

  try {
      // Create a Signature Request object containing the data for the signature request (optional)
      $sigReqObj = $signatureRequest->signatureRequestGet($signatureRequestId);
      // Save the title for later use to save file (optional)
      $title = $sigReqObj->getSignatureRequest()
          ->getTitle();

      // Send the request to Dropbox Sign
      $result = $signatureRequest->signatureRequestFiles($signatureRequestId);

      // For a ZIP file:
      // $result = $signatureRequest->signatureRequestFiles($signatureRequestId, "zip");

      // Save the file
      copy($result->getRealPath(), __DIR__ . '/file_response.pdf');

      // For a ZIP file:
      // copy($result->getRealPath(), __DIR__ . '/file_response.zip');

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

  ```php New SDK - Auto-generated URL
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create a Signature Request object
  $signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

  $signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

  try {
      // Send the request to Dropbox Sign
      $result = $signatureRequest->signatureRequestFilesAsFileUrl($signatureRequestId);
      print_r($result);
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```

  ```php New SDK - Base64 String
  <?php

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

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

  $config->setUsername("YOUR_API_KEY");

  // Create a Signature Request object
  $signatureRequest = new Dropbox\Sign\Api\SignatureRequestApi($config);

  $signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

  try {
      // Send the request to Dropbox Sign
      $result = $signatureRequest->signatureRequestFilesAsDataUri($signatureRequestId);
      print_r($result);
  } catch (Dropbox\Sign\ApiException $e) {
      $error = $e->getResponseObject();
      echo "Exception when calling Dropbox Sign API: "
          . print_r($error->getError());
  }
  ```
</CodeBlocks>

<HR />

## Supporting Legacy SDKs

<SdkLogistics sdkLanguage="PHP" sdkLegacyVersion="3.8.0" />

<HR />

## Feedback and Assistance

<SdkFeedback sdkLanguage="PHP" />