Kaizen #17 - PHP SDK

Hello everyone!

Welcome to yet another post in the Kaizen series.

This week, we are going to discuss the PHP SDK.

PHP Software Development Kit

PHP SDK allows you to create client PHP applications that can be integrated with Zoho CRM effortlessly. It serves as a wrapper for the REST APIs, thus making it easier to use the services of Zoho CRM.

Here is a sample of how the PHP SDK acts as a middleware between Zoho CRM and Client PHP Application.

What can you do with the PHP SDK?

You can use the PHP SDK to exchange data between Zoho CRM and the client PHP application.
Authenticate your application easily every time you sync data between Zoho CRM and the client PHP application, as the SDK takes care of generating the access/refresh tokens automatically.

Installing the PHP SDK

You can install the PHP SDK for Zoho CRM through the Composer—a dependency manager for PHP applications.

The pre-requisites for the client PHP application, before you start using the PHP SDK are:

The client app must have PHP 5.6 or above with a curl extension.
The client app must have the PHP SDK installed through Composer.
The ZCRMRestClient::initialize($configuration) function must be called once while starting the client app. It contains the configuration details as key-value pairs.

PHP SDK and the PHP client application

Include the following line to your client application (wherever you intend to use the PHP SDK) to access all the functionalities of the PHP SDK.

require ‘vendor/autoload.php’
Include the namespaces of the class in the "use" statement. For instance, if you use the ZCRMRestclient class, you must add the following.

use zcrmsdk\crm\setup\restclient\ZCRMRestClient;

How to start using the PHP SDK?

Step-1: Prerequisite: Register your application
Step-2: Install the PHP SDK
Step-3: Authenticate the client application
Step-4: Knowledge Base: Token Persistence
Step-5: Initialization

Step-1: Prerequisite: Register your application

All the Zoho CRM APIs are authenticated by the OAuth2.0 standards. It is mandatory to authenticate the client application with Zoho.

1. Goto https://api-console.zoho.com

2. Click ADD CLIENT.

3. Choose a client type. For instance, Self Client.

4. Choose the Client Type, and click CREATE.

In the case of a web-based client, you need to specify the Client Name, Homepage URL and redirect URIs.

5. Once you successfully register your self-client, you will receive a Client ID and Client Secret.

Step-2: Install the PHP SDK

Installing Composer

As discussed earlier, you can install the PHP SDK through the Composer. To install the composer:

Operating System	Procedure
Mac/Linux	Run the following command in your terminal: curl -sS https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx
Windows	Click here to download the .exe file and install composer.

Installing the PHP SDK through the Composer

Navigate to the workspace of your client app.
Run the following command in the workspace of your client app.

composer require zohocrm/php-sdk
Once you run this command, the system installs the PHP SDK and creates a package named vendor in the workspace of your client app.

Step-3: Authenticate the client application

You must authenticate the client PHP application before it can use the PHP SDK. To authenticate the client PHP application, pass the configuration associative array to the initialization process.

Create $configuration associative array. It must contain the authentication credentials required.
The configuration associative array must then be passed using the ZCRMRestClient::initialize($configuration); function.

Configuration associative array

You must add the configuration values to the PHP associative array (key-value pair) and pass it as an argument to the ZCRMRestclient::initialize($configuration); function. Below is the list of keys that are to be in the associative array.

Key	Description
client_id, client_secret mandatory	You can get these details after registering your client.
redirect_uri mandatory for a web based client	The redirect URI of your web-based PHP client application.
currentUserEmail mandatory	It is the email ID of the current user. You can set it in two ways: a. Through the currentUserEmail key in the configuration associative array (or) b. Through the ZCRMRestClient::setCurrentUserEmailId({user_email_id}) line in the code.
fileUploadUrl Mandatory when using the Bulk Write API	The value for this key must be https://content.zohoapis.com.
applicationLogFilePath optional	The SDK automatically creates a file to store the log information. The absolute file path of the folder in which the system must create the log file must be specified. The default file name is the ZCRMClientLibrary.log. If not specified, the system creates the file inside the project.
sandbox optional	Represents whether to make API calls from the sandbox account. true: Make the API calls from the sandbox account. false: Do not make the API calls from the sandbox account. This is the default value.
apiBaseUrl optional	Represents the URL to make API calls. It denotes the domain of the user. The possible values are: www.zohoapis.com (default) www.zohoapis.eu www.zohoapis.com.cn
apiVersion optional	Represents the API version. Specify the value as v2 (default).
access_type optional	Specify the value as offline. There is no support for Online OAuth client in PHP SDK as of now.
accounts_url optional	The accounts URL. Possible values are: https://accounts.zoho.com (default) https://accounts.zoho.eu https://accounts.zoho.com.cn https://accounts.zoho.in
persistence_handler_class optional	The implementation of ZohoOAuthPersistenceInterface
token_persistence_path optional	The absolute path to the folder that contains zcrm_oauthtokens.txt file. This key is mandatory if you want to use file persistence. If you include this key, this method takes precedence over other persistence methods.
persistence_handler_class_name optional	The name of the custom class for persistence. This key is available only in PHP SDK 2.0.7 and above versions.
db_port optional	You can specify this key if you want to use DB persistence. The default value is 3306.
db_username, db_password optional	Specify the username and password of your database. The default value for db_username is root.
host_address optional	The address of the machine in which the MySQL server is running. The default value is 'localhost'. This key is available only in PHP SDK 2.0.7 and above versions.

Sample containing the mandatory keys alone:

$configuration=array("client_id"=>"1000.xxxxxxxxxxx"","client_secret"=>"831bxxxxxxxxxxxx","redirect_uri"=>"","currentUserEmail"=>"patricia@zylker.com");

ZCRMRestClient::initialize($configuration);

Sample containing all the keys:

$configuration=array("client_id"=>"1000.xxxxxxxxxxx",

"client_secret"=>"831bxxxxxxxxxxxx",

"redirect_uri"=>"redirect_uri",

"currentUserEmail"=>"patricia@zylker.com",

"applicationLogFilePath"=>"absolute/path/to/folder",

"sandbox"=>"false","apiBaseUrl"=>"www.zohoapis.com",

"apiVersion"=>"v2","access_type"=>"offline",

"accounts_url"=>"https://accounts.zoho.com",

"persistence_handler_class"=>"absolute/file/path/to/persistence/implementation",

"token_persistence_path"=>"absolute/path/to/folder/zcrm_oauthtokens.txt", //should not contain "zcrm_oauthtokens.txt"

"persistence_handler_class_name"=>"Persistence_class_name",

"fileUploadUrl"=>"https://content.zohoapis.com");

ZCRMRestClient::initialize($configuration);

Step-4: Token Persistence

Your application should retain tokens (grant, access, refresh tokens) to automate the process of data-sync between your PHP application and Zoho CRM.

You can persist tokens in your application in three ways:

a. Using a Database
b. Using a File
c. Custom Persistence

a. Using a Database

If you prefer using database persistence, you can use the MySQL.

Prerequisites while using the database persistence

The name of the database must be zohooauth.
There must be a table oauthtokens with columns
a. useridentifier (varchar(100))
accesstoken (varchar(100))
refreshtoken (varchar(100))
expirytime (bigint)

b. Using a File

This type of persistence uses a file to read and write OAuth tokens. The file persists the token of a single user. So, it is best used for the 'self-client' type of authentication since it involves only one user. If you prefer using the file persistence, you must create an empty file in the local drive named zcrm_oauthtokens.txt. Further, set the file path in the token_persistence_path, of the $configuration associative array. Do not include "zcrm_oauthtokens.txt" in the path.

For example, if the file is in a folder named "TokenStorage", then

token_persistence_path="{path/to/TokenStorage}"

c. Custom Persistence

From the PHP SDK version 2.0.0, you can have your own implementation of persistence.

You must mention the name of the persistence class in the persistence_handler_class_name key of configuration associative array. Provide the file path of the PHP file that implements the custom persistence, in the persistence_handler_class key of the configuration associative array. The class must implement the ZohoOAuthPersistenceInterface.

You must write an implementation of the inbuilt ZohoPersistenceHandler interface, with the following methods:

getOAuthTokens($userEmailId)—invoked to fetch the saved tokens. This method should return ZohoOAuthTokens object for the library to process it.
saveOAuthData(ZohoOAuthTokens tokens)—invoked to store the tokens.
deleteOAuthTokens($userEmailId)— invoked to delete the tokens.

Step-5: Initialization

Once you define the OAuth configuration, you can initialize the PHP client application.

You need to generate the tokens (grant/access/refresh) to run the app.

Generating the tokens

As the V2 Zoho CRM APIs follow the OAuth2.0 protocol, it is mandatory to authorize the OAuth2.0 app before using the SDK functions with an access token.

You can generate an access token from a grant token.

You can generate the grant token in two ways based on the type of client.

For Self Client Applications

Log in to Zoho and go to Zoho Developer Console.
Select your Self Client.
Provide the necessary scopes separated by commas, along with the scope aaaserver.profile.READ.
Select the Time Duration from the drop-down. This is the time the grant token is valid for.
Provide a description for the scopes. Click GENERATE.
Copy the grant token.

For Web-based Applications

It is the responsibility of your client app to generate the grant token for the users trying to login.

Your application's UI must have the Login with Zoho option to open the grant token URL of Zoho, which would prompt for the user's OAuth2.0 authorization.

Upon the successful login of the user, the grant token will be sent as a parameter to your registered redirect URL.

Generating an access token from the grant token

Use the below code snippet in your main class.

$configuration =array("client_id"=>"1000.xxxxxxxxxxx","client_secret"=>"831bxxxxxxxxxxxx","redirect_uri"=>"","currentUserEmail"=>"patricia@zylker.com");

ZCRMRestClient::initialize($configuration);

$oAuthClient = ZohoOAuth::getClientInstance();

$grantToken = "paste_the_self_authorized_grant_token_here";

$oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

Note

The code snippet to generate the access token from the grant token is valid only once per grant token. If the grant token expires before you generate the access token, you must generate a new grant token only.
Generating access and refresh tokens is a one-time process. After the tokens are generated for the first time, the SDK persists them based on the keys defined in the configuration dictionary, and refreshes the access token as and when required.

App Startup

Invoke the following line of code every time you start your client app.

$configuration =array("client_id"=>"1000.xxxxxxxxxxx","client_secret"=>"831bxxxxxxxxxxxx","redirect_uri"=>"","currentUserEmail"=>"patricia@zylker.com");

ZCRMRestClient::initialize($configuration);

Sample SDK Code

The following image shows the sample SDK code to create a new record. The downloadable sample code is attached.

For more sample codes, refer to our SDK guide.

We hope you found this post useful. Keep a tab on this series for more exciting topics!

Reach out to us at support@zohocrm.com if you have any questions, or let us know in the comment section.

We will meet you next week with another useful topic.

Cheers!

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes