double-opt-in / php-client-api
This is the official client api for the Double-Opt-in service.
This package's canonical repository appears to be gone and the package has been frozen as a result.
Installs: 4 181
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 3
Open Issues: 0
Requires
- php: >=5.3.0
- lib-curl: *
- commerceguys/guzzle-oauth2-plugin: ~1.0
- guzzlehttp/guzzle: ~6.0
Requires (Dev)
README
The PHP client api for Double Opt-in lets you integrate the double-opt.in service to your application by using its api. The api is an OAuth 2.0 REST api. You need an account at double-opt.in and a site to log the data to. All user-related data will be hashed or crypted before sending to the server api. So all hashing and encrypting will be done on your client side. We have NO plain text data from your users or customers. (Except the name of the optional scope right now.)
Installation
Add to your composer.json following lines
"require": {
"double-opt-in/php-client-api": "~1.6"
}
Usage
For a running example you can take a look at the double-opt-in/cli-client-php package.
In general you will need the client for communication and a command for sending your business command.
The communication client
$clientId = 'YOUR_CLIENT_ID';
$clientSecret = 'YOUR_CLIENT_SECRET';
$siteToken = 'YOUR_SITE_TOKEN';
// this is only one way to get a configuration instance
$config = new DoubleOptIn\ClientApi\Config\ClientConfig($clientId, $clientSecret, $siteToken);
// bypass ssl verification with the following setting
// $config->setHttpClientConfig(['verify' => false]);
// this is your api client which handles all requests and responses to the api server
$api = new DoubleOptIn\ClientApi\Client\Api($config);
You can also store the configuration values in a file.
Alternative ways to configure the client
Hint: For the http_client
configuration values please look to the guzzle configuration values. We use the guzzle http
client internal.
1. Use a file
For using a configuration file you have to use the ConfigFactory:
$config = \DoubleOptIn\ClientApi\Config\ConfigFactory::fromFile(__DIR__.'/config.php');
$client = new DoubleOptIn\ClientApi\Client\Api($config);
The file has to have the following content:
<?php // config.php
return array(
'api' => 'https://www.double-opt.in/api', // optional
'client_id' => 'YOUR_CLIENT_ID',
'client_secret' => 'YOUR_CLIENT_SECRET',
'site_token' => 'YOUR_SITE_TOKEN',
// optional cache file, recommended for better performance
'cache_file' => 'path/to/writable/cachedir',
// optional http client configuration values
'http_client' => array(
'verify' => false,
),
);
2. Use an array
For using array configuration you have to use the ConfigFactory as well:
$config = \DoubleOptIn\ClientApi\Config\ConfigFactory::fromArray($configArray);
$client = new DoubleOptIn\ClientApi\Client\Api($config);
You need the following structure for your array:
$configArray = array(
'api' => 'https://www.double-opt.in/api', // optional
'client_id' => 'YOUR_CLIENT_ID',
'client_secret' => 'YOUR_CLIENT_SECRET',
'site_token' => 'YOUR_SITE_TOKEN',
// optional cache file, recommended for better performance
'cache_file' => 'path/to/writable/cachedir',
// optional http client configuration values
'http_client' => array(
'verify' => false,
),
);
3. Instantiate a ClientConfig object
You can also set a configuration instance manually:
$config = new DoubleOptIn\ClientApi\Config\ClientConfig($clientId, $clientSecret, $siteToken, $apiUrl, $httpClientConfig);
$client = new DoubleOptIn\ClientApi\Client\Api($config);
That's it.
Cache File option
The ClientConfig object has the ability to cache an bearer token for its lifetime. It is recommended for better performance. The given cache file will be automatically appended with site token and client id to get a unique cache for a concrete connection.
Using the cache for the requested OAuth Access Token means the next request does not need any extra request for fetching an access token again. Each next request uses the fetched access token again.
Manually setting can be done by doing this:
$config = new DoubleOptIn\ClientApi\Config\ClientConfig($clientId, $clientSecret, $siteToken, $apiUrl, $httpClientConfig);
$config->setAccessTokenCacheFile('path/to/writable/cachedir/or-file-prefix');
$client = new DoubleOptIn\ClientApi\Client\Api($config);
Or use the config option as array with special key cache_file
.
The commands
Basically we can log an action for email, retrieve all actions for email and validate an email. For every single task we have a concrete command. For administrative information you can request the current status too.
ActionsCommand
The ActionsCommand retrieves all actions stored for an email.
$email = 'email-to@look.at';
$actionsCommand = new DoubleOptIn\ClientApi\Client\Commands\ActionsCommand($email[, $action[, $scope]]);
Sending the command and retrieving the actions:
$response = $client->send($actionsCommand);
The response has a data
part and a meta
part. You can access them like so:
$data = $response->data();
$meta = $response->meta();
$actions = $response->all();
Data has an array of entries with the actions content. You have an example at CommandResponse::all().
Meta has a pagination object for going to the next result pages.
LogCommand
The LogCommand will be used to log an action for an email.
ATTENTION: We never store user-related data by this api! We hash and encrypt data before we send it.
$email = 'email-to@log.now';
$action = 'register';
$logCommand = new DoubleOptIn\ClientApi\Client\Commands\LogCommand($email, $action[, $scope]);
Optional you can force the necessary attributes ip
, useragent
and created_at
by using this methods:
$logCommand->setIp('127.0.0.1');
$logCommand->setUseragent('My own useragent/1.0');
$logCommand->setCreatedAt('2014-12-13 12:34:56');// or use a \DateTime instance
Sending the command to the api service:
$response = $client->send($logCommand);
$action = $response->action();
You can set almost every word or action name you want. There are special names set to the site as actions workflow.
These actions control the state of an user. This is the action state you have to validate before sending him an email.
These actions are register -> confirm -> blacklist
by default. So if your user is blacklisted, you are not able to
send him an email newsletter for example. Only when a user is confirmed you can mail him with marketing information.
So the legal agreement.
As a result you get the entry created right now.
ValidateCommand
The ValidateCommand is for validating a user before sending him an email.
$email = 'email-to@validate.at';
$validateCommand = new DoubleOptIn\ClientApi\Client\Commands\ValidateCommand($email[, $scope]);
You can validate an email globally or for a defined scope. But with hashed and encrypted data, we can only return data, which is in our database. So if you have logged an email with action and scope, you only can validate by adding the optional second argument scope.
Sending the command to the api service:
$response = $client->send($validateCommand);
$action = $response->action();
In $action
is the most-recent action from the actions workflow. So not the most-recent action at all, only the action
from the workflow. By default one of the register
, confirm
or blacklist
.
Be careful of adding (logging) the right action (with or without scope) for an user.
StatusCommand
The StatusCommand is for retrieving some status information.
$statusCommand = new DoubleOptIn\ClientApi\Client\Commands\StatusCommand();
Sending the command to the api service:
$response = $client->send($sendCommand);
$status = $response->status();
In $status
is an instance of the Status model (DoubleOptIn\ClientApi\Client\Commands\Responses\Models\Status). Here
you can access the following information:
- site name
- site type
- storage time in seconds for the stored data (time after last touch)
- credits left
- soft quota limit
- hard quota limit
- daily credits usage (approximation)
- unique mail hashes or identities