Skip to content

Commit

Permalink
Merge pull request #73 from docusign/PHP-Readme-Update
Browse files Browse the repository at this point in the history 
Php readme update
  • Loading branch information
@mmallis87
mmallis87 authored May 8, 2019
2 parents 92aaa41 + d382ba3 commit 37f26be
Showing 1 changed file with 71 additions and 177 deletions.
248 changes: 71 additions & 177 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,183 +2,77 @@

[![Build status][travis-image]][travis-url]

You can sign up for a free [developer sandbox](https://go.docusign.com/sandbox/productshot/?elqCampaignId=16532).

Requirements
============

PHP 5.4+ or higher [http://www.php.net/].

Installation
============

### Composer

You can install the bindings via Composer. Run the following command:

composer require docusign/esign-client

To use the bindings, use Composer's autoload:

require_once('vendor/autoload.php');

### Manual Install

If you do not wish to use Composer, you can download the latest release. Then, to use the bindings, include the init.php file.

require_once('/path/to/docusign-esign-client/autoload.php');

#### Dependencies

This client has the following external dependencies:

* PHP Curl extension [http://www.php.net/manual/en/intro.curl.php]
* PHP JSON extension [http://php.net/manual/en/book.json.php]

Usage
=====

To login and send a signature request from a template:

```php
<?php

require_once('docusign-php-client/autoload.php');

class DocuSignSample
{
public function signatureRequestFromTemplate()
{
$username = "[EMAIL]";
$password = "[PASSWORD]";
$integrator_key = "[INTEGRATOR_KEY]";

// change to production (www.docusign.net) before going live
$host = "https://demo.docusign.net/restapi";

// create configuration object and configure custom auth header
$config = new DocuSign\eSign\Configuration();
$config->setHost($host);
$config->addDefaultHeader("X-DocuSign-Authentication", "{\"Username\":\"" . $username . "\",\"Password\":\"" . $password . "\",\"IntegratorKey\":\"" . $integrator_key . "\"}");

// instantiate a new docusign api client
$apiClient = new DocuSign\eSign\ApiClient($config);
$accountId = null;

try
{
//*** STEP 1 - Login API: get first Account ID and baseURL
$authenticationApi = new DocuSign\eSign\Api\AuthenticationApi($apiClient);
$options = new \DocuSign\eSign\Api\AuthenticationApi\LoginOptions();
$loginInformation = $authenticationApi->login($options);
if(isset($loginInformation) && count($loginInformation) > 0)
{
$loginAccount = $loginInformation->getLoginAccounts()[0];
$host = $loginAccount->getBaseUrl();
$host = explode("/v2",$host);
$host = $host[0];

// UPDATE configuration object
$config->setHost($host);

// instantiate a NEW docusign api client (that has the correct baseUrl/host)
$apiClient = new DocuSign\eSign\ApiClient($config);

if(isset($loginInformation))
{
$accountId = $loginAccount->getAccountId();
if(!empty($accountId))
{
//*** STEP 2 - Signature Request from a Template
// create envelope call is available in the EnvelopesApi
$envelopeApi = new DocuSign\eSign\Api\EnvelopesApi($apiClient);
// assign recipient to template role by setting name, email, and role name. Note that the
// template role name must match the placeholder role name saved in your account template.
$templateRole = new DocuSign\eSign\Model\TemplateRole();
$templateRole->setEmail("[SIGNER_EMAIL]");
$templateRole->setName("[SIGNER_NAME]");
$templateRole->setRoleName("[ROLE_NAME]");

// instantiate a new envelope object and configure settings
$envelop_definition = new DocuSign\eSign\Model\EnvelopeDefinition();
$envelop_definition->setEmailSubject("[DocuSign PHP SDK] - Signature Request Sample");
$envelop_definition->setTemplateId("[TEMPLATE_ID]");
$envelop_definition->setTemplateRoles(array($templateRole));

// set envelope status to "sent" to immediately send the signature request
$envelop_definition->setStatus("sent");

// optional envelope parameters
$options = new \DocuSign\eSign\Api\EnvelopesApi\CreateEnvelopeOptions();
$options->setCdseMode(null);
$options->setMergeRolesOnDraft(null);

// create and send the envelope (aka signature request)
$envelop_summary = $envelopeApi->createEnvelope($accountId, $envelop_definition, $options);
if(!empty($envelop_summary))
{
echo "$envelop_summary";
}
}
}
}
}
catch (DocuSign\eSign\ApiException $ex)
{
echo "Exception: " . $ex->getMessage() . "\n";
}
}
}

?>
```

See [UnitTests.php](https://github.com/docusign/docusign-php-client/blob/master/test/UnitTests.php) for more examples.

# Authentication

## Service Integrations that use Legacy Header Authentication

([Legacy Header Authentication](https://docs.docusign.com/esign/guide/authentication/legacy_auth.html) uses the X-DocuSign-Authentication header.)

1. Use the [Authentication: login method](https://docs.docusign.com/esign/restapi/Authentication/Authentication/login/) to retrieve the account number **and the baseUrl** for the account.
The url for the login method is www.docusign.net for production and demo.docusign.net for the developer sandbox.
The `baseUrl` field is part of the `loginAccount` object. See the [docs and the loginAccount object](https://docs.docusign.com/esign/restapi/Authentication/Authentication/login/#/definitions/loginAccount)
2. The baseUrl for the selected account, in production, will start with na1, na2, na3, eu1, or something else. Use the baseUrl that is returned to create the *basePath* (see the next step.) Use the basePath for all of your subsequent API calls.
3. As returned by login method, the baseUrl includes the API version and account id. Split the string to obtain the *basePath*, just the server name and api name. Eg, you will receive `https://na1.docusign.net/restapi/v2/accounts/123123123`. You want just `https://na1.docusign.net/restapi`
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
5. Set the authentication header as shown in the examples by using `Configuration.Default.AddDefaultHeader`

## User Applications that use OAuth Authentication
1. After obtaining a Bearer token, call the [OAuth: Userinfo method](https://docs.docusign.com/esign/guide/authentication/userinfo.html). Obtain the selected account's `base_uri` (server name) field.
The url for the Userinfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environment.
1. Combine the base_uri with "/restapi" to create the basePath. The base_uri will start with na1, na2, na3, eu1, or something else. Use the basePath for your subsequent API calls.
4. Instantiate the SDK using the basePath. Eg `ApiClient apiClient = new ApiClient(basePath);`
5. Create the `authentication_value` by combining the `token_type` and `access_token` fields you receive from either an [Authorization Code Grant](https://docs.docusign.com/esign/guide/authentication/oa2_auth_code.html) or [Implicit Grant](https://docs.docusign.com/esign/guide/authentication/oa2_implicit.html) OAuth flow.
5. Set the authentication header by using `Configuration.Default.AddDefaultHeader('Authorization', authentication_value)`

Testing
=======

Unit tests are available in the [test](/test) folder.

Follow the steps below to run the test cases

* Rename the "TestConfig.php-sample" to "TestConfig.php"
* Populate all the required values like the login credentials, integrator key, host, etc in TestConfig.php
* Run the following command from the [test](/test) folder

phpunit.phar UnitTests.php

Support
=======

Feel free to log issues against this client through GitHub. We also have an active developer community on Stack Overflow, search the [DocuSignAPI](http://stackoverflow.com/questions/tagged/docusignapi) tag.

License
=======

The DocuSign PHP Client is licensed under the following [License](LICENSE).
## Requirements

- PHP 5.4+
- Free [Developer Sandbox](https://go.docusign.com/sandbox/productshot/?elqCampaignId=16531)

## Compatibility

- PHP 5.4+

## Note

This open-source SDK is provided for cases where you would like to make additional changes that the SDK does not provide out-of-the-box. If you simply want to use the SDK with any of the examples shown in the [Developer Center](https://developers.docusign.com/esign-rest-api/code-examples), follow the installation instructions below.

## Installation

### Composer:

1. In your **PHP console** , type:
**Composer require docusign/esign-client;**
2. To use the package automatically, add to Composer's **Autoload** file:
**require_once('vendor/autoload.php');**

### Manual install:

<ol>
<li>Download or clone this repository.</li>
<li>Bind the PHP SDK to your server or place it in a static location.
<ol style="list-style-type: lower-alpha simple">
<li>To bind to your server, edit the <em>init.php</em> file. Add:<br>
<code>require_once('/path/to/docusign-esign-client/autoload.php');</code></li>
<li>To bind to single pages: In your PHP file that will utilize the PHP SDK, add:<br>
<code>`require_once('/path/to/docusign-esign-client/autoload.php');</code></li>
</ol>
</li>
</ol>

## Dependencies

This client has the following external dependencies:

- [PHP cURL extension](https://www.php.net/manual/en/intro.curl.php)
- [PHP JSON extension](https://php.net/manual/en/book.json.php)

## Code Examples

### Launchers

DocuSign provides a sample application referred to as a [Launcher](https://github.com/docusign/eg-03-php-auth-code-grant). The Launcher contains a set of 18 common use cases and associated source files. These examples use DocuSign's [Authorization Code Grant](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-code-grant) flow.

## Proof-of-concept applications

If your goal is to create a proof-of-concept application, DocuSign provides a set of [Quick Start](https://github.com/docusign/qs-php) examples. The Quick Startexamples are meant to be used with DocuSign's [OAuth Token Generator](https://developers.docusign.com/oauth-token-generator), which will allow you to generate tokens for the Demo/Sandbox environment only. These tokens last for eight hours and will enable you to build your proof-of-concept application without the need to fully implement an OAuth solution.

## OAuth Implementations

For details regarding which type of OAuth grant will work best for your DocuSign integration, see the [REST API Authentication Overview](https://developers.docusign.com/esign-rest-api/guides/authentication) guide located on the [DocuSign Developer Center](https://developers.docusign.com/esign-rest-api/guides/authentication).

For security purposes, DocuSign recommends using the [Authorization Code Grant](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-code-grant) flow.

There are other use-case scenarios, such as **single-page applications** (SPA) that use **Cross-Origin Resource Sharing** (CORS), or where there may not be a user to interact with your Service Account. For these use cases, DocuSign also supports [JWT](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-jsonwebtoken) and [Implicit](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-implicit) grants. For code examples, see the links below:

- [JWT (JSON Web Token)](https://github.com/docusign/eg-03-php-auth-code-grant)
- Implicit Grant (coming soon)

## Support

Log issues against this client through GitHub. We also have an [active developer community on Stack Overflow](https://stackoverflow.com/questions/tagged/docusignapi).

## License

The DocuSign PHP Client is licensed under the [MIT License](https://github.com/docusign/docusign-php-client/blob/master/LICENSE).

[travis-image]: https://img.shields.io/travis/docusign/docusign-php-client.svg?style=flat
[travis-url]: https://travis-ci.org/docusign/docusign-php-client

0 comments on commit 37f26be

Please sign in to comment.