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

• Related Module in Sharing Rules

  Zoho CRM team recently added the feature to filter records by Related Records It will be really beneficial if we can have this feature for Sharing Rules as well

• Assignment Thresholds Resetting After Lead Conversion

  Hello everyone, We're facing an issue with Zoho CRM's lead assignment thresholds that makes them unsuitable for our workflow. I'm hoping to find a potential workaround or solution from the community. Here’s our current process: A new lead is created automatically

• Zoho CRM Analytics - Allow To Reorder Dashboards

  I would like to suggest that you add the ability to reorder dashboards in the Analytics Module. I can see that this has been requested some time ago, the latest 9 years ago. I am not sure if this is a big or small endeavor, but such a small fix can go

• Territory view for custom modules?

  I have recently activated territories however I can't seem to find how to use territories for custom modules? These modules have territories:  Contacts /  Accounts / Opportunities These modules don't have territories:   Buildings (custom module) and 

• Zoho Books - How to Invoke a Custom Function in Schedulers

  We have multiple schedulers that send emails to customers in batches. Currently, we are maintaining the same code across several schedulers. Is it possible to use a custom function inside a scheduler script? If yes, how can we invoke the custom function

• Approval Process Comments

  Is it possible to view the comments entered during the approval or rejection of a record in the approval process? If not, is there a way to require a field to be completed upon approval or rejection?

• Login for test case

  Had a few questions regarding authentication test cases and couldn't find an answer in the the docs. 1. If an app like Zoho Creator requires authentication before providing access, do I need to create a login function and add it to each test case? 2.

• Zoho / Outlook Calendar sync

  The current Marketplace -> Microsoft -> Meetings integration needs 2 changes. 1. The current language for the Two-Way sync option should be changed. It currently states, "Sync both your Zoho CRM Calendar and Office 365 Calendar meetings with each other."

• Customer members area

  Does FSM support a customer members area? If not what do you propose we use if we want the data used in FSM for customers to give them an area / login to see past orders, create new orders and general announcements.

• Zoho Books-Accounting on the Go Series!

  Dear users, Continuing in the spirit of our 'Function Fridays' series, where we've been sharing custom function scripts to automate your back office operations, we're thrilled to introduce our latest initiative – the 'Zoho Books-Accounting on the Go Series'.

• Desktop app doesn't support notecards created on Android

  Hi, Does anybody have same problem? Some of last notecards created on Android app (v. 6.6) doesn't show in desktop app (v. 3.5.5). I see these note cards but whith they appear with exclamation mark in yellow triangle (see screenshot) and when I try to

• Notes created in mobile can no longer be accessed in desktop

  Working with a 2013 Mac running OS 10.14.6; Desktop Notebook version 4.5.3. Using Motorola Moto G Power 5G - 2024; Android app version 6.7 I have been using Notebook for some years. Starting several weeks ago, the notes newly created ion the phone can

• Function #49: Manage varying installment payments using Zoho Books

  . Hello everyone, and welcome back to our series! Last week, we discussed automating the collection of fixed installment payments in Zoho Books. But what if your payment structure involves charging varying percentages of the invoice total as installments?

• Zoho Writer - Option to Export as .zdoc format

  I've noticed that it's not possible to export a Zoho Writer Document in the .zdoc format. Isn't zdoc, Zoho Writer's own format? My use case is that I sometimes need to create quite complex documents with floating elements, which sometimes need to become

• Is it possible for contacts to "Re-enter" a workflow in Zoho Campaign?

  We are currently working on a way to automatically add users to from one list to other lists based on specific criteria, but can't seem to find a native way of doing this so we are trying to use Workflows to do this. So, for example, if a user's status is set to "Active," then they should be added to the list "Active Users." If the same user's status is then set to "Paused," they should be added to the list "Paused Users" and removed from the list "Active Users." This works fine for the first go

• Bulk upload images and specifications to products

  Hi, Many users have asked this over the years and I am also asking the same. Is there any way in which we can bulk upload product (variant) images and product specifications. The current way to upload/select image for every variant is too cumbersome.

• Out of Office for Just One of My Alias Email

  Can I set up the Out of Office Reply for Just One of my Alias Email Addresses?

• Can I map multiple Surveys into the CRM using the same fields?

  Hello, We are a healthcare practice that offers two distinct services (Nutrition and Primary Care). We use Zoho Survey for our lead generation form (Get Started Survey), which allows people to express interest in one of the two services and even allows

• Dealing with API responses where integers have more than 16 digits

  Hi there How do I deal with an api response contaning an int or float with more than 16 digits (before any decimal places for a float). I constantly receive the response "Unable to cast the 'BigInteger' value into a 'BIGINT' value because the input is

• Can't change form's original name in URL

  Hi all, I have been duplicating + editing forms for jobs regarding the same department to maintain formatting + styling. The issue I've not run into is because I've duplicated it from an existing form, the URL doesn't seem to want to update with the new

• Need Inactive accounts to be visible in Reports in Zoho Books

  I N=need Inactive accounts to be visible in Reports in Zoho Books to do recons of the accounts but when i see the same they are not visible in the Accountant - Account Transactions report

• unblock e-mail

  please unblock my e-mails info@meatnews.gr and myrtokaterini@meatnews.gr

• Add Zoho Mail for users who do not need Zoho One

  We have licenses for ZOho One for teams that need to use the suite of products that Zoho One offers.  We have 8 more people who only need email access and we would like to add just a Zoho Mail.  They do not need the Zoho One license.  We are currently

• ZML vs HTML Snippet - which is better?

  Are there certain use cases where one is better than the other?

• Auto CheckOut Based On Shift.

  This Deluge script runs on a scheduled basis to automatically set the 'Actual_Check_Out' time for employees who haven't manually checked out. If the current time is past their scheduled 'Shift_End_Time', the script updates the check-out time to match

• How to remove some users in zoho accounts

  How to remove some users in Zoho accounts.

• Infinite loop of account verification

  Hi I can't do anything on my zoho account.  I always get this message Hi Sheriffo Ceesay As a security measure, you need to link your phone number with this account and verify it to proceed further. When ever I supply the details, it displays that the number is associated with another account. I don't have any other account on zoho so this is really annoying. 

• Load PO_Date field (Purchase Order) with current date in Deluge

  Hi, I'm not a full time developer, just helping to customize our CRM, in the small company I work for. There must be something wrong with me, because I can't do something so simple as complete a field with the current date in a function using Deluge.

• Zoho CRM in Microsoft Power Automate Custom Connector

  Hi everyone, I’m building a Power Automate flow that integrates Microsoft Bookings with Zoho CRM. The goal is to automatically create a meeting (event) in Zoho CRM whenever a new appointment is booked via Microsoft Bookings. To achieve this, I created

• Spell check sucks

  Come on guys, it's 2024 and your spell check is completely retarded. You gotta fix it.

• How to include total km for multiple trips in expense report.

  Whenever I create a mileage report it only shows the total dollar amount to be reimbursed. The mileage for each individual trip is included but I also need to see the total distance for all trips in a report? How do I do this?

• Outgoing blocked: Unusual activity detected.

  I just made payment for my Zohomail Today and have been debited so i will like to be Unblocked because this is what it says (Outgoing blocked: Unusual activity detected) Thank you i await your swift responses

• Zoho One Login Issue - Unable to receive OTP

  Hi Support Team, I am experiencing a unique login issue with Zoho One. I am attempting to log in from India using Zoho Login credentials provided by a USA-based client. Their Zoho account is hosted on a US data center. After entering the username and

• Question Regarding Managing Sale Items in Zoho Books

  Good day, I was wondering about something. Right now, Zoho Books doesn’t seem to have a way to flag certain items as being on sale. For example, if I want a list of specific items to be on sale from October 1 to October 12, the user would have to export

• In the Zoho Creator Customer Payment form i Have customer field on select of the field Data want to fetch from the invoice from based on the customer name In the Customer Payment form i Have subf

  In the Zoho Creator Customer Payment form i Have customer field on select of the field Data want to fetch from the invoice from based on the customer name In the Customer Payment form i Have subform update Invoice , there i have date field,Invoice number

• Problem of Import Client Users From CRM and or Expense

  I am premium plan user on Projects. I have about 500 customers on Expense and CRM that integrated with each other. According to at below link, I am trying to import clients from CRM, system not allowed to select any customer. If I import from Expense,

• Unable to see free plan option

  Hello Zoho Support Team, I hope you are doing well. I am trying to sign up for Zoho Mail, but I am unable to see the option for the free plan. Could you please guide me on how I can access or activate the free plan? Thank you for your assistance.

• unblock my zoho mail account. outlines@zoho.com

  please unblock my zoho mail account, outlines@zoho.com

• domain not verified error

  Hi when i try to upload a video from zoho creator widget to zoho work drive iam getting domain not verified error.I don't know what to do .In zoho api console this is my home page url https://creatorapp.zoho.com/ and this is my redirect url:www.google.com.Iam

• equest to Disassociate Bigin from Zoho One and Migrate to Standalone (Upgrade to Bigin Premier – 3 Seats, Annual)

  Dear Zoho One Support Team, I’m writing to request your assistance to disassociate (remove) the Bigin application from our Zoho One organization while preserving all existing Bigin data. After the disconnection is successfully completed, we intend to

• Next Page