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

    • Emails not being received from a particular domain

      Cannot receive any emails sent from atco.com Domain is in the spam whitelist so should be no reason for it not to be coming through. Have filed a ticket and besides a generic response of we are looking at it - it seems there is no actual support workers

    • Mail Not Showing In Inbox or Sent Box

      Hi, there are mails that are not displaying in both my inbox and sent box. I just tried the iPad app and it is the same but there is a blank field where a mail should be and it refers to a server error. Please fix this.

    • Marketing Automation List Entry Criteria is no longer an option

      For a couple of years now we have used the "List Entry Criteria" option to filter our Journey recipient list. All of a suddent the option no longer exists for New Lists and I can only delete the option from existing lists but can no longer edit it. Anyone

    • GCLID arrives not in CRM with iframe integrated ZOHO Form

      Hello amazing community, I enabled Adwords integration in ZOHO CRM. I have a ZOHO Form integrated in a wordpress. I tested iframe and Javascript. I enabled the "handover" GCLID in the ZOHO Form. When I add a GLID with http://www.example.com/?gclid=TeSter-123.

    • Add Webhook Response Module to Zoho Flow

      Hi Zoho Flow Team, We’d like to request a Webhook Response capability for Zoho Flow that can return a dynamic, computed reply to the original webhook caller after / during the flow runs. What exists today Zoho Flow’s webhook trigger can send custom acknowledgements

    • Bidirectional sync between Zoho Bookings and Zoho CRM - Part 1

      Hey, community members! The default integration between Zoho CRM and Zoho Bookings is unidirectional, which means that any appointments booked, rescheduled, or deleted in Zoho Bookings will be reflected in Zoho CRM. However, any modifications made to

    • Is it possible to edit placeholder text?

      In the master slides I want to make sure my templates have more meaning for the users and want to replace the standard placeholder text with something more instructional. Instead of "Click to edit Mast subtitle styles" I want to have "Click to enter reporting

    • Delay function execute

      I've got a workflow which uses a webhook to send information to Flow, which in return updates a record in Creator. Problem is, by the time this has executed, the rest of my script has run and can't find the (yet to be) updated info in the record. Is there

    • How to allow download of a file AFTER information is collected?

      I can't find this anywhere. Can someone help with what seems to be a pretty basic web function today? - File is stored in Workdrive - Prospect goes to a URL where the file is located - System requests prospect to enter "Name" and "Email" - An email is

    • Add Baseline methods to API

      There are no API methods for creating or querying baselines,  Use case: Customer is notified of the current project start date according to plan via another product/integration. We would like to auto create a baseline (Automated via API) at the point

    • Bulk Fill In & Edit PO/Bill/SO/Invoice

      Hello, I am adding stock in bulk on a PO, the system is automatically populating the Rate (price) and Tax from the item data. Problem is that the bill rate is different from the rate on the item data, so I have to manually erase each and enter the price.

    • Fixed Assets beg balance

      Hello, I trust you are well I'm a new zoho books user and I find it difficult to plug in the fixed assets balance and here's what I have done: 1- I imported the fixed assets data into the fixed assets module as per the instructions 2- the import process

    • Syncing with Google calendar, Tasks and Events

      Is it possible to sync Zoho CRM calendar, task and events with Google Calendar's tasks and events. With the increasing adoption by many major tool suppliers to sync seamlessly with Google's offerings (for instance I use the excellent Any.do task planning

    • CRM Deluge how can link attach file with workdrive file.

      Hi, We have create file at workdrive and would like to link to attachment at crm module by deluge. Right now can only upload it to attachment but can not link the file from workdrive. Thank you

    • Feature announcement: AI-powered document generator in Zoho Sign

      Hi there! We recently announced manual document creation by offering an editor within Zoho Sign. Today, we are excited to announce AI-powered document generation to help you draft agreements, purchase orders, and other important business documents in

    • Permanently deleted files

      Is there a way to get back permanently deleted files from your account if they were accidentally deleted and no longer recoverable from the recycling bin? I know I am probably screwed but I just figured I would ask.

    • Shared Mailbox in iOS app

      Hi, On the desktop I am using a Shared mailbox for our company's general mailbox that somebody else should be able to view. In the iOS app however I can't find it? Old sources on the internet says this isn't possible but that can't be right? Somebody

    • Tip #41- Simplify Compliance and Efficiency with Zoho Assist’s Data Cleanup Feature- 'Insider Insights'

      Managing device data efficiently is just as important as securing remote access. With Zoho Assist’s Data Cleanup feature, admins can easily remove outdated or unnecessary device records, keeping the console organized and secure. This action is carried

    • Revenue Management: #6 Revenue Recognition in Professional Services Industry

      If you run a consulting firm, agency, or any service-based business, you have a situation where you have signed the contract, maybe even sent the invoice, and have received some initial payments. So, can you consider this as revenue? What if the project

    • Zoho fsm scheduled maintenance dispatch

      Hi, I'm reaching out regarding an issue I'm encountering with the Scheduled Maintenance feature in Zoho FSM. I’m trying to configure it so that it automatically dispatches all maintenance jobs scheduled within the next 150 days, starting from today. However,

    • zoho.inventory.getRecords returns no records

      I running a custom function (Deluge) in Zoho Flow with a connection to Zoho Inventory. To debug the problem, I created the test function below. It returns "Number of contacts fetched: 0". This confirms that there's no issue with the org ID or connection

    • Zoho Campaigns Event timestamps do not propagate to Zoho CRM

      We have integrated Zoho CRM and Zoho Campaigns. But when looking at Contact records, the Campaign event data is missing the actual timestamps: especially when a particular email was sent. They're not in the Campaigns related list, and the cannot be found

    • Feature announcement - Simplifying document creation with Zoho Sign

      Hi there, We are pleased to announce the release of our document creation feature, enabling you to create, edit, and finalize documents like agreements, purchase orders, and contracts without relying on external tools or applications. &lt;br&gt; This

    • Integrating File Attachments in Zoho Flow Email Notifications

      Hi, I would like to be able to send an email once an entry is made in a form, and in this email, I would like to attach a file that has been added to the form using the ImageUpload (or FileUpload) widget. So, I started by creating a flow that will trigger

    • Zoho project purchases

      Hi Folks, I think having a purchase module in projects will help in putting together a project p and L. Project wise purchases and expenses.  Do let me know your thoughts.

    • Create Tasklist with Tasklist Template using API v3

      In the old API, we could mention the parameter 'task_template_id' when creating a tasklist via API to apply a tasklist template: https://www.zoho.com/projects/help/rest-api/tasklists-api.html#create-tasklist In API v3 there does not seem to be a way to

    • How can I restore all the deleted Time entries of a Task in Zoho Projects

      How can I restore all the deleted Time entries of a Task in Zoho Projects? Query: In Zoho Projects, I cloned a task and deleted the time entries from the cloned task. However, this also deleted the time entries from the original task. How can I restore

    • Is there a way to make an account inactive in ZoHo Desk

      We have a few Clients "Accounts" that we no longer do business with. It would be beneficial for them to not show up in lists. However, we want to go back and view tickets, time, etc.

    • How to set the value of the Phone field importing contacts in Zoho Desk

      Hi everyone, i'm new in Zoho Desk, we're setting up the environment and i'm importing contacts from another CRM using a file CSV and i'm getting a problem with phone numbers (italian): the leading zero is cut away, also if the value is inside double quotes.

    • Set Custom Icon for Custom Modules in new Zoho CRM UI

    • Deprecation Notice: OpenAI Assistants API will be shut down on August 26, 2026

      I recieved this email from openAI what does it means for us that are using the integration and what should we do? Earlier this year, we shared our plan to deprecate the Assistants API once the Responses API reached feature parity. With the launch of Conversations,

    • How to center a field inside a section?

      I’ve been trying to center a field inside a section in Zoho Canvas. When I align it visually, it looks centered in the editor, but after clicking Save, the field appears misaligned on the actual canvas. I also tried setting the field to full width, but

    • Kaizen #192 - Implementing Custom Token Persistence in Python SDK

      Welcome back to another week of Kaizen! Last week, we discussed how to implement Login with Zoho using OAuth 2.0 and saw how to bring it to life in a real-world application with the Zoho CRM Python SDK. We also discussed how Zylker Academy built a custom

    • Showing the map along with mileage expense

      When you use the GPS to track mileage, it shows you the map of the actual path travelled. It would be very useful and practical to save that map with the mileage expense, so that when the report is created, it provides a map of each mileage expense associated

    • Enable Validation Rule for Multi-Select Picklist Field

      Zoho, Please allow validation rules for multi-select fields.

    • File Upload field not showing in workflow

      Hi, I have added a field on Zoho CRM. I want to use it in a workflow where that particular field is updated based on another field, however it is not showing up in the field list to select it in the workflow. Why is this please?

    • CRM Custom function updating a module record shows the Super Admin user as the record modifier

      Dear Zoho CRM Team, Is there any way to update this so that when a custom function has updated a record the Super Admin user doesn't become the modifier? This happens on the record as a modifier and shows up in the audit logs. It would be more useful

    • Best practice importing items and matching assemblies

      Hi, I was wondering what would be the best practice to import items and composite items (assemblies) From my backup, what should I import first? The items or the composite items? I am on Zoho one, using inventory and books. Kind regards, Sabine

    • Best way to fetch employee names from Zoho People into Zoho Creator Inventory Stock Form field Employee Name Lookup

      Hi Team, I have a requirement in my Zoho Creator application (Inventory Stock Adjustment) where I need to fetch employee names from Zoho People and use them as a lookup in a form. Currently, I am considering using an integration field to fetch this data

    • get file api is returning Junk data

      I am working on extension development where at one point I need to retrieve attachments on records I found out I can use only invokeconnection and not invokeurl in extension development The invoke connection returns the image in raw binary format. When

    • Next Page