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

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

    • Function #46: Auto generate list of lapsed customers using Custom Button

      Hello everyone, and welcome back to our series! Customer retention is one of the key factors that impact the long-term success and sustainability of a business. High customer retention rates indicate satisfied customers, quality products or services,

    • Before Going To The Qc stage , site ready ness file upload mandtoty how to achive this in the blue print transition

      Before Going To The Qc stage , site ready ness file upload mandtoty how to achive this in the blue print transition Is it possible on click of the predelivery Transition show the alert message if site ready ness file upload empty also not move the stage

    • Announcing new features in Trident for Windows (v.1.28.5.0)

      Hello Community, Trident for Windows is here with exciting new features to help you stay productive and make collaboration simpler. Let’s dive into what’s new! Slash commands are now supported in the Cliq module. You can now use slash commands from the

    • Convert time to string and remove second

      Hello everyone, I have a question that I can't figure out on my own. How to convert time into string (singleline) and remove second. Like HH:mm. If I convert it as below, the result becomes null. Thank you very much. input.Time.tostring("HH:mm") result:

    • Has anyone imported items and included the storage bin?

      We have a large amount of Inventory Items. We would like to import these into Zoho Inventory but while we can import the majority of data, the storage bin refuses to map. Has anyone successfully imported the data and mapped the bin?

    • Terms & Conditions add a rule.

      Hi I'd like to format my T&C's to auto format a Deposit amount based on the Total. "Quotation is valid for 7 days from the date of issue. A 75% deposit ( R .00 )is required to confirm the booking. The remaining balance ( R .00)is due upon project completion.

    • Zoho Inventory Feature Roadmap Visible To All

      Hello, please consider making your feature roadmap visible to us users so that we know what to expect in future. This may appease current users who are seeking clarification on feature implementation dates, so that they can make an informed decision whether

    • send file to ftp or another external service

      i'v created a zoho creator application for take a picture and rename it by phone. Now i need to send Each renamed pictures to my ftp or to specific folder on google drive...then, delete it from creator. (every picture recived it will processed by another program and stored on my Erp) HOW CAN I DO ??

    • Feature Request - Improved booking layouts, specifically for individual booking links

      I would like to see more layout options and specifically to have the meeting description beside the calendar booking function, when sharing booking links to specific consultations/meetings. Below is a screenshot from Calendly. I love this layout and it

    • Set Conditional and Dependent Rules for Issues in Zoho Projects

      An Issue Layout is a customizable form to add and update information about a specific issue. The fields in the issue layout can be changed dynamically based on user requirement using the issue layout rules. Consider a scenario where an electrical fluctuation

    • Accounting on the Go Series-56: e-Way Bill Module in the Mobile App – A Handy Solution for Indian Businesses

      Hello everyone, Managing e-Way bills just got more convenient with the Zoho Books mobile app! For businesses operating under the GST regime, e-Way bills are essential for tracking the movement of goods. Previously, you had to log in to the web app to

    • Copying records from a Custom Module into Deals

      Hello, I recently created a custom module to handle a particular type of order/transaction in our business. Having got this up and running I've realised that it would be much better to use the Deals module with a different layout instead. We've entered

    • Creator App on Mobile - Workflow "On Create / Edit - On Load" not triggered ?

      Hi Everyone, I built an application to track assets, which is used both at the office (desktop) an in the field by technicians (mobile app). In the field, technicians open an existing form and add rows to a subform at some point. One field they have to

    • HOW TO VIEW INDIVIDUAL COST OF NEWLY PURCHASED GOODS AFTER ALLOCATING LANDED COSTS

      Hello, I have been able to allocate landed costs to the purchase cost of the new products. however, what i need to see now is the actual cost price (original cost plus landed cost), of only my newly purchased products to enable me set a selling price

    • Custom Function to get custom field of lookup type in Books

      Hi, Here's the situation. In Purchase Order, there is a custom field (lookup) to SO. The requirement is to update to the related SO if PO get updated Right now facing challenge to get the id of custom field (lookup) in PO. Please find below the sample

    • Custom From Address is now Organizational Email

      We're introducing a small yet meaningful change in Zoho Recruit, one that sets the foundation for bigger improvements coming your way. What’s changed? We’ve renamed the Custom From Address to Organizational Email. The new name was chosen to better reflect

    • What's New in Zoho Billing Q2 2025

      Hello everyone, We are excited to share the latest set of updates and enhancements made to Zoho Billing in Q2 2025, ranging from image custom fields to support for new languages. Keep reading to learn more. Upload Images From Your Desktop to Email Notifications

    • Map dependency on Multiselect picklist

      I need help in Zoho CRM. I have 2 multi-select picklists. For example, Picklist A has country names. Picklist B has state names. Now I want to show states on the basis of the selected country from Picklist A. Both are multi-select fields, so the standard

    • Tip of the Week #63 – Keep personal emails out of team view.

      Shared inboxes are great for teamwork—they let everyone stay on the same page, respond faster, and avoid duplicate replies. But not every message needs to be shared with the entire team. Think about those one-on-one chats with a manager, a quick internal

    • Episode III : Powering Automation: Custom Functions in Action

      Hello Everyone, In our previous episodes, we explored custom functions and the Deluge programming language. If you’ve been wondering why the Episode series have been quiet, here’s the reveal! On our community, we've been showcasing custom functions integrated

    • Narrative 2 - Understanding Organizational Departments

      Behind the scenes of a successful ticketing system - BTS Series Narrative 2 - Understanding Organizational Departments A ticketing system's departments are essential because they provide an organized and practical framework for handling and addressing

    • Zoho Projects Plus for the healthcare industry

      The global healthcare industry is complex and diverse; from patient record maintenance, healthcare supply chain, to manufacturing complex medical equipment, the industry functions on many layers. Managing all these layers requires tested out techniques

    • Missing Outlook calendar option in Calendar

      Hi all I don't have an Outlook Calendar option in the Settings > Synchronise settings of Calendar. Any ideas why not?

    • Zoho Meeting Android app update: Breakout rooms, noise cancellation

      Hello everyone! In the latest version(v2.6.1) of the Zoho Meeting app update, we have brought in support for the following features: 1. Join Breakout rooms. 2. Noise cancellation Join Breakout rooms. Breakout Rooms are virtual rooms created within a meeting

    • Whats App Automation

      It would be nice to be able to send out an automated whats app message template on moving stages or creation of a ticket (same as you can do for automated emails). Currently only automated emails can be sent. Also, if whats app could be used more effectively

    • Zoho Projects Android app update: Enhanced Documents module within the projects.

      Hello everyone! In the latest Android version(v3.9.35) of the Zoho Projects app update, we have enhanced the documents module within the projects. Now, you can view all the attachments that you have added across the project in tasks, bugs, comments, etc,

    • Lead Source Disappears

      When adding a new lead and saving the page, the page refreshes itself and the lead source field becomes blank. We set the "Lead source" as a required field to see if it would help, but the problem persists and we always have to re-enter the lead sou

    • Inquiry Regarding Monitoring ZOHO CRM API Credit Usage

      Hello ZOHO Community, I hope this message finds you well. I have a question regarding monitoring the usage and remaining credits of the ZOHO CRM API. I recently discovered that within ZOHO CRM, by navigating to Settings ⇒ Developer Hub ⇒ APIs & SDKs,

    • Payment Gateways - A unified hub to manage all your payment integrations in Zoho Creator

      Hello everyone, We're thrilled to announce that we've completely reimagined the way payment gateways are handled in Creator. The result is a centralized Payment Gateways section that provides a clean, user-friendly interface to configure and manage all

    • Community Digest Julio 2025 - Todas las novedades en Español Zoho Community

      ¡Hola, Español Zoho Community! Ha pasado un tiempo desde el último Digest pero, ¡ya estamos de vuelta con las novedades más relevantes en las aplicaciones de Zoho y su universo! Si no te quieres perder ninguna de las novedades que vamos publicando, te

    • Tip #35- How to use Notifications in Zoho Assist to stay on top of session activities- 'Insider Insights'

      Hello Zoho Assist Community! This week, we’re exploring Zoho Assist’s built-in notification system for improved visibility and accountability. Keeping track of session activity is crucial, especially when you're managing multiple remote devices and technicians.

    • Assistance with Exporting Specific Data from Zoho CRM

      Hi, Could you please guide me on how to export specific information, such as the model number and serial number, from the Accounts module in Zoho CRM? Thank you in advance for your assistance.

    • Coming Soon in Zoho Invoice: Send Invoices Instantly via WhatsApp

      We're working on bringing a new level of convenience to your invoicing experience. Introducing a much-requested feature in Zoho Invoice: You can now share invoices directly to your customers via WhatsApp! With this new option, you can: Share invoices

    • field update from the value of another field

      Hello, I need to do a field update from the value of another field, but i don´t know how can i do it. In the mass update option it is not possible... I need to put the last name value form the leads module to other custom field that i have created. thanks for your help

    • What is a realistic turnaround time for account review for ZeptoMail?

      On signing up it said 2-3 business days. I am on business-day 6 and have had zero contact of any kind. No follow-up questions, no approval or decline. Attempts to "leave a message" or use the "Contact Us" form have just vanished without a trace. It still

    • Playback and Management Enhancements for Zoho Quartz Recordings

      Hello Zoho Team, We hope you're all doing well. We would like to submit a feature request related to Zoho Quartz, the tool used to record and share browser sessions with Zoho Support. 🎯 Current Functionality As of now, Zoho Quartz allows users to record

    • Next Page