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

• Whatsapp Limitation Questions

  Good day, I would like to find out about the functionality or possibility of all the below points within the Zoho/WhatsApp integration. Will WhatsApp buttons ever be possible in the future? Will WhatsApp Re-directs to different users be possible based

• Create a draft in reply to an email via Emails API

  Hi, I’d like to use the outgoing webhook to automatically create a draft reply to incoming mail. How can I use the Emails API to create a draft reply that is linked to an existing email thread? I couldn’t find the relevant method in the documentation.

• India Tech Support

  Is there no phone tech support number for India? And no chat facility either?

• Billing Management: #1 Billing a Universal Business Routine

  Hello, As the saying goes, "Do the hardest job first." We started with the complex subject of finance and revenue management, which is considered the backbone of any business. Now, let's shift our focus and take a deep dive into this Billing Management,

• Show/ hide specific field based on user

  Can someone please help me with a client script to achieve the following? I've already tried a couple of different scripts I've found on here (updating to match my details etc...) but none of them seem to work. No errors flagged in the codes, it just

• What is a a valid JavaScript Domain URI when creating a client-based application using the Zoho API console?

  No idea what this is. Can't see what it is explained anywhere.

• 5名限定 課題解決型ワークショップイベント Zoho ワークアウト開催のお知らせ (9/25)

  ユーザーの皆さま、こんにちは。Zoho ユーザーコミュニティチームの藤澤です。 9月開催のZoho ワークアウトについてお知らせします。 今回はZoomにて、オンライン開催します。 諸事情につき、今月の開催回は中止となりました。 次回は10/31（金）14時からの開催を予定しています。 ━━━━━━━━━━━━━━━━━━━━━━━━ Zoho ワークアウトとは？ Zoho ユーザー同士で交流しながら、サービスに関する疑問や不明点の解消を目的とした「Zoho ワークアウト」を開催します。 Zoho

• Zoho Calendar not syncing correctly with personal Google Calendar

  Coming to this forum as Zoho Calendar support team is not responding, any more. For the past 8 weeks, I have been having an issue with Zoho Calendar not syncing with my personal Google Calendar correctly. I subscribed to Zoho Calendar iCal in my personal

• Introducing Assemblies and Kits in Zoho Inventory

  Hello customers, We’re excited to share a major revamp to Zoho Inventory that brings both clarity and flexibility to your inventory management experience! Presenting Assemblies and Kits We’re thrilled to introduce Assemblies and Kits, which replaces the

• Customer Parent Account or Sub-Customer Account

  Some of clients as they have 50 to 300 branches, they required separate account statement with outlet name and number; which means we have to open new account for each branch individually. However, the main issue is that, when they make a payment, they

• need a packing list feature

  In our business, goods listed on an invoice are packed in separate boxes and shipped off. for e.g. an invoice may have 10 items. each item could then be packed in different boxes depending on qty of each item. this packing list is as important as the invoice for purposes of shipping documents.  Request you to add this feature asap.

• Workdrive 5.0 / API Documentation Workflows

  Hi Zoho, When will the API documentation of the workflows be published? We are interested in using it to trigger manual workflows from an external application. Greetings, Justin

• How to keep track of bags, cans, drums of inventory?

  We buy and sell products that are packaged in bags 🛍️, cans🥫, drums🛢️, etc. with batch numbers. When we get a shipment of one of the products, how do we track we received (say) 10 cans each of 5L of a product and maybe we received 10 cans of another

• Zoho Error: This Operation has been restricted. Please contact support-as@zohocorp.com for further details

  Hello There, l tried to verify my domain (florindagoreti.com.br) and its shows this error: This Operation has been restricted. Please contact support-as@zohocorp.com for further details. Screenshot Given Below -  please check what went wrong. Thanks

• How many ZOHO-Sites does the ZOHO-One Suite allow for?

  The free version of ZOHO-Sites allows for two sites, but it seems that the professional version (which is included in the ZOHO-One Suite) only allows for two websites. Is that correct? How many sites can I have within one ZOHO-One account?

• Webhook from Zobot to Zoho Flow fails

  I'm trying to connect from zobot to zoho flow. When testing in zflow, I am receiving all entered data from the connector correctly. The SalesIQ connector's "outputreaction" is {} (is this normal or is there a problem?). But as soon as I try my chat bot

• Transition from Sole Proprietorship to GmbH (Limited Liability Company) – Best Approach in Zoho Books / Zoho One

  Hello everyone, I am currently operating under a Zoho One plan with a sole proprietorship in Switzerland. As of January 1st, 2026, I will be incorporating a new legal entity – a GmbH (Swiss equivalent of a Limited Liability Company). While the business

• Best way to display complex Bookings Consultation Descriptions on Zoho Site?

  I am a new user so apologies if this has been asked before. I couldn't find any answers in the forum. We offer 18 complex Consultations to our subscribers. Our current platform lets me put detail on these Consultations thoroughly (200-300 words) during

• DKIM cannot be enabled for the domain as no verified default selector present

  Hi Support Team, For Domain DKIM record trying to enable status. but showing error "DKIM cannot be enabled for the domain as no verified default selector present" So, please resolve the issue. Thank you.

• Issue Connecting My Domain to Zoho Sites Despite Purchasing It from Zoho

  Hello, I am facing an issue connecting my domain to my website on Zoho Sites. Details of the issue: I purchased the domain directly from Zoho. I am already using the same domain successfully with Zoho Mail. However, when I try to assign this domain to

• Insert auto number from main form into subform rows

  Hello. I'm trying to take from my main form "order number" which i have setup as an auto generated number into every line created in my subform. So when a row is created in my subform i want the "order number " from the main form to be inserted automatically.

• Dark Mode - Font Colors Don't Work

  When editing a document in Dark Mode and selecting font colors, they don't show up on screen.  Viewing/editing the same document in Light Mode shows them just fine.

• Integrate Bunq with ZOHO Bookes

  We are new users of ZOHO Books, and our bank (BUNQ, in the Netherlands) isn't listed on the bank integrations. Is there a way to handle this?

• Access Denied

  I am iOS Developer and updating our clients project and shifted ZohoDeskPortalCore SDKs from cocoapods to SPM and changed few lines of code but now i am get access denied, the help center app is unavailable. please contact administrator.

• Using Zoho Desk to support ISMS process

  Hi, I am evaluating using Zoho Desk for security incident management. This seems to be aligned with Zoho Desk purpose as its just another type of incident. However in security incident management, ideally I can link incidents (tickets) with a risk from

• Bin Locations

  Dear all, I am wondering if someone has the ability to develop the bin locations option for zoho inventory (integrated with zoho books) Regards, Ryan

• TaxJar vs Avalara

  Hi, I'm evaluating adoption of a sales-tax service for US based business. Anyone else have experience with TaxJar and Zoho Books? I am a Zoho One subscriber so anticipate needing to use Flow to make this work. It seems like Avalara are simply too expensive

• How to check Leads with no Task (open activity)

  Hi everyone, I was wondering if there’s a way to view leads that don’t have any tasks assigned or open activities linked to them.

• What can we do on our end to improve the Answer bot answers?

  Hi, I'm using the Answer bot card in the Codeless bot builder. I've input several questions and their answers in the FAQ section to feed the Answer bot. The text is all in French, as this is the language our customers communicate in. I've tried testing

• Taxes for EU B2B Transactions

  Currently, ZC doesn't seem to have a procedure for validating VAT numbers of businesses purchasing in another EU state, and removing local VAT is valid.  This is essential for all inter EU B2B trade.

• How to upload file to Connect using API?

  Hi there. I looked at the API documentation and nowhere did it mention how to use the API method to upload a file even though it is mentioned that it is possible to be done so. Please help.

• Items Landed Cost and Profit?

  Hello, we recently went live with Zoho Inventory, and I have a question about the Landed Cost feature. The FAQ reads: "Tracking the landed cost helps determine the overall cost incurred in procuring the product. This, in turn, helps you to decide the

• Group Tax in Service Line Items

  Hi FSM Team! I noticed that when you update a tax in the service line item the group tax is not showing up as an option. Let me know what can be done thank you!

• FSM Improvement Idea - Show an Import button when there is no data

  I am setting up FSM for a client and I noticed that there is no option to import data, see screenshot below. Even when you click Create Contact there is only an option to Import from Zoho Invoice. It is only after you add at lease 1 record that the Import

• Zoho FSM API Delete Record

  Hi FSM Team, It would be great if you could delete a record via API. Thank you,

• OAUTH_SCOPE_MISMATCH Error for Marketing Automation APIs with CRM Plus Account

  I'm trying to integrate Marketing Automation journey triggering via API but getting OAUTH_SCOPE_MISMATCH errors. I need clarification on API access for CRM Plus users.

• Access token generate from the refresh token not working for API

  Dear Sir/Madam, When I use my refresh token to obtain new access_token, that token return INVALID_TOKEN when the same API is called. I made sure that my api site is correct and match the auth web site. However the original access_token work fine.

• Function #4: Schedule Customer Statements

  Regularly sending statements to customers is an imperative part of many business processes as it helps foster strong customer relationships and provides timely guidance on payments. While you can generate the statement of accounts and have it sent over

• Limiting search or dependencies with an asterisk "*".

  I have a form with several dependency fields with options still developing for each field. Since these options were developing and not yet ready to be a selection in the field, I placed a filter for the dropdown field. In this filter, I selected fields

• Cross Data Center Support for 1:1 Chats with External Users

  Hello Zoho Cliq Team, We hope you're doing well. We appreciate the recent enhancement that enables cross data center collaboration in external channels, which has already improved communication across distributed teams. However, we’ve noticed that this

• Next Page