Kaizen 94 PHP SDK V4 Configuration and Initialization

Kaizen 94 PHP SDK V4 Configuration and Initialization

Hello and welcome to another Kaizen week!

In previous Kaizen posts, we have covered in detail how to configure and initialize PHP SDKs for Zoho CRM v2.1 APIs. We have since released SDKs for v4 and v5 APIs. However, starting from v4, there are some changes in the configuration and initialization process.  In this post, we will discuss you how to configure and initialize PHP SDK v4 and v5.

The PHP Software Development Kit (SDK) simplifies the integration of client PHP applications with Zoho CRM. Acting as a wrapper for the REST APIs, it streamlines the usage of Zoho CRM services. 

Before proceeding with the configuration, make that your client application meets the prerequisites. This includes having PHP 7 or above installed, along with the cURL extension, which is necessary for connecting and communicating with Zoho CRM APIs.

I. 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 as Self-Client or Server based Applications depending on your application.
  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.

II. Installing the PHP SDK 

  1. If not already installed, follow the instructions provided at the corresponding link to install Composer.

     Mac/Linux
     curl -sS https://getcomposer.org/installer | php (terminal command)
     Windows https://getcomposer.org/doc/00-intro.md#installation-windows

  2. Install PHP-SDK using Composer
    1. Navigate to the workspace of your client app.
    2. 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. 
       
      composer require zohocrm/php-sdk-4.0 (for v4 APIs)
       composer require zohocrm/php-sdk-5.0 (for v5 APIs)
  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';

III. Token Persistence

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

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

Here, $token is an instance of the Token interface.

Token Persistence using a Database

In Database persistence, tokens are stored and retrieved from a database (e.g., MySQL).
Create a table in your database with the following required columns. For example, if you want to persist your tokens in a table named token in database named zoho, use this:
 
 CREATE DATABASE zoho; // use this to create database named zoho
// use this to create a table named token, with the following necessary columns
CREATE TABLE token ( 
  id varchar(10) NOT NULL,
  user_name 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)
);

Note that the columns are different for API v2.1. Please refer to this post for more details. . 

File Persistence

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

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.

IV. Configuration

The configuration step involves setting up various details in the SDK, such as user authentication, token persistence, logging, API call timeout settings, and more. The following keys are defined during this process:
  1. environment (mandatory): The API environment which decides the domain and the URL to make API calls, in Domain::Environment pattern.
    Domains : USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter
    Environments : PRODUCTION(), DEVELOPER(), SANDBOX()
  2. Token (mandatory): This key contains the user token details. Create an instance of OAuthToken with the information that you get after registering your Zoho client.  Depending on the available tokens, you can select one of the following flows:
    Note : You need to generate the tokens (grant/access/refresh) beforehand to use them in the respective flows.
    a) grantToken flow - You should use the grant Token for configuration.
     $token = (new OAuthBuilder())
      ->clientId("clientId")
      ->clientSecret("clientSecret")
      ->userSignature($user) //optional
      ->grantToken("grantToken")
      ->redirectURL("redirectURL") //optional
      ->build();

    b) refreshToken flow - Utilize the refresh token in this flow.
    $token = (new OAuthBuilder())
      ->clientId("clientId")
      ->clientSecret("clientSecret")
    ->userSignature($user) //optional
      ->refreshToken("refreshToken")
      ->build();

    c) 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())
       ->userSignature($user) //optional
       ->accessToken("accessToken")
       ->build(); 

    d) id flow - You can use the id from the persisted token file/DB to make API calls. The id is a unique system generated value for each token details entry in the file/DB.
    $token = (new OAuthBuilder())
       ->id("id")
       ->build();

  3. logger (optional) : 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. The default level is OFF.

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

  4. store (optional) : 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. For more details, refer here.
  5. SDKConfig (optional) : 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.

  6. requestProxy (optional) : Contains 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();

  7. resourcePath (optional) : Configure the absolute directory path to store user specific files containing module fields information. If skipped, the files will be stored in the project directory itself.

V. Initilization

After completing the configuration, you can proceed with 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\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;

  require_once "vendor/autoload.php";

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

Initialize::initializeSDK();
?>

You are now set to use the PHP SDK and make API calls. 

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

Cheers!




    Access your files securely from anywhere

          Zoho Developer Community

              Bootcamp
              Community
              Pricing
              Webinars
              What's New
              Integrations
              Contact Support
              Contact Sales

                Zoho Survey Resources
                  Features
                  Survey Templates
                  Integrations
                  Community
                  iOS Mobile Surveys
                  Pricing
                  Android Mobile Surveys
                  Insurvey Blogs
                  Insight Blogs
                  Tips & Tricks





                                Latest Feature Updates


                                    Zoho Desk Resources

                                    • Desk Community Learning Series


                                    • Digest


                                    • Functions


                                    • Meetups


                                    • Kbase


                                    • Resources


                                    • Glossary


                                    • Desk Marketplace


                                    • MVP Corner


                                    • Word of the Day




                                        Zoho Marketing Automation
                                          Zoho SalesIQ Resources


                                                Manage your brands on social media
                                                Access Zoho Social

                                                  Zoho Pagesense Resources


                                                      Zoho TeamInbox Resources

                                                        Zoho DataPrep Resources



                                                          Zoho CRM Plus Resources

                                                            Zoho Books Resources


                                                              Zoho Subscriptions Resources

                                                                Zoho Projects Resources


                                                                  Zoho Sprints Resources


                                                                    Qntrl Resources


                                                                      Zoho Creator Resources



                                                                          Zoho Campaigns Resources


                                                                            Zoho CRM Resources

                                                                            • CRM Community Learning Series

                                                                              CRM Community Learning Series


                                                                            • Kaizen

                                                                              Kaizen

                                                                            • Functions

                                                                              Functions

                                                                            • Meetups

                                                                              Meetups

                                                                            • Kbase

                                                                              Kbase

                                                                            • Resources

                                                                              Resources

                                                                            • Digest

                                                                              Digest

                                                                            • CRM Marketplace

                                                                              CRM Marketplace

                                                                            • MVP Corner

                                                                              MVP Corner





                                                                                Design. Discuss. Deliver.

                                                                                Create visually engaging stories with Zoho Show.

                                                                                Get Started Now


                                                                                  Zoho Show Resources


                                                                                    Zoho Writer Writer

                                                                                    Get Started. Write Away!

                                                                                    Writer is a powerful online word processor, designed for collaborative work.

                                                                                      Zoho CRM コンテンツ






                                                                                        Nederlandse Hulpbronnen


                                                                                            ご検討中の方





                                                                                                  • Recent Topics

                                                                                                  • Gravity Forms plugin not passing some fields

                                                                                                    I use the gravity form zoho plugin to push data from my lead form into my lead page in Zoho CRM. Everything was working file for about 6 months. Suddenly on Oct 1st, some of the fields are no longer getting passed to Zoho. The fields with the problem

                                                                                                  • Can't delete bank transactions (i changed from 14 days trail to free just now)

                                                                                                    Hi, I manually added one bank transaction When i try to delete it, it say below: What should I do?

                                                                                                  • Feature Request: Search in the PC client. Some thoughts about the search.

                                                                                                    Hi all. I'm really excited to start using Zoho Notebook, but I'm missing some of the search capabilities on my desktop. There are also some thoughts on improving search in general. Search is very important to me, without it it is difficult for me to use

                                                                                                  • Leave Policy for Brazil

                                                                                                    Hi, Brazil asked us to configure Zoho People to apply the following policy: · To block starting vacations 2 business days before holidays or weekends; Employees cannot start their vacations 2 days before holidays or weekends. Example: If December 25th

                                                                                                  • Adding date field to each individual Items when creating Invoices?

                                                                                                    When adding items into an invoice I need to be able to have a date for each item. Example below: Date Item Description Qty Rate Discount(%) Tax Amount 31/07/13 Brown Sugar Performance 1.00 3,000.00 0.00 10% $3300 Is this possible or will it be in the

                                                                                                  • Auto-Create OneDrive Folder Structure Upon Lead Creation

                                                                                                    Hello, New to Zoho and looking for help on a critical process automation I'm looking to implement. My company currently utilizes OneDrive for file management and the folder structure is Proposals -> Client Name -> Address (where I need to initially create

                                                                                                  • Profile Page View Customization

                                                                                                    I need to change the fields, sections from the profile view of an emplyoyee.

                                                                                                  • What do the Image Sizes mean in Zoho CRM Email Templates?

                                                                                                    Below you can see the image options in email templates: Banner, Fit, Small, Medium, Original, Custom. Can someone from Zoho please share with me: What each is/means? How each will look on desktop AND mobile? How to edit "custom"?  If I choose "Custom"

                                                                                                  • Translate any published presentation to the language of your choice

                                                                                                    As part of our constant effort to enrich your presentation experience, Zoho Show has rolled out a new feature for translating published presentations. Consider the following scenario: Zylker IT services, a multinational corporation, has announced product

                                                                                                  • Blueprint: multi-select lookup field not available in the criteria option

                                                                                                    I read this old forum post which stated that multi-select lookup fields are now selectable as an option in a Blueprint transition configuration: https://help.zoho.com/portal/en/community/topic/blueprint-multi-select-lookup-field-not-available-within-blueprint-transition

                                                                                                  • Apply Credit Note Automatically

                                                                                                    We need the ability to apply open Credit Notes toward invoices generated by recurring invoice as the first, priority payment. This should be an option that we can enable/disable in the recurring profile and/or the Credit Note. Other invoicing systems can do this. I'm not sure why Zoho Invoice doesn't have it. Here's an example for a Recurring Invoice... If a customer has open Credit Notes, and a saved credit card set for auto-pay, once an invoice goes out, the credit balance gets automatically applied

                                                                                                  • Workflow for "Expenses" module?

                                                                                                    Hi there, over the last 2 years, Zoho Expense has seen tremendous growth and we are happy with it. But, sometimes it is frustrating to see things are being implemented halfheartedly, or so it seems. For example, There is the possibility to create workflows

                                                                                                  • Record Template - Conditionally printing sections

                                                                                                    Is there a way to conditionally print a section of a Record Template? More specifically I am printing records from a Form "Invoice". That Form has 3 SubForms. I'd like to print the content of those SubForms using a Record Template but only if they have at least one line item. If they have no line items, I'd like to hide the headers for that section on the printout.

                                                                                                  • User can choose the PDF report

                                                                                                    Hi. I would like to find out if a user (Creator or customer portal) to choose from the different PDF customised reports that have been built?

                                                                                                  • Query table pull last 12 months

                                                                                                    I am tying to pull the following criteria and the date is always what causes me the issue. I want to pull people (pco_id) who have entries of "event_id" being these 2 events and whos "kind" is Regular or Guest and where the event_starts_at (date column)

                                                                                                  • PLEASE FIX Search options and consider a Global seach option

                                                                                                    A recent update has removed the ability to search for addresses and phone numbers under contacts. We cannot find where this moved to (If it is still available). Please put these options back as we cannot locate specific projects anymore. Also please consider allowing for a Global search. This would really improve the search engine. For example: If I search for "Sally Jones" then all invoices , estimates, vendors etc.. would populate.. Please let me know if you need any more information. Thank You....

                                                                                                  • Customize your calendar based on personal preferences

                                                                                                    Greetings, We're happy to introduce a few new capabilities to the Activities module's Calendar View! Now you can tailor your calendar's appearance and notification settings to suit your needs. In the past, the Calendar View lacked customization options

                                                                                                  • BUG ALERT: Client Script + Commands -> $Page contextual data is not updated

                                                                                                    When using the new Client Script Commands feature, there is an issue with the Client Script $Page contextual data not accurately being updated each time a Command is run. Assuming a Client Script Command called "Client Script Command Bug" with the following

                                                                                                  • Show iFrame of related List inside of Blueprint Transition

                                                                                                    Hey, is it possible to show an iFrame of a related list like this inside of a Blueprint transition?

                                                                                                  • Lookup Fields not Converting

                                                                                                    I manage holiday properties. I have a lookup to the Accounts (Properties) in the Leads module. The lookup is connected to the property address field. When I convert it the lookup field does not update in Deals, although the property address does. There

                                                                                                  • 2024: A Year of Transformation with Zoho Forms

                                                                                                    As we close the curtain on another exciting year, it’s time to reflect on the strides Zoho Forms has taken in 2024. From empowering businesses with advanced tools to simplifying workflows and enhancing user experiences, our updates this year were all

                                                                                                  • Stop selling out of stock Items.

                                                                                                    Hi I have been using Zohobooks for a around 8 month now. I am not involved in selling process but my staff cant stop selling product which they do not hold in stock, this is a big headache for me as physical count never matches what is shown on the books. 

                                                                                                  • Bigin API Token Request ("invalid_client")

                                                                                                    Hi people, I tried to connect to the API without success, I've read all of the documentation multiple time and tried just about everything. I tried to do it with Python Request module and with Postman, passing the information through both the URL parameter

                                                                                                  • Customer Happiness not clickable when using API

                                                                                                    Is there a way to automatically add the Customer Feedback links when generating email drafts via the API? Currently, the feedback links are only added when generating an email draft using the UI. I tried using the endpoint described in https://desk.zoho.com/DeskAPIDocument#CustomerFeedback#CustomerFeedback_Getthecustomerfeedbackplaceholderlink

                                                                                                  • Send To Zoho Sign not Showing

                                                                                                    The button send to Zoho sign is not showing on my Zoho CRM . Is there additional steps I need to take after installing Zoho Sign to CRM ?

                                                                                                  • How to Get An Image's URL once it's uploaded to library?

                                                                                                    I manage to find URLs to the images I uploaded to my library, but after a day, it seems the links stop working like its only temporary. Where can I find the ACTUAL solid URL for my images that I upload to my Library so I can use them for my custom template / HTML coded template? Thanks, Mac

                                                                                                  • 【Zoho CRM】インポート機能のアップデート：既存データへのタグ追加が可能に！

                                                                                                    ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中のインポート機能のアップデートをご紹介します。 Zoho CRMのタグは、データを効率的に分類、認識するためのラベルです。 タグ付けは次の3つの方法で行えます： 個別タグ付け：少数のデータを手動でタグ付け 自動化：特定のタイミングで繰り返しタグ付け 一括更新：インポート機能でタグを追加または更新 今回のアップデートでは、インポート時に既存のタグを残したまま、新しいタグの追加、既存タグを置き換えできるようになりました。

                                                                                                  • Bluerprints: How to connect the created record back?

                                                                                                    I've a blueprint which creates another record as part of an 'After' transition. But the two records don't seem to be linked together. If it's not automatic - how do I get the created record ID to link it to the original record? Thanks!

                                                                                                  • Populate a Related List Item based on a Stage

                                                                                                    I would like to know if I can populate a CLOSED DEAL section in a contact that populates only when a Deal (something in the Deal Module) is listed as Closed - Won. I'd like another section that is just called deals, which shows me all other deals that

                                                                                                  • Being able to draw inside a module ?

                                                                                                    I was wondering if anyone know of a solution for this request. We would like to be able to draw directly from one module in the CRM and have it attached to that record. Here is an example. Paul would go to the customer once he as done the measuring, he

                                                                                                  • 2 serial numbers for 1 item (Mac address and Serial number)

                                                                                                    There is a way to track 2 serial number type for 1 Item. Ex: Some electronic devices have a MAC address and a serial number. I need to track those 2 numbers

                                                                                                  • Holidays

                                                                                                    Hi; For defining Holidays, you need to add logic to handle the year as well as the month & day. We need to be able to enter Holidays for the next year. I need to add a holiday for January 2, 2017, but I can't until January 1st, which is a Sunday and we

                                                                                                  • Delete a department or category

                                                                                                    How do I delete a Department?  Also, how do I delete a Category? This is pretty basic stuff here and it's impossible to find.

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

                                                                                                  • Analytics Module: Can you move items from one dashboard to another?

                                                                                                    Is there a way to move items from one dashboard to another? I want to rearrange my dashboard now that I know what i'm doing but i don't want to remake my various widgets? Edit: Hey Zoho, This would be a good feature: to be able to move/copy widgets to

                                                                                                  • Copy Widget to another Dashboard

                                                                                                    I can see the option to clone a widget to the same dashboard but is it possible to copy it to another dashboard?

                                                                                                  • Is there a way to print the dashboard?

                                                                                                    I would like the capability of printing the dashboard - is that possible?

                                                                                                  • Custom Deal Name in Lead Conversion Mapping

                                                                                                    I know there are ways to change the name of a Deal after conversion using a custom function, so no need to repost that information. I would like to see the CRM Improved with Deal Name Customisation and I think the Lead Conversion Mapping page would be

                                                                                                  • Introducing Record Summary: smarter insights at your fingertips

                                                                                                    Hello everyone, Building on the recent launch of Zoho's in-house Zia Large Language Model (Zia LLM)—a major milestone in Zoho CRM’s AI capabilities—we’re excited to introduce the Record Summary feature. This powerful addition makes use of Zia LLM to simplify

                                                                                                  • Suppress "spreadsheet will not be saved" message on published sheet

                                                                                                    I have published a sheet and have one column on that sheet that the user can edit (a dropdown picklist where the user can select the status for each line). Is there a way to suppress the Zoho Sheet message "Any changes made to this published spreadsheet

                                                                                                  • Next Page