PHPackages                             penneo/penneo-sdk-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. penneo/penneo-sdk-php

ActiveLibrary[API Development](/categories/api)

penneo/penneo-sdk-php
=====================

Penneo SDK for PHP

v3.0.0(1y ago)399.4k↓17.5%9[7 issues](https://github.com/Penneo/sdk-php/issues)[3 PRs](https://github.com/Penneo/sdk-php/pulls)1Apache-2.0PHPPHP ^7.2|^8.0CI passing

Since Feb 12Pushed 1y ago15 watchersCompare

[ Source](https://github.com/Penneo/sdk-php)[ Packagist](https://packagist.org/packages/penneo/penneo-sdk-php)[ Docs](https://penneo.com)[ RSS](/packages/penneo-penneo-sdk-php/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (59)Used By (1)

Penneo SDK for PHP
==================

[](#penneo-sdk-for-php)

Penneo is all about digitizing the process of signing documents and contacts. The Penneo SDK for PHP enables PHP developers to use digital signing of documents in their PHP code. Get more info at [penneo.com](https://penneo.com/)about how to become a customer.

Prerequisites
-------------

[](#prerequisites)

The Penneo SDK for PHP requires that you are using PHP 5.3 or newer. Also you must have a recent version of cURL >= 7.16.2 compiled with OpenSSL and zlib.

Getting Started
---------------

[](#getting-started)

You can install the SDK by simply cloning or downloading the source, or you can use Composer. We recommend that you use Composer:

### Installing via Composer

[](#installing-via-composer)

The recommended way to install the Penneo SDK is through [Composer](http://getcomposer.org).

```
# Install Composer
curl -sS https://getcomposer.org/installer | php
```

Next, update your project's composer.json file to include the SDK:

```
{
    "require": {
        "penneo/penneo-sdk-php": "2.*"
    }
}
```

After installing, you need to require Composer's autoloader before calling any SDK functions e.g.:

```

```

You can find out more on how to install Composer, configure autoloading, and other best-practices for defining dependencies at [getcomposer.org](http://getcomposer.org).

Documentation
-------------

[](#documentation)

This section documents the different objects available through the SDK and how to use them.

### Authentication

[](#authentication)

The SDK supports three different methods of authentication:

- Interactive authentication using **OAuth 2.0**: This is the recommended method of authentication. It is more secure and allows you to perform operations on behalf of your users.
- Programmatic authentication using **OAuth 2.0**: The recommended method of authentication for integrations without user interaction.
- Programmatic authentication using **WSSE**: This is a legacy method of authentication. While it is supported, we encourage the use of OAuth instead of WSSE.

#### OAuth 2.0

[](#oauth-20)

Read more about OAuth 2.0 [here](https://oauth.net/2/).

##### OAuth client

[](#oauth-client)

You will need an OAuth client to be used by your integration to perform the OAuth 2.0 authentication flow.

To create such a client please open a ticket in our [Support Center](https://penneo.my.site.com/support/s/contactsupport?language=en_US) asking for the creation of an integration client. Please specify in the request the name of the client and the redirect\_uri towards which you will receive the callback requests.

We will provide you with a `client_id` and `client_secret`.

##### Programmatic authentication using OAuth

[](#programmatic-authentication-using-oauth)

To set up programmatic access, you'll need to initialize the API connector with oauth, by building it using your `client_id`, `client_secret` and your chosen `redirect_uri`, alongside the API key and secret.

```
$oAuth = Penneo\SDK\OAuth\OAuthBuilder::start()
    ->setEnvironment('environmentHere')
    ->setClientId('clientIdHere')
    ->setClientSecret('clientSecretHere')
    ->setTokenStorage(new SessionTokenStorage())
    ->setApiKey('apiKeyHere')
    ->setApiSecret('apiSecretHere')
    ->build();

Penneo\SDK\ApiConnector::initializeOAuth($oAuth);
```

> 👉 see a full, functional example in [docs/programmatic\_oauth\_example.php](docs/programmatic_oauth_example.php).

Then you can start making API requests.

##### Interactive authentication using OAuth

[](#interactive-authentication-using-oauth)

To initiate interactive authentication, you will first need to build the authorization URI using your `client_id`, `client_secret` and your chosen `redirect_uri`, then redirect the user to the `$authorizationUrl`:

```
// Build the OAuth instance
$oAuth = Penneo\SDK\OAuth\OAuthBuilder::start()
    ->setEnvironment('environmentHere')
    ->setClientId('clientIdHere')
    ->setClientSecret('clientSecretHere')
    ->setRedirectUri('redirectUriHere')
    ->setTokenStorage(new SessionTokenStorage())
    ->build();

// Generate code verfier and a code challenge
$pkce = new Penneo\SDK\OAuth\PKCE\PKCE();
// Code verifier should be stored (e.g. in user session) as it will be required later for the authorization code exchange
$codeVerifier = $pkce->getCodeVerifier();
$codeChallenge = $pkce->getCodeChallenge($codeVerifier);

// Build authorization request URL
$authorizationUrl = $oAuth->buildRedirectUrl($scope, $codeChallenge)

// Redirect currently logged in user to the $authorizationUrl (Penneo Auth Service)
```

The environment can either be `sandbox` for testing, or `production` for the live system.

Following the standard OAuth 2.0 flow, the user is brought to the authorization page where they can log in into Penneo with their chosen method (e.g. username and password, Google, Microsoft, etc.) and authorize your application to access their Penneo account.

The user is then redirected back to the `redirect_uri` with a single-use authorization code.

##### Exchanging authorization code with access token

[](#exchanging-authorization-code-with-access-token)

Now you have a single-use `authorization code` and a `code verifier` that you can use to exchange them for an `access_token` which will be stored in the token storage defined previously in the `OAuthBuilder`:

```
// Exchage received authorization code with the access token
$oAuth->exchangeAuthCode($authCode, $codeVerifier);
```

When the authorization code is successfully exchanged with a new `token`, you can then initialize the OAuth 2.0 connector using the already authorized `$oAuth` instance:

```
// Initialize the connection to the API as customer
Penneo\SDK\ApiConnector::initializeOAuth($oAuth);
```

> 👉 see a full, functional example in [docs/interactive\_oauth\_example.php](docs/interactive_oauth_example.php).

##### OAuth Token Storage

[](#oauth-token-storage)

The SDK will store the OAuth 2.0 token in the session using the `SessionTokenStorage` by default. If you want to use another storage, you can implement your own by using the `TokenStorage` interface.

#### WSSE

[](#wsse)

The Web Services Security (WSSE) authentication is done in a single line of code, using your Penneo API credentials:

```
// Initialize the connection to the API
Penneo\SDK\ApiConnector::initializeWsse('apiKeyHere', 'apiSecretHere', $endpoint);
```

If you have a reseller account, you can carry out operations on behalf of one of your customers, by specifying the customer id as well:

```
// Initialize the connection to the API as customer
Penneo\SDK\ApiConnector::initializeWsse('apiKeyHere','apiSecretHere', $endpoint, $customerId);
```

The endpoint URL can point to either the sandbox (for testing) or the live system. Both endpoint URLs are available on request.

### Problems in production?

[](#problems-in-production)

You should add a logger by calling `ApiConnector::setLogger()`. If you contact support, please include any relevant `requestIds` you find in the logs.

### Document signing

[](#document-signing)

- [Folders](docs/folder.md)Folder objects are containers for case file objects.
- [Case files](docs/casefile.md)The case file object is a container used to bundle documents and signers. Every signing process starts with a case file.
- [Documents](docs/document.md)The document object represents (and contains) the actual PDF document.
- [Signature lines](docs/signature-line.md)Every signable document must have at least one signature line. Think of it as the dashed line that people used to sign using a pen.
- [Signers](docs/signer.md)A signer object represents the person that signs.
- [SigningRequests](docs/signing-request.md)Think of the signing request as being the instructions for the signer on what to sign. It can either be the formal letter accompanying the document, the yellow post-its showing where to sign, or both.
- [Case file templates](docs/templates.md)Instead of specifying the mapping between documents and signers explicitly, it is possible to use one of the many pre-defined case file templates provided by Penneo.

### Identity validation

[](#identity-validation)

- [Validations](docs/validation.md)Money laundering regulations require companies to validate the identity of their clients. The validation object can accomplish this, using only a social security number and an electronic ID.

Quick Examples
--------------

[](#quick-examples)

### Signing a document (simple)

[](#signing-a-document-simple)

In this example, we show how to create a document with a single signer. The link to the Penneo signing portal, where the actual signing takes place, is printed as a result.

```