Kaizen #84 - PHP SDK [Part I]

Kaizen #84 - PHP SDK [Part I]

Hello and welcome to another Kaizen week!

In this week's post, we'll show you how to get started with Zoho CRM's PHP SDK, and walk you through the configuration and initialization process.

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.

Why PHP SDK?

Easy authentication: You don't have to worry about manually managing authentication because the PHP SDK takes care of generating access/refresh tokens for you.
Easy and Efficient data exchange: With the PHP SDK, you can easily exchange data between Zoho CRM and your client PHP application, where the CRM entities are modelled as classes. You can declare and define CRM API equivalents as simple functions in your PHP application.

Prerequisites 

  • The client app must have PHP 7 or above with a cURL extension. cURL extension is used to connect and communicate with the Zoho CRM APIs.
  • The client app must have the PHP SDK installed through Composer. 

How to start using the PHP SDK?

  1. Prerequisite : Register your application with Zoho CRM.
  2. Install the PHP SDK.
  3. Knowledge Base : Token Persistence
  4. Configuration 
  5. initialization.

1. 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.
  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.

2. Install PHP SDK 

1. Install Composer, if not already installed. Please check the corresponding link for installation instructions.

2. Install PHP-SDK using Composer
  • Navigate to the workspace of your client app.
  • 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.   Note : This command installs SDK for API v2.1.

    composer require zohocrm/php-sdk-2.1

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';

3. Token Persistence

Token persistence refers to storing and utilizing authentication tokens provided by Zoho, enabling the SDK to refresh the access tokens without the need for 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. 

Method
Description
getToken($user, $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($user, $token)
Invoked after fetching access and refresh tokens from Zoho. This method saves the token details.
deleteToken($token)
This method is used to delete the given token details.
getTokens()
This method is used to retrieve all the stored tokens.
deleteTokens() 
The method to delete all the stored tokens.
getTokenById($id, $token) 
This method is used to retrieve the user token details based on the unique ID.

a. Token Persistence using a Database

Database persistence is a technique that involves storing and retrieving data from a database. If you prefer using database persistence, you can use MySQL. 
Create a table in your database with the required columns. For example, if you want to persist your tokens in a table named token in database named zoho, use the following:
CREATE DATABASE zoho; // use this to create database named zoho
// use this to create a table named token, with the necessary columns
CREATE TABLE token ( 
  id varchar(255) NOT NULL,
  user_mail 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)
);

In this example, your tokens will be persisted in the token table in your zoho database.

b. File Persistence

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

c. 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.

4. Configuration

Configuration is a critical step in which you set up SDK's configuration details like user authentication, token persistence, logging and API call timeout settings, and more. Listed below are the keys that you define in this step.

Key
Description
user
mandatory
Represents the mail id, which is used to identify and fetch tokens from the File or DB.
environment
mandatory
Represents the data centre details in Domain::Environment pattern.
Domains : USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter
Environments : PRODUCTION(), DEVELOPER(), SANDBOX()
token
mandatory
Contains user token details. Depending on the tokens, you can choose grantToken flow, refreshToken flow or accessToken flow.
logger
optional
Contains the configuration for logging exceptions and API call information. By default, the logs will be available in the workspace as sdk_logs.log.
store
optional
Contains details for the Token Persistence object. You can choose between DB Store, File Store or Custom Store, and configure accordingly.
SDKConfig
optional
Contains additional configuration details like timeout, autorefresh fields, picklistvalidation, etc
requestProxy
optional
Contains the details of the proxy, if you are using a proxy server to authenticate and make the API calls.
resourcePath
optional
The path containing the absolute directory path to store user specific files containing the module fields information.


Let us discuss how to configure each of them, in detail.
a. user : The user key will be used to store and identify the tokenstore details in the DB or File Storage for token persistence. Create an instance of UserSignature that identifies the current user with the following :
  1. $user = new UserSignature("patricia@zoho.com");
b. environment : The API environment which decides the domain and the URL to make API calls. 
  1. $environment = USDataCenter::PRODUCTION();
c. token : Create an instance of OAuthToken with the information that you get after registering your Zoho client. Depending on the tokens available with you, you can choose one of the following flows. 
Note : You need to generate the tokens (grant/access/refresh) beforehand. 
  • grantToken flow - You should use the grant Token for configuration.
    $token = (new OAuthBuilder())
      ->clientId("clientId")
      ->clientSecret("clientSecret")
      ->grantToken("grantToken")
      ->redirectURL("redirectURL")
      ->build();

  • refreshToken flow -In this flow, use the refresh token.
    $token = (new OAuthBuilder())
      ->clientId("clientId")
      ->clientSecret("clientSecret")
      ->refreshToken("refreshToken")
      ->redirectURL("redirectURL")
      ->build();

  • 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()
      ->accessToken("accessToken")
      ->build(); 

d. logger : 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.

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

e. store : 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.
  • DB Store - Configure the Database details, where you want to store your tokens.
    $tokenstore = (new DBBuilder())
    ->host("hostName")
    ->databaseName("dataBaseName")
    ->userName("userName")
    ->password("password")
    ->portNumber("portNumber")
    ->tableName("tableName")
    ->build();

  • File store - Give the absolute file path, where you want to store the tokens. 
    $tokenstore = new FileStore("absolute_file_path");

  • Custom Store - In this method, you can implement your own method for storing and retrieving the tokens. Please note that to do so, you must implement the TokenStore interface, and override its callback methods (getToken, saveToken, deleteToken, getTokens, deleteTokens, getTokenById). 
    $tokenstore = new CustomStore();

Note :  The corresponding storage will  have id, user_mail, client_id, client_secret, refresh_token, access_token, grant_token, expiry_time and redirect_url. The id is a unique system generated key.

f. SDKConfig : 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.
  1. $autoRefreshFields = false;
  2. $pickListValidation = false;
  3. $enableSSLVerification = true;
  4. $connectionTimeout = 2;
  5. $timeout = 2;
  6. $sdkConfig = (new SDKConfigBuilder())
  7. ->autoRefreshFields($autoRefreshFields)
  8. ->pickListValidation($pickListValidation)
  9. ->sslVerification($enableSSLVerification)
  10. ->connectionTimeout($connectionTimeout)
  11. ->timeout($timeout)
  12. ->build();
g. requestProxy : Create an instance of RequestProxy containing 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();

h. resourcePath : Configure path containing the absolute directory path to store user specific files containing module fields information.

$resourcePath = "/Documents/phpsdk-application";

5. Initilization

Once you have completed the configuration process, you can move on to 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\api\authenticator\store\FileStore;
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;
use com\zoho\api\authenticator\store\DBBuilder;

require_once "vendor/autoload.php";

class Initialize
{
  public static function initialize()
  {
    $user = new UserSignature("patricia@zoho.com");
    $environment = USDataCenter::PRODUCTION();
    $token = (new OAuthBuilder())
    ->clientId("1000.xxxxxxxxxxxxxxxx")
    ->clientSecret("554a9776d10ff016a92c1eb01xxxxxxxxxx")
    ->refreshToken("1000.xxxxxxxxxxxxxxxxxxxx")
    ->redirectURL("www.zoho.com")
    ->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;
    $sdkConfig = (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())
    ->user($user)
    ->environment($environment)
    ->token($token)
    ->store($tokenstore)
    ->SDKConfig($configInstance)
    ->resourcePath($resourcePath)
    ->logger($logger)
    ->requestProxy($requestProxy)
    ->initialize();
  }
}
?>


You are now all set to explore the functionalities of SDK. Here is a sample code to get the records from Leads module, with the ifmodifiedsince header.

<?php
use com\zoho\api\authenticator\OAuthBuilder;
use com\zoho\crm\api\dc\USDataCenter;
use com\zoho\crm\api\InitializeBuilder;
use com\zoho\crm\api\UserSignature;
use com\zoho\crm\api\record\RecordOperations;
use com\zoho\crm\api\record\GetRecordsHeader;
use com\zoho\crm\api\HeaderMap;
use com\zoho\crm\api\ParameterMap;
require_once "vendor/autoload.php";

class Record
{
    public static function initialize()
    {
        $user = new UserSignature('myname@mydomain.com');
        $environment = USDataCenter::PRODUCTION();
        $token = (new OAuthBuilder())
        ->clientId("1000.xxxxxxx")
        ->clientSecret("4b5baxxxxxxxxxxxxf")
        ->grantToken("1000.xxxxx")
        ->build();
        (new InitializeBuilder())
            ->user($user)
            ->environment($environment)
            ->token($token)
            ->initialize();
    }

    public static function getRecords()
    {
        $recordOperations = new RecordOperations();
        $paramInstance = new ParameterMap();
        $headerInstance = new HeaderMap();
     $ifmodifiedsince = date_create("2022-06-01T12:00:00+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()));
        $headerInstance->add(GetRecordsHeader::IfModifiedSince(), $ifmodifiedsince);
        $response = $recordOperations->getRecords("Leads", $paramInstance, $headerInstance);
        echo($response->getStatusCode() . "\n");
        print_r($response);
    }
}
Record::initialize();
Record::getRecords();


Next week, we will dive deeper and provide more sample codes to help you further. Stay tuned!

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



    • Recent Topics

    • :between: conditions in search?criteria

      Hello, please help solve problem I try to select deals by Creater_Time between dates i send this GET request /crm/v4/deals/search?criteria=(Created_Time:between:(2024-02-01T18:52:56,24-02-17T18:52:56)) encoded to /crm/v4/deals/search?criteria=%28Created_Time%3Abetween%3A%282024-02-01T18%3A52%3A56%2C24-02-17T18%3A52%3A56%29%29

    • Zoho Creator : Updating Records via Import. Can't use Autonumber or ZohoRecordID ?

      Hi, I am trying to use the function to update a report with an import. I'm running in to the error : "unable to update because the form has no column with unique values" In the release notes it says Only field with unique values can be used to compare

    • 💡 Feature Request: Custom App Bundle Plan (Pick Only the Apps You Need)

      Request: Allow Users to Build a Custom App Bundle (Choose Only the Apps They Need) Hi Zoho Team, I appreciate the value that Zoho One and the Plus Bundles (CRM Plus, Finance Plus, etc.) offer. However, I’m finding it difficult to get the best fit for

    • Search Feature Now Broken

      I have many hundreds of notes on Zoho Notebook but now when I search for a keyword, I only get 30 results maximum. This is unacceptable and yet another feature that has become broken on this quickly deteriorating software. Please fix immediately.

    • Restrict Zoho One Account Notifications to Admins

      Hi Zoho One Team, I hope you're doing well. We recently noticed that end users are receiving administrative pop-ups in Zoho One, such as the DKIM configuration notice (screenshot attached). This type of notification is only relevant to administrators

    • Automated Checkout

      Hi Team, I’m trying to create an automated checkout function in Zoho People. My requirement is that if an employee forgets to check out, the system should automatically check them out after 10 hours. However, I'm encountering an error while updating the

    • Zoho CRM Community Digest - June 2025 | Part 1

      **We offer both video and written formats, take your pick and jump in.** CRM FOMO is real. You could be doing everything right and still miss the beat. That’s where we come in. Zoho CRM Community Digest! Every two weeks, we bring you the insider scoop

    • Introducing Video Tutorials for the Zoho FSM Mobile App

      We’re excited to announce the launch of our brand-new video tutorials for the Zoho FSM Mobile App—designed painstakingly to help your field agents get up to speed in no time! Whether you're brand new to the Zoho FSM mobile app or just need a quick refresher,

    • Zoho People > Managed People > User Access Control

      Hello All I need your recommendation on how should i go about setting the User Access Control in my Zoho People

    • What happened to the tabs in the ribbon on the top in my CRM?

      Hi, This morning all of the tabs (modules) in the ribbon on top are no longer showing up. I had the modules in the ribbon in a specific order for easy, one-click access. Now it's only showing the active tab and the rest are hiding under the three dots

    • Connect to Australian bank

      How do I connect to an Australian bank. No Australian bank shows up in my list. I think its because the service provider is Token and not Yodlee. How do I change this?

    • Searching for content within courses

      Hello, I have been testing out Zoho One for my company have been exploring Learn. I've noticed that you cannot search for content within a course. You can only locate the title of the course. Example: Course: How to Make Your Bed Chapter: Pillows Lesson:

    • Citations Problem

      I'm having an odd problem with the "Add Citations" feature of Zoho Writer. When I add a citation using the "Fetch website details online" feature it works the first time I use it but if I try it a second time by clicking that link nothing at all happens

    • Zoho People Leave Balance Show as Negative

      Hi All I have the Portugal material Leave that policy allows up to 120 days or 150days for employee to apply within 365 days and employees is able to take minimum of 1 days or up to 120 days In my Leave Grant I have set as the setting.

    • Zoho People > Performance > Appraisal > Mismatch between the template-configured module and the currently enabled module.

      Hello There When we enable the performance module there a prompt Mismatch between the template-configured module and the currently enabled module. How do we resolve this

    • Introducing WhatsApp integration in Bigin

      Greetings! In today's business landscape, messaging apps play a significant role in customer operations. Customers can engage with businesses, seek support, ask questions, receive personalized recommendations, read reviews, and even make purchases—all

    • Zoho People Leave Application Module Error: Leave balance has exceeded as on 09-07-2025.

      Dear All I need to check how do i resolve the issue of Error: Leave balance has exceeded as on 09-07-2025. All my leave have this issue

    • Power of Automation:: Daily Time log summary broadcast to Zoho Cliq using Schedule Custom Functions

      Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:

    • When Calls Ends, Creating Note with the call description by deluge code

      Hi, i need help with writing deluge code function, to scenario is like this - i want to create a workflow thats after 10 that the call ends the deluge function will create a new note in module calls that link the note in module calls to the his lead ticket

    • Default Memo from Custom Field (from Bill) when Paying with Check

      Hi, we are using "Pay via Check" option to pay for our Bills in Zoho Books. I would like the memo on the check to pull directly from one of the custom field values within the Bill. Is there any way I can do this? The memo that I need is already on the

    • Wouldn't it be great to have an option to schedule sending emails in Zoho mail? Schedule send feature request

      The subject says it all - but just to clarify: This is to request a new feature that would allow users to schedule the delivery of an email for a given date & time. In small companies it is quite common to work unsocial hours on customer emails. But some

    • Static vs Standard Subforms - New Feature; But how does it work?

      I've just noticed that we now have the option of static or standard subforms, but I can't find any posts on the new feature. So, how does the new subform type work?

    • 【Zoho CRM】翻訳機能のアップデート

      ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中から、翻訳機能のアップデートをご紹介します。 翻訳機能が拡張され、Webタブ、レイアウト、セクション、ウィザード、ウィザード画面、セグメントも翻訳できるようになりました。 翻訳をエクスポートする際に、これらの要素に対応する用語もエクスポート先の言語で追加されます。 ※過去の関連記事はこちらから まず、翻訳の設定画面から「エクスポート」を選択してください。すると、TXT形式のファイルがローカル環境に出力されます。

    • Trying to make zoho invoice have a button

      Hello I am getting this error with the code below. Anyone know how to fix? Check and update the code in line 5 as there is a Exception : Variable 'invoice_id' is not defined // Define Organization ID (Replace with your actual Zoho Invoice organization

    • Duplicate Contacts - how to get merge or delete

      I have noticed that our list of contacts in Zoho Desk duplicates contacts periodically. I have yet to identify when or why. How do I merge or delete them? I see there is a "Deduplicate" but I am unable to find anything that explains this feature.

    • Another nightmare experience with a "Zoho Partner": Cloud Z Technologies

      I found "CloudZTech" on fiverr and I hired them to do a simple $300-$500 task. They did not deliver on time and I was forced to fire them. You guys must watch out for these fake ZOHO PARTNERS, 99% of them don't have the expertise necessary to help. I

    • Pickup and delivery

      Some of our products are pickup only and some delivery. Is there a way of doing this in commerce. Plus we give volume discount to all customers. We handle this in Books using pricelist and range pricing. Is there a way of doing this within commerce.

    • Unable to change the "credentials of login user" option when creating a connection

      I want to create a new Desk connection where the parameter to use 'credentials of login user' is set to YES. I'm able to create a new connection but am never given the option to change this parameter. Is this a restriction of my user profile, and if so,

    • How can you train the Zia Bot for Desk

      I added the Zia bot to my portal, but it's rarely able to answer questions, even when I have dedicated articles for the question.  How can I best train it? Should I change the title of my articles, add more information inthe body copy?

    • Direct Download Link

      I saw how to share off a document to the public, which is great, but I was also wondering if there is a way to get a direct download link for a zoho doc. I would like to be able to simply send people my documents without them having to find download on the zoho page (not hard, but just for convenience)

    • Form responses to quote process

      Hello, so I am new to Zoho One. I'm fairly confident what I want to do can be done I just need guidance on how to accomplish it. I have a Zoho Form. When a customer fills out the form I want to generate a quote (that I will email to them, I do NOT want

    • i keep see there is a connetion issue connecting 3rd party api on zoho when using zia

      hi there , i have set up open ai api to zoho zia (copied and pasted to zoho zia) but I keep getting notificaiton "there is a connetion issue connecting 3rd party api on zoho" when using zia on top when click zia and try to type in word there

    • IPv6 MX Support in 2025

      There are multiple discussion on this community on IPv6 adjacent issues though the most pressing issue for IPv6 support is not solved yet the support team seems to not understand what is the issue and is steering the conversation to the wrong and misleading

    • Zoho Books Quote - Client cannot accept quote

      We are using the Zoho One plan and some of our clients have reported that they cannot accept the quote when we select their email at the bottom to send the quote to. When trying to accept, the quote prompts a message saying "You are not allowed to accept

    • Reckon Accounts Hosted to Zoho Finance

      Hi Everyone I want to transition from Reckon Accounts Hosted to Zoho Finance, as I have numerous other tasks in Zoho One, and it seems logical to make the move. (Reckon has a QuickBooks back end & is hosted on Assure now, think) I would really like to

    • Flex Your Creativity – A New component to Canvas in Zoho CRM

      Hello Everyone We’re excited to introduce Flex, a new component for Canvas in Zoho CRM! Flex is here to give you greater control over how your data is displayed in your layouts. This component enables responsive layouts that adapt across different screen

    • Vendor Assignment issue for staff in User Roales

      there is a limitation in software that we can't assing Vendors to our staff - we can only assign Customers on staff wise!! There is a limitation of this software that in case i want to assign limited vendors to my staff - it's not possible. Either i will

    • Zoho Desk Community Portal Not Displaying Custom Styling Correctly

      Hi Zoho Community, I’m struggling to get a custom community portal in Zoho Desk to display my branding and styling correctly, and I’d love some help troubleshooting this for a client’s support portal. Details: Setup: Zoho Desk (Professional plan, latest

    • Remove or hide default views

      I'm looking to only have the views pertinent to my organization. Is there a way to show only my custom views (or separate them to a different area or something)? If not, this should be a feature as switching from Zendesk we had this option...

    • Wie kann ich einen Nutzer löschen?

      Wir haben Zoho one. Es handelt sich um einen ehemaligen Mitarbeiter.

    • Next Page