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

    • Chatbot for Urdu language

      Hello, I have successfully set up Zoho Desk and integrated it with Moodle using ASAP. I am now looking for a chatbot that supports the Urdu language to enhance student support. My goal is to enable the chatbot within ASAP so that students can ask questions,

    • Multi Level Hierarchical Query

      Hi guys I have a situation where i am trying to extract the descendants of a particular entry. So long story short, i have the Account table with Agency (A) id = 1, and that has child Agency (B) id = 2. This child agency (B) has a child agency (C) id

    • AI-Powered Grouping and Tagging of Related Issues and Tasks in Zoho Projects

      Dear Zoho Projects Team, Greetings, We would like to suggest a feature that would greatly enhance how we manage feature requests and bug reports submitted through the Zoho Desk to Zoho Projects integration. Use Case: Our support agents handle customer

    • How to change side bar from dark mode to light mode?

      The side bar on the left side in workdrive doesn't appear to have a way to fix it from dark mode - is there a way to? I can't read in dark mode without excessive headaches, and I would really like to be able to see while I have workdrive open, as workdrive

    • How to see history on Bulk send of Customer Statements

      Hi, We bulk send statements to customers every month via Books - every month we have customers emailing requesting a statement. Currently I have no visibility on if a customer was sent the statement or not and if our process is being followed or overlooked

    • Guided Conversations - Ticket Creation

      Hi there, Using Guided Conversations to Take Customer Data and apply it into a Support Ticket for internal use, Is there a way to take multiple Textual Variables Inputs (A series of questions), and have the answers all appear in the Description of the

    • How to add buttons elements in the Header

      I am trying to add CTA (Call to Action) buttons in the right side of the main navigation menu. This is a common practice for sites but I can't seem to figure this out for Zoho Sites. Is there a custom workflow that could be shared with me? 

    • Automatic back up - Zoho Recruit, books, people,crm, analytics

      Hello, Has anyone found a good way of automatically backing up Zoho (CRM, expense, recruit, people, books, analytics).? I have found with tool that does, but it doesn't include recruit or analytics It's a bit annoying and time consuming having to go to

    • delete departments on zoho desk

      I created test departments on zoho desk. how can i delete them now?

    • Validation, checking if a file has been attached to the ticket

      A very useful option would be to allow checking, under specific conditions, whether the user has attached a file to the application, e.g., a bug report. Some applications require files to be attached, and the system could enforce this after the system

    • AI & Zoho Recruit

      Hello, I guess we all are using AI in our personal and professional lives. Now, let's imagine. Recruitment is just a succession of stages and steps. For which step would you like to see AI implemented into Zoho Recruit ? I'll start : - Automatic translation

    • Zoho Flow not handling Boolean properly

      Hi, I have a checkbox in one system that I'm trying to sync with a checkbox in Zoho CRM. The value from the source system comes in as blank (unticked) or 1 (ticked). I've written the following custom function to convert the output to either boolean false

    • Quotes Module - import data

      Hello Zoho, is it possible to import Quotes records? I was trying and i have no results. Raport shows no data imported. Could you help me please how to do it?

    • Balance Sheet - Zoho Analytics

      Hi Team, I’m looking to implement a feature that captures the conversion rate based on the filters applied. By default, it should fetch the most recent conversion rate, and when a filter (such as a timeline filter) is applied, it should return the conversion

    • files sent will not open for recipient

      work files (done in writer) which previously opened will not open for the recipient

    • How to Print the Data Model Zoho CRM

      I have created the data model in Zoho CRM and I want the ability to Print this. How do we do this please? I want the diagram exported to a PDF. There doesnt appear to be an option to do this. Thanks Andrew

    • Cisco Webex Calling Intergration

      Hi Guys, Our organisation is looking at a move from Salesforce to Zoho. We have found there is no support for Cisco Webex Calling however? Is there a way to enable this or are there any apps which can provide this? Thanks!

    • Migration of Mails from Pipedrive

      Hi, so far the migration from Pipedrive to ZOHO works pretty good. For full completeness of the migration we miss all the mails linked to Deals, Contacts, Customers, ... What possibilities do we have to have Pipedrive fully migrated to ZOHO? Best Regards,

    • Published sheets don't work anymore

      Hi, Published sheets don't work anymore. The display of values is very very slow and calculations are not displayed at all. Thanks!

    • WorkDrive TrueSync for macOS 26 (Tahoe) Beta

      Hello everyone, With Apple unveiling the macOS 26 (Tahoe) Beta, we know many of you are eager to explore the latest features and enhancements. We’re excited to support your enthusiasm! As part of our commitment to delivering seamless cross-platform experiences,

    • Limited layout rules in a module

      There is a limit of 10 layout rules per module. Is there a way to get that functionality through different customization or workflow + custom function (easily accessible), etc. Having just 10 is limiting especially if module contains a lot of data. Are

    • #1 Zoho Billing vs. Zoho Books: Which one should I choose?

      Managing your business finances isn't just about sending invoices. It's about keeping everything organized, accurate, and moving towards your organization's goals. At Zoho, we understand the complexity, which is why we offer two powerful yet distinct

    • Is Zoho tables still being developed?

      Has this product been abandoned? I haven't seen any useful new features or stability improvements over the past six months or more. I think Tables is a great concept, filling a niche between spreadsheets and full database tools, but the current implementation

    • How to connect oracle ADW with Analytics

      I want to add Oracle ADW as a data source in Zoho Analytics, but I couldn't find any relevant documentation. Can anyone suggest how to do it, or let me know if it's even possible? Thanks!!

    • RAG (Retrieval Augmented Generation) Type Q+A Environment with Zoho Learn

      Hi All, Given the ability of Zoho Learn to function as a knowledge base / document repository type solution and given the rapid advancements that Zoho is making with Zia LLM, agentic capabilities etc. (not to mention the rapid progress in the broader

    • add attachments to automated emails?

      Hi, I'm looking for a way to have documents saved under an account, be grabbed and sent to an email address once a specific status has been updated.  For example we have a tab we've labeled as sales orders, when the status is changed to shipped, it emails the customer the tracking number and estimated delivery date.  I'd like it to also grab pdf docs (COA, BOL, etc) from that order and send in that email.   Currently we have to go into zoho change the status to shipped, then email all the docs to

    • [Action Required] Zendesk - Zoho Analytics integration requires re-authentication

      Dear Zendesk integration users, Zendesk is transitioning to a new OAuth model that uses refresh tokens for improved security and stability (read more). As a result, all Zendesk users in Zoho Analytics must re-authenticate their Zendesk connections on

    • Rerun Migration?

      I migrated a mailbox a few days ago, but didn't do the cutover on the MX records until today.  How can I rerun the migration to sync the mailboxes?  The old account has had a fair amount of activity since the first migration. I am used to other systems

    • طلب حذف الدومين والمؤسسة من حساب zoho

      السلام عليكم، أود طلب حذف الدومين التالي من حسابي في Zoho، حيث لا يظهر لي خيار الحذف في لوحة التحكم: اسم الدومين: hudajstore.com البريد المرتبط: [contact@hudajstore.com] علمًا بأنني المسؤول عن المؤسسة، ولا أستخدم الدومين حاليًا، وأرغب في إلغاء ربطه وحذف

    • Microsoft Outlook Add-in Update: Enhancing Efficiency for Recruiters

      We've released an update to the Zoho Recruit Microsoft Outlook Add-in, which brings a host of features designed to streamline your recruiting process and boost productivity. Let's delve into the details: Associate Emails with records in Zoho Recruit You

    • New integration: Zoho Books + Zoho Forms

      Hello Zoho Forms community! We are thrilled to announce the addition of another integration that brings speed and efficiency to your financial workflows. Zoho Forms can now be integrated with Zoho Books! Here’s a quick rundown on Zoho Books! For anyone

    • Witness Sign - Automation with Zoho Creator

      Hi there, I used to be able do automatically send a Zoho Sign document from Zoho Creator where each signer had one witness. The action code was as follows for each signer and witness:       // CLIENT eachActionMap1 = Map(); eachActionMap1.put("signing_order","1");

    • Announcing: custom color palette + free workshop

      Hello everyone, We're excited to share new feature in Zoho Bookings—a color palette within booking page themes. You'll find this option under Manage Bookings > Workspaces > Booking Page Themes. You can customize the color of every element in your booking page and even alter the transparency of your background image. Please note that this is a paid feature included in the Basic and Premium plans. At the moment, it's available only under the Modern Web theme. This means you can create billions (7,

    • Removing To or CC Addresses from Desk Ticket

      I was hoping i could find a way to remove unnecessary email addresses from tickets submitted via email. For example, a customer may email the support address AND others who are in the helpdesk notification group, in either the TO or CC address. This results

    • Ability to Export Field Dependency Structure in Zoho Desk

      Hi Zoho Team, We’d like to request a feature enhancement in Zoho Desk that would greatly improve configuration management for organizations like ours: Requested Feature: The ability to export the full structure of Field Dependencies, especially for multi-level

    • [URGENT] Allow reorder (drag&drop) of subform record

      Very simple user case: a wedding planning app where you want to send your client a form to fill with information about their wedding. Form includes some field for general purpose information and a subform for event pacing/schedule. Clients are invited to create a new row (When? - What? - Where? - Who?) for each thing happening during their wedding chronologically. Ex: When                  What 10h                      Something TBD                    Speech After speech      Yet another thing happening

    • Departments in Zoho

      I'm trying to set up a department. It looks like Departments have been removed from Zoho One. Is there another option? We have our main account setup, but want to set up a separate small department that can't see our tabs.

    • Add Timer for Agent Status Duration in Zoho Desk Dashboard

      Hello Zoho Desk Team, We hope you're doing well. We would like to submit a feature request to further enhance the agent status tracking functionality within the Zoho Desk Dashboard. 🎯 Current Functionality As it stands, Zoho Desk allows us to view the

    • [Beta Feature] Parent-Child Ticketing

      Hello there, a beta parent-child ticketing feature has recently been made available for some, read more here: https://help.zoho.com/portal/en/kb/desk/ticket-management/articles/understanding-parent-child-ticketing-system#Business_scenarios I would like

    • Enable Sorting by Ticket Count in Category Reports

      Hi Zoho Desk Product Team, I hope you're doing well. We would like to submit a feature request to improve the reporting capabilities in Zoho Desk. 🎯 Feature Request: Sorting by Ticket Count in Category Reports Currently, category-based reports in Zoho

    • Next Page