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

    • Live webinar: Transform data into impactful visuals with Zoho Show

      Data is frequently a core part of a presentation, whether it’s a sales pitch, project update, research report, or performance review. But when it’s just numbers on a page, the message you’re trying to convey can get buried. The real magic happens when

    • File attachments not working - web version

      Since Notebook announced better file attachments, I have experienced file attachments failing. When uploaded from my pc to the web version, notebook just spins. Acting like the attachment is very large. When it's 30k. If I cancel out of this, the notecard

    • API - Barebones Data for Send Doc For Signiture

      I am learning how to use with Zoho Sign API. I am wondering if someone can give me a bare bones JSON data sample for "Send Document For Signature". Below is the blank data that is pre-populated in postman. Seems like there is more here than the bare minimum

    • Revenue Management: #2 How to compute revenue?

      In our previous post, we discussed the revenue recognition standards under IFRS 15 and ASC 606 and the five-step model. Now, let's examine three distinct business scenarios to see how the standards and model work in practice. This will help you understand

    • External lookup in CRM (as in Books)

      Hello Context: We have a CRM module, similar to Deals, but for Purchasing. Once the PO is created, a link to this PO should be updated in that "deal". In Books, you can add a custom 'external' field which can look up into CRM modules. I'm asked to have

    • "Undo Send" Feature

      Would love it if TeamInbox had an "Undo Send" feature, that gives you 10 seconds or so to "undo" the sending of an email. Many other email clients already have this feature, and my clients really miss it, as it has saved them many times in the past when

    • Zoho Sites

      Does anyone have experience building Zoho sites or know how I can find someone who does?

    • Zoho Crm Lagging

      Hi Zoho Support Team, Starting from today, my Zoho CRM has been extremely slow and laggy when accessing any pages or modules. This is affecting my work and overall productivity. Could you please help to check if there are any ongoing issues or if there’s

    • Is there a way to reference/attach mails to deals/contacts when the mails haven't come through their contacts normal email and the mail comes through software / app who use their mail system

      There are often system mails that come through systems or other software which use their email addresses since they use their own mail servers to mail. This causes an issue as it does not record the mail in the history of the CRM since the email is not

    • Recommendation

      I give up on Zoho. It's never going to be an all in one solution, their own apps don't even connect. Can any one recommend an alternative at least for the crm / people.

    • CRM - Site/Location

      Hi Zoho, One massive oversight of the Zoho CRM is the inability to add multiple sites or locations to one account. Many organisations have several (in some cases, hundreds) of sites across the country or even the globe. The workaround to this, of course,

    • An unknown error occurred. Please contact support

      Whenever I visit this page I see this. I changed browser and still the same. Can someone from Zoho help me please?

    • How to Streamline Pick & Ship

      Is there a way to streamline the built-in pick and ship process? I guess mostly on the ship side. Our current process allows us to choose shipping super fast. It's an EasyPost plugin for WooCommerce. You have to populate the boxes / weights / shipping

    • How to add, delete or rename the "payment method" drop down?

      When we recorded payment in invoice, there's a "payment method" drop down with choices like cash, bank transfer... We want to add and delete or rename some new selection. How to do such adjustment? Please advice.

    • Smarter data gathering with Query component in Wizards

      Dear All, Introducing the Query Component in Wizards for CRM! A smart search field that saves you time and effort, and helps you manage and gather data more efficiently than ever before. Long and complex record entries can be overwhelming and prone to

    • Introducing teamspaces and team modules in Zoho CRM mobile app

      Hello everyone, We have an exciting update to share in the Zoho CRM mobile app. As part of CRM For Everyone—a new set of features that reflect our vision to democratize CRM and make it accessible for all—teamspaces and team modules are now available on

    • Client Script - change page and/or section background colours

      Hello, Would anyone be willing to help me with a bit of Client Scripting code? I have had a go myself but only been able to alter the form field styles, not the overall page/section/heading styles. I want to set a different page background colour for

    • Zoho SalesIQのチャットボット、ブロックのコピー機能

      Zoho SalesIQのチャットボットの構築でドラッグアンドドロップで作成を行っているます。 内容は同じブロックのコピーペースト機能がないみたいなのですが、同一のブロック、同一の複数のブロックをいくつも作成する場合は、皆様はどのように行われていますか？ 例えば添付の４つのブロックをまとめてコピーして、別のフローの先につなげる場合です。 教えていただけますと幸いです。よろしくお願いいたします。

    • Questions About Zoho Commerce Member Portal

      Hello, A couple questions about the Zoho Commerce Member Portal: 1. Can I add only specific pages be added to the Members Portal, and not the entire website? 2. When a customer signs up on my Zoho Commerce site, is there a setting that gives me a chance

    • Cancel and refund

      Hi, Yesterday I paid for the Zoho email subscription. Within a few minutes, I realized that the subscription counts one email ID as one user. To make another email ID for the same domain name, I'd have to pay for another user. I emailed right away to

    • Online Payment Fees

      We don't take many online credit card payments so the merchant service provider (PayPal) charges us the 2.9% fee for processing the amount. I would like the ability for the fee to be automatically added to the total amount for "ease of payment". We'd

    • Error occured. please try again!!!

      I created a new list. Added two new contact's email addresses. I try to EDIT either one of them to add their first name, last name and phone number. Whatever I try to edit and update, I get the error message  Error occured. please try again!!! And it doesn't update any of their info. I tried just editing first and last name. Still get the error. No matter what I try to update, I get the error. I tried creating a new list, and adding just one email address and then edit it and also get the error.

    • "Send email as" not work

      Hi team, I currently use ZOHO MAIL services on the MAKE platform (formerly INTEGROMAT). In MAKE I entered my ZOHO MAIL credentials but the problem is that when the emails are sent from the automation in MAKE, the emails do not come in with the name set

    • *UPDATE: ISSUE RESOLVED, SEE HOW FOR HELP* Issue imbedding Youtube Videos

      **UPDATE: RESOLVED** For anyone that is having a similar issue, try this workaround before attempting to have the Zoho techs fix it. I have been in communication with them for weeks about this and they can't seem to fix the issue. Thinking it may have just been my computer or my browser, I tried two different computers on two different networks, each running different versions of Windows, and tried it on Chrome, Firefox and IE; nothing worked. So, needless to say, it's an issue with Zoho somewhere.

    • Backorder For Composite Items

      Hello If i released SO for composite item and use backorder feature of zoho inventory then it should backorder child item items of composite and not composite item.This is basic of backordering.I conveyed this to zoho call center but no solution yet.

    • Paid Support

      We are in the process of creating tiers for our support offerings. There will be three tiers of support available - 2 paid and 1 free. The paid tiers will be purchased in allotted hours. I need to figure out how to a) work in the out of the box SLA, Contracts

    • Automatically CC supervisor

      Hello,  in our organization agents are replying to tickets and they are required to CC their supervisor on all emails to and from customers.  is there a way to have an email address automatically populate in the CC field when reply to a ticket?  tha

    • Zoho One - White Label

      Releasing a white-label feature for Zoho One, or any software or service, can offer several advantages and benefits for both the company providing the software (Zoho in this case) and its users. Here are some key reasons for releasing a white-label feature

    • Are this Features included in the Road Map

      1. Sync between description/short description in Zoho Books/Inventory and Zoho Commerce: I am unsure how it works now. I belive the description is not pulled. 2. Pick Up: This feature is great. It is added on Zoho Commerce but not on Books/Inventory which

    • Reconciliation - Show Transactions After End Date

      I did a quick search, and I've only seen this brought up indirectly. In the reconciliation interface, transactions dated up to a week after the end date should be available for being reconciled. The use case is pretty simple... many times, transactions

    • Auto populate email field in zoho form

      Hi,  Is there a way the email field in zoho forms can be auto populated based on the name selected from a drop down list?

    • Option to accept and pay for estimate from Public Estimate link?

      Is there any way that our customers can get the Estimate in their email, click on "View Estimate" and from the public link, click Accept and Pay? When they click that, in the background Zoho would create the invoice record in the so that the payment would

    • Kaizen #125 Manipulating Multi-Select Lookup fields (MxN) using Zoho CRM APIs

      Hello everyone! Welcome back to another week of Kaizen. In last week's post in the Kaizen series, we discussed how subforms work in Zoho CRM and how to manipulate subform data using Zoho CRM APIs. In this post, we will discuss how to manipulate a multi-select

    • Easily track referrals with Zoho Forms

      Referral tracking can be a powerful way for businesses to understand where their leads are coming from. With Zoho Forms, tracking the referral sources of your leads is an easy and straightforward process. Here are some tips to help you make the most of

    • Add an email to an existing ticket is not working

      I noticed that in Zoho Desk the funcionality to add an email to an existing ticket is not working using the syntax [##12345##], has the method changed? In red is the syntax we use to add email to an existing ticket As you can see, he did not add the email

    • New CRM to Campaigns Sync Doesn't Continue Making Updates

      Changes made in CRM are not appearing in mapped fields in matching Campaign records after migrating to the new sync process. The only way we've found to get records to update is to call into Support and point out the problem. After convincing Support

    • Zoho Integration with UPS

      I have 2 questions: Firstly, is there a way to notify UPS that we have a package to collect once we have done the shipping label? Secondly, how do I get the tracking number and shipment method onto the Invoice and Package Slip for the customer? Than

    • Cannot log in to IMAP account as of last night

      Hey I've been using MFA with an authenticator for a while and have had to use application passwords for Outlook and Edison Mail on my Android devices. Last night the app passwords started to be rejected on my Android devices so I created new ones for

    • Low Stock View

      We use the Low Stock view frequently as a guide to inform us when to reorder items, but the view is misleading because it does not take into account Purchase Orders that have already been raised. Unless you are aware and check item by item, this can lead

    • Improve History Feature in Zoho Inventory

      At present there is a "history" tab on Zoho Inventory Items, however this only shows a date and time stamp along with the users name. It doesn't say what was changed. What is the value of this if you can't see what was changed? My Ideal is to include

    • Next Page