Kaizen #94 - PHP SDK V4 - Configuration and Initialization

Hello and welcome to another Kaizen week!

In previous Kaizen posts, we have covered in detail how to configure and initialize PHP SDKs for Zoho CRM v2.1 APIs. We have since released SDKs for v4 and v5 APIs. However, starting from v4, there are some changes in the configuration and initialization process.  In this post, we will discuss you how to configure and initialize PHP SDK v4 and v5.

The PHP Software Development Kit (SDK) simplifies the integration of client PHP applications with Zoho CRM. Acting as a wrapper for the REST APIs, it streamlines the usage of Zoho CRM services. 

Before proceeding with the configuration, make that your client application meets the prerequisites. This includes having PHP 7 or above installed, along with the cURL extension, which is necessary for connecting and communicating with Zoho CRM APIs.

I. Register your application with Zoho CRM

Registering your application with Zoho CRM is a mandatory step in order to authenticate and authorize API calls using the OAuth2.0 standards.

1. Go to https://api-console.zoho.com
   
2. Click on Get Started or +ADD CLIENT.
   
3. Choose the Client Type as Self-Client or Server based Applications depending on your application.
4. Fill in the necessary details and click CREATE. Once you successfully register your self-client, you will receive a Client ID and Client Secret.
   

II. Installing the PHP SDK 

1. If not already installed, follow the instructions provided at the corresponding link to install Composer.
   
   

   Mac/Linux	curl -sS https://getcomposer.org/installer | php (terminal command)  https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx
   Windows	https://getcomposer.org/doc/00-intro.md#installation-windows

   
   
2. Install PHP-SDK using Composer
   
1. Navigate to the workspace of your client app.
   
2. Run the following command in the workspace. Upon successful installation, the system will create a package named vendor in the workspace of your client app. 

   composer require zohocrm/php-sdk-4.0 (for v4 APIs)  composer require zohocrm/php-sdk-5.0 (for v5 APIs)

3. To use the SDK in your project, add the following line in your project PHP files. This loads and includes our PHP-SDK library in your project. If you skip this step, you will get a fatal error in response due to the missing libraries.
   

   require 'vendor/autoload.php';

   
   

III. Token Persistence

Token persistence refers to storing and utilizing authentication tokens provided by Zoho, enabling the SDK to refresh the access tokens without user intervention. The SDK offers three types of persistence - File, DB, and Custom - with file persistence being the default method. 

The persistence is achieved by writing an implementation of the inbuilt TokenStore interface, which has the following callback methods. 

Methods	Description
findToken(Token $token)	Invoked before firing a request to fetch the saved tokens. This method returns an implementation of Token interface object for the library to process it.
saveToken(Token $token)	Invoked after fetching access and refresh tokens from Zoho. This method saves the token details.
deleteToken($id)	This method is used to delete the given token details.
getTokens()	The method is used to retrieve all the stored tokens.
deleteTokens()	The method to delete all the stored tokens.
findTokenById($id)	This method is used to retrieve the user token details based on the unique ID.

Here, $token is an instance of the Token interface.

Token Persistence using a Database

In Database persistence, tokens are stored and retrieved from a database (e.g., MySQL).

Create a table in your database with the following required columns. For example, if you want to persist your tokens in a table named token in database named zoho, use this:

CREATE DATABASE zoho; // use this to create database named zoho // use this to create a table named token, with the following necessary columns CREATE TABLE token (    id varchar(10) NOT NULL,   user_name varchar(255) NOT NULL,   client_id varchar(255),   client_secret varchar(255),   refresh_token varchar(255),   access_token varchar(255),   grant_token varchar(255),   expiry_time varchar(20),   redirect_url varchar(255),   primary key (id) );

Note that the columns are different for API v2.1. Please refer to this post for more details. . 

File Persistence

File Persistence allows storing and retrieving the authentication tokens from the given file path. The file contains id, user_name, client_id, client_secret, refresh_token, access_token, grant_token, expiry_time and redirect_url. 

Custom Persistence

Custom Persistence refers to a technique where users can create their own method of storing and retrieving authentication tokens. To use this method, users need to implement the TokenStore interface and override its methods according to their own logic.

IV. Configuration

The configuration step involves setting up various details in the SDK, such as user authentication, token persistence, logging, API call timeout settings, and more. The following keys are defined during this process:

1. environment (mandatory): The API environment which decides the domain and the URL to make API calls, in Domain::Environment pattern.
   Domains : USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter
   Environments : PRODUCTION(), DEVELOPER(), SANDBOX()
2. Token (mandatory): This key contains the user token details. Create an instance of OAuthToken with the information that you get after registering your Zoho client.  Depending on the available tokens, you can select one of the following flows:
   
   Note : You need to generate the tokens (grant/access/refresh) beforehand to use them in the respective flows.
   
   a) grantToken flow - You should use the grant Token for configuration.
   

   $token = (new OAuthBuilder())   ->clientId("clientId")   ->clientSecret("clientSecret")   ->userSignature($user) //optional   ->grantToken("grantToken")   ->redirectURL("redirectURL") //optional   ->build();

   
   
   b) refreshToken flow - Utilize the refresh token in this flow.
   

   $token = (new OAuthBuilder())   ->clientId("clientId")   ->clientSecret("clientSecret") ->userSignature($user) //optional   ->refreshToken("refreshToken")   ->build();

   
   
   c) accessToken flow - You can use the access token to configure in this flow. Please note that the token will not be persisted in this case, and the access token will be directly used to make the API calls.
   

   $token = (new OAuthBuilder())    ->userSignature($user) //optional    ->accessToken("accessToken")    ->build();

   
   
   d) id flow - You can use the id from the persisted token file/DB to make API calls. The id is a unique system generated value for each token details entry in the file/DB.
   

   $token = (new OAuthBuilder())    ->id("id")    ->build();

   
   
3. logger (optional) : Create an instance of Logger Class to log exception and API information. You can set the level you want to log (FATAL, ERROR, WARNING, INFO, DEBUG, TRACE, ALL, OFF), and also configure the file path and file name for the log file. The default level is OFF.
   
   
   

   $logger = (new LogBuilder())   ->level(Levels::INFO)   ->filePath("/Documents/php_sdk_log.log")   ->build();

   
   
4. store (optional) : Configure your token persistence using this method. If this is skipped, the SDK creates the sdk_tokens.txt in the current working directory to persist the tokens by default. For more details, refer here.
5. SDKConfig (optional) : The additional SDK configurations are taken care of with this method. 
   

   Configuration Key	Description
   autoRefreshFields  Default Value : False	A boolean configuration key to enable or disable automatic refreshing of module fields in the background. If set to true, fields are refreshed every hour, and if set to false, fields must be manually refreshed or deleted.
   pickListValidation  Default Value : True	This field enables or disables pick list validation. If enabled, user input for pick list fields is validated, and if the value does not exist in the pick list, the SDK throws an error. If disabled, the input is not validated and the API call is made.
   enableSSLVerification  Default Value : True	A boolean field to enable or disable curl certificate verification. If set to true, the SDK verifies the authenticity of certificate. If set to false, the SDK skips the verification.
   connectionTimeout  Default Value : 0	The maximum time (in seconds) to wait while trying to connect. Use 0 to wait indefinitely.
   timeout  Default Value : 0	The maximum time (in seconds) to allow cURL functions to execute. Use 0 to wait indefinitely.

   
   
6. requestProxy (optional) : Contains the proxy properties of the user. Configure this only if you're using a proxy server to make the API calls.
   

   $requestProxy = (new ProxyBuilder())  ->host("proxyHost")  ->port("proxyPort")  ->user("proxyUser")  ->password("password")  ->build();

   
   
7. resourcePath (optional) : Configure the absolute directory path to store user specific files containing module fields information. If skipped, the files will be stored in the project directory itself.

V. Initilization

After completing the configuration, you can proceed with initializing the SDK, and begin making API requests.

Here is a sample code to initialize the SDK, using refresh token flow and DB Persistence. 

<?php   use com\zoho\api\authenticator\OAuthBuilder;   use com\zoho\api\authenticator\store\DBBuilder;   use com\zoho\crm\api\InitializeBuilder;   use com\zoho\crm\api\UserSignature;   use com\zoho\crm\api\dc\USDataCenter;   use com\zoho\api\logger\LogBuilder;   use com\zoho\api\logger\Levels;   use com\zoho\crm\api\SDKConfigBuilder;   use com\zoho\crm\api\ProxyBuilder;   require_once "vendor/autoload.php";   class Initialize   {     public static function initializeSDK()     {       $user = new UserSignature("patricia@zoho.com");       $environment = USDataCenter::PRODUCTION();       $token = (new OAuthBuilder())         ->clientId("1000.xxxxxxxxxxxxxxxx")         ->clientSecret("554a9xxxxxxxxxxxxxxxxx") ->userSignature($user) //optional         ->refreshToken("1000.xxxxxxxxxxxxxxxxxxxx")          ->redirectURL("www.zoho.com") //optional         ->build();      $logger = (new LogBuilder())        ->level(Levels::INFO)        ->filePath("/Documents/php_sdk_log.log")        ->build();      $tokenstore = (new DBBuilder())        ->host("insert_your_hostname_here")        ->databaseName("insert_your_database_name_here")        ->userName("insert_your_db_username_here")        ->password("insert_your_db_password_here")        ->portNumber("insert_your_portnumber_here")        ->tableName("insert_your_table_name_here")        ->build();      $autoRefreshFields = false;      $pickListValidation = false;      $connectionTimeout = 2;      $timeout = 2;      $enableSSLVerification = false;      $configInstance = (new SDKConfigBuilder())        ->autoRefreshFields($autoRefreshFields)        ->pickListValidation($pickListValidation)        ->sslVerification($enableSSLVerification)        ->connectionTimeout($connectionTimeout)        ->timeout($timeout)        ->build();      $resourcePath = "/Documents/phpsdk-application";      $requestProxy = (new ProxyBuilder())        ->host("proxyHost")        ->port("proxyPort")        ->user("proxyUser")        ->password("password")        ->build();     (new InitializeBuilder())       ->environment($environment)       ->token($token)       ->store($tokenstore) //optional       ->SDKConfig($configInstance) //optional       ->resourcePath($resourcePath) //optional       ->logger($logger) //optional       ->requestProxy($requestProxy) //optional       ->initialize();    }  } Initialize::initializeSDK(); ?>

You are now set to use the PHP SDK and make API calls. 

If you have any queries, let us know the comments below, or send an email to support@zohocrm.com. We would love to hear from you!

Cheers!

• Topic Participants

• Anu Abraham

  

• Sticky Posts

• Kaizen #197: Frequently Asked Questions on GraphQL APIs

  🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

• Kaizen #198: Using Client Script for Custom Validation in Blueprint

  Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

• Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

  Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

• Kaizen #193: Creating different fields in Zoho CRM through API

  🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

• 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

• Recent Topics

• CRM : Function to add user name to text field

  I have a lookup field in a module that is linked to the CRM users so we can assign a Project Lead to the customer. Sadly Zoho Marketing Automation doesn't sync Lookup fields so I need to extract information from the lookup to text fields: Lookup field

• Export PDF File Name

  Is it possible to change the default Zoho .pdf naming scheme for inventory items like quotations? Would like to use the the Subject as the default quote name. Is this possible?

• How to change the from address from 'no reply' for an email template in CRM

  Hi, We have our CRM set up with the from field as sales@XXX. I have just created a series of email templates and sent a test and they are sending from noreply@zoho I have tried searching for how to change the email template but don't have the options

• Zoho CRM Client Script - SetCriteria in lookup Field

  Hello All One More Zoho CRM Client Script Tips & Trick. Now you can Set the Criteria on Your lookup in zoho CRM, It Comes With a Create Page, Edit Page, and Details Page (Standard). Example:- We have a Room Module that includes Room Name, Status, Campus,

• Kaizen #71 - Client Script ZDKs for Detail (Canvas) Page

  Hello everyone! Welcome back to another interesting Kaizen post. In this post, we can discuss Client Script ZDKs support for Detail (Canvas) Page. What is Detail (Canvas) Page? A Detail(Canvas) Page allows you to customize the record detail page to your

• how to use validation rules in subform

  Is it possible to use validation rules for subforms? I tried the following code: entityMap = crmAPIRequest.toMap().get("record"); sum = 0; direct_billing = entityMap.get("direct_billing_details"); response = Map(); for each i in direct_billing { if(i.get("type")

• Add Custom Reports To Dashboard or Home Tab

  Hi there, I think it would be great to be able to add our custom reports to the Home Tab or Dashboards. Thanks! Chad

• Rich-text fields in Zoho CRM

  Hello everyone, We're thrilled to announce an important enhancement that will significantly enhance the readability and formatting capabilities of your information: rich text options for multi-line fields. With this update, you can now enjoy a more versatile

• Zoho Reports Duplicating Entries

  I have a custom costing tab with a table where we entre invoices. These are under a Heading (PO Subject) and notes added in the form with different line items. In the reports, I have organised the report to group per PO Subject, with the total of the

• Validation Rule Not Working for Mandatory Field in Zoho Blueprint

  As a Zoho user, we created a validation rule for a specific field. However, we noticed that when we made the same field mandatory within a Blueprint, the validation rule we defined did not work. When we reported this issue to Zoho Support, they stated

• Notes Issues

  Been having issues with Notes in the CRM. Yesterday it wasn't showing the notes, but it got resolved after a few minutes., Now I have been having a hard time saving notes the whole day. Notes can't be saved by the save button. it's grayed out or not grayed

• Export from Contacts module to Products module in Zoho CRM

  Good afternoon, I would like to send a number of contact info from the Contacts module into the customized module (tickets to an event) in one operation. I have selected several contacts in the Contact module (people who I have labelled as people I want

• Zoho Commerce

  Hi, I have zoho one and use Zoho Books. I am very interested in Zoho Commerce , especially with how all is integrated but have a question. I do not want my store to show prices for customers that are not log in. Is there a way to hide the prices if not

• Can’t receive emailI c

  I have generated a basic for but when I submit it I don’t get a email, I’ve been in the settings and tested me email, all appears correct, can you please help me

• Data Capture for Historical Activity (Especially One Lead Downloading Variois reports without Overwriting the info)

  Is there a better way in Zoho CRM to capture and archive a lead’s historical activity—specifically whenever they download reports—so that the data is stored without being overwritten?”

• Client Script - Updating Field Value in Detail Page of a Lead

  Hello, I'm trying to use Client Script To enrich some data of the Lead when one of my User fill the "City" field in the detail page of the Lead. This is my Script: log (value); var response = ZDK.Apps.CRM.Functions.execute("getInfoCitta", { "nomeCitta":

• Auto shapes in Zoho sheet.

  Does Zoho sheet supports inserting auto shapes (rectangle, circle...). I did not see any option to do so.  If its not supported currently, is there any plans on bring in this features. Any timelines ?

• I Can't Clone Webinar that I Co-Organize

  How do i get our account admin to give me permission to clone our webinars? I am a co-organizer

• I want to Make the due date of the project appears automatically

  hello everyone I want to know if the zoho projects app can add automatically the END DATE of the project I added the duration, start after dates of each tasks in the project template & the starting date of the project itself and the end date of it doesn't

• Introducing Profile Summary: Faster Candidate Insights with Zia

  We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiring

• How to get the call recording external ID via desk API

  I have enabled phonbridge integration with Zoom Call. I am trying to access the call recording in Zoom by calling Zoom API. I have built a Desk workflow to trigger on a new call, to call a custom function. when calling the API, the response doesn't contain

• Can't View Project Names in Mobile App

  I can't view project names on PO's in the app, nor can I add that as a viewable PDF field in inventory on the computer. I've attached screenshots showing that in the mobile version whether you are on the PO, editing the PO, or viewing the PO line items,

• How do you print a refund check to customer?

  Maybe this is a dumb question, but how does anyone print a refund check to a customer? We cant find anywhere to either just print a check and pick a customer, or where to do so from a credit note.

• Notebook

  I have purchased the monthly pro subscription of Notebook. But it does not support my XP-Pen to write something in it. So it is not useful to me. Hence I am requesting you to help me to discontinue this subscription.

• Domain Mapping & Image Publishing Issues on Zoho Sites

  Hello, I am facing two issues with my Zoho Sites account: 1. Images not visible after publishing. 2. Domain mapping error: "Domain already exists". I am a paid customer. Please connect me with Live Chat Support or Zoho Assist so I can show my issue

• Prevent duplicate with custom fields?

  I was wondering something about custom field/custom modules in Zoho Desk. For some reason you can make a custom field mandatory but not unique? For example, if I create a custom module to manage equipment and renewal and make a field serial number no

• Round robin

  Hi, I'm trying to set up a round robin to automatically distribute tickets between agents in my team but only those tickets that are not otherwise distributed by other workflows or direct assignments. Is that possible and if so which criteria should I

• "Is Zoho CRM customer" vs "Is linked with Zoho CRM"

  Recently while building a Flow, I was setting up a Decision action following a Zoho Invoice Fetch record action. There were 2 choices that I had not seen as something I could manually action in Zoho Invoice: "Is Zoho CRM customer" and "Is linked with

• Two currencies

  More and more I am finding that internattional payments' fees are unpredictable. I would like, on my invoices that are in a foreign currency (eg. USD$ or EUR€) for there to be a GBP£ TOTAL display alongside the invoice's currency total. This would make

• Automatic Matching from Bank Statements / Feeds

  Is it possible to have transactions from a feed or bank statement automatically match when certain criteria are met? My use case, which is pretty broadly applicable, is e-commerce transactions for merchant services accounts (clearing accounts). In these

• Generate leads from instagram

  hello i have question. If connect instagram using zoho social, it is possible to get lead from instagram? example if someone send me direct message or comment on my post and then they generate to lead

• Zoho PDF editor has a lot of issues.

  Zoho PDF editor needs a lot of work. It hangs and glitches a lot. Deletes annotations and clearings randomly.

• Where is the desktop app for Zoho Projects???

  As a project manager, I need a desktop app for the projects I manage. Yes, there's the web app, which is AWESOME for cross browser and platform compatibility... but I need a real desktop app for Projects that allow me to enter offline information where

• How to Automate Monthly PDF Reports with Filters in Zoho Creator

  Hi everyone, I’m trying to build an automated monthly reporting process in Zoho Creator and would appreciate suggestions or best practices from anyone who has done something similar. What I’m trying to do: I have a form called New_Customer with fields

• Feedback: Streamlining Note Management in Zoho Notebook

  Dear Team/Support, I would like to share some feedback regarding the note management system that could help improve usability and accessibility for users like myself. Notebook 1 (screenshot attached): Currently, the system does not allow selecting and

• showing Limit exceeded

  Good afternoon...trust you're good. I've been having issues working with but it's not responding. it's showing Limit exceeded, sorry it seems like too many people are working on the sheet right now please try again later. meanwhile no one is working on

• Converting Sales Order to Invoice via API; Problem with decimal places tax

  We are having problems converting a Sales Order to an Invoice via API Call. The cause of the issue is, that the Tax value in a Sales Order is sometimes calculated with up to 16 decimal places (e.g. 0.8730000000000001). The max decimal places allowed in

• Sorting columns in Zoho Projects

  Hi, In project management best practice, sorting columns (ascending, descending) is an important tool. Sorting dates to see the order of tasks starting, sorting on priority or even on planned hours is a must for an efficient project control. Currently,

• Business Continuity - Disaster Recovery

  I know about the Zoho CRM backup .zip files, however, this doesn't include any of the infrastructure with like custom fields or custom modules. I am curious on what everyone has in place for a true backup or what your plan is if your Zoho instance were

• Upload API

  I'm trying to use the Upload API to upload some images and attach them to comments (https://desk.zoho.com/DeskAPIDocument#Uploads#Uploads_Uploadfile) - however I can only ever get a 401 or bad request back. I'm using an OAuth token with the Desk.tickets.ALL

• Next Page