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




                                    Zoho Desk Resources

                                    • Desk Community Learning Series


                                    • Digest


                                    • Functions


                                    • Meetups


                                    • Kbase


                                    • Resources


                                    • Glossary


                                    • Desk Marketplace


                                    • MVP Corner


                                    • Word of the Day



                                        Zoho Marketing Automation


                                                Manage your brands on social media



                                                      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

                                                                                                  • Feature Request - Configurable Payment Icons + Pay Now link in email.

                                                                                                    The PAY NOW buttons (icons) on invoices are really small. It would be great if we could make that a big, colored icon. Better would be to add a button to emails as well. 
                                                                                                  • Website Access Blocked (from one pc only) when attempting unattended access to any device

                                                                                                    Hello From one of my laptops I cannot access any remote device using unattended access. A Zoho Assist error page didplays 'Website Access Blocked. See attached.
                                                                                                  • AI read notes or explanation

                                                                                                    It would be such a great feature to have AI voices be able to read our Notes or Explanation If not having the AI speak the notes at run time, how about a feature where inside of Zoho Show you can have it look at all the notes of all the slides and have
                                                                                                  • Top Menu Disappeared from Blog Page

                                                                                                    Hi, Our top menu disappeared at Blog Posts page. However, it's still visible any other page on the website. I attached two screenshots, so it can be understood clearly. How can we bring back top menu? Thanks, K.
                                                                                                  • Managing Prepaid Hours for Consulting

                                                                                                    We are a consulting firm that bills clients a flat upfront annual fee plus an hourly rate and offer a discount for pre-paying a block of hours. Hours that surpass the pre-paid block are billed monthly at the normal rate. If there are any pre-paid hours remaining at the end of the project they are banked for future use. I'm not seeing a method of doing this in Projects/Books/CRM... thoughts?
                                                                                                  • ZOHO Widget SDK not loading in html

                                                                                                    I have this code below, I have imported the widgetsdk however I get the error shown in the image, I have tried many different ways of importing and initiating the function ZOHO but nothing is working. can someone explain what I'm doing wrong, if I am
                                                                                                  • Enhancements to Zoho Corp Help Center "Team Requests" View

                                                                                                    Dear Zoho Team, I hope this message finds you well. The ability to view both my tickets and my team’s tickets in the Zoho Corp Help Center is a fantastic feature, especially as the focal point for Zoho in our organization. However, we’ve encountered a
                                                                                                  • Allow Multiple Scheduled Appointments with Zoho Support

                                                                                                    Dear Zoho Team, I hope you're doing well. First, thank you for introducing the option to schedule support calls via the Zoho CRM booking link. This has been a fantastic enhancement, eliminating the need for back-and-forth coordination when scheduling
                                                                                                  • Projectwise budget ---

                                                                                                    Can we have a Project wise subject in addition to the Monthly, and quarterly ACCOUNT LEVEL budget?
                                                                                                  • WorkDrive API Documentation

                                                                                                    WorkDrive provides users and developers an extensive set of APIs to help integrate functionalities of Zoho WorkDrive with other Zoho applications and third-party tools. We have published the official WorkDrive API Documentation page for all external users.
                                                                                                  • Error 403: Forbidden When Updating Email Signature via API

                                                                                                    Hi Zoho Desk team, First, congratulations again on the excellent Zoho API. But, I’m encountering an issue while attempting to update an email signature via the API. Whenever I make a request to update the signature, the response returns an HTTP 403 Forbidden
                                                                                                  • Who can see draft replies on tickets?

                                                                                                    We have noticed that we are able to see draft replies made by other agents. Which settings can limit this visibility? It makes sense to me that admins and the agent who created the draft would be able to see the draft, but no one else. How can we make
                                                                                                  • Serious question: Are there actually "solo-preneurs"/small business owners who made Zoho-one work well for them?

                                                                                                    L.S. After already many years of continued struggle with Zoho-One, I am seriously wondering if there are actually solo-preneurs (one person small business owners - without a large, dedicated IT dept.) who got it (Zoho-One) to work well for their businesses.
                                                                                                  • Major iOS issues when accessing forms via the browser

                                                                                                    Hi, We have been using forms for some time, while the office staff are accessing the forms via the app on Android mobiles, we have a fleet of sub contractors that we would not like them having access to the main app as some of the forms are confidential
                                                                                                  • All notes disappeared

                                                                                                    I've been using the notebook app for over five years on my phone without being logged into an account. A few days ago I opened the app and all my notes had disappeared. Since then I tried restarting my phone, updating the app and logging into my account,
                                                                                                  • How to Iterate a Function in Zoho Desk Workflow with Delay Between Calls?

                                                                                                    Hi everyone, I’m working on a function in Zoho Desk that searches for a specific ticket record. If the ticket is not found, I need to retry the search multiple times with a delay between each attempt until the ticket is located or a maximum number of
                                                                                                  • How to Iterate a Function in Zoho Desk Workflow with Delay Between Calls?

                                                                                                    Hi everyone, I’m working on a function in Zoho Desk that searches for a specific ticket record. If the ticket is not found, I need to retry the search multiple times with a delay between each attempt until the ticket is located or a maximum number of
                                                                                                  • Work Orders / Bundle Requests

                                                                                                    Zoho Inventory needs a work order / bundle request system. This record would be analogous to a purchase order in the purchasing workflow or a sales order in the sales cycle. It would be non-journaling, but it would reserve the appropriate inventory of
                                                                                                  • Zoho Books API Limit Is RIDICULOUS!!!!!!!!!!!!!

                                                                                                    The 2,500 API call limit in Zoho Books is about as useful as AOL dialup.  Seriously Zoho, not only can I use up 2,500 API calls in no time with my own app but YOUR OWN STUPID IPAD APP blows through them super fast too, so if any one of my clients wants
                                                                                                  • QR codes in templates

                                                                                                    I'm excited about the new QR code generator. I have included a QR code that contains the record ID setting "${ID}" as input data. In the report detail it works perfectly but when printing it in a template the code is not shown.
                                                                                                  • Button Display Conditions

                                                                                                    Hi Guys, Is it at all possible to have extra button conditions? Context: We have data in our deals module which has a custom button which converts the deal into contacts + set up relationships between them. At the end of the conversion we set a field
                                                                                                  • Knowledge base: The nitty-gritty of SEO tags

                                                                                                    A well-optimized knowledge base with great SEO can benefit your company by allowing customers to find help articles and support resources using search engines. This enables customers to quickly and efficiently find the information they need without direct
                                                                                                  • Social Media Simplified with Zoho Social: Make the best out of the publishing calendar

                                                                                                    Are you a marketer who likes visualizing your plan of action before you start social media posting? Are you part of a team that works on social media on a rotational basis, so the most important task is to collaborate to avoid overlap and confusion? Or
                                                                                                  • Custom function daily limit and procedural programming

                                                                                                    Dearest Zoho Today, support confirmed that if I call a custom function from another custom function then I will use up two, with regards to my daily limit. A few times, we have blown our daily limit and that means that ordinary business processes don't run for the rest of the day. I have to mop these up the following day and there is no guarantee that I will get it right. Therefore, I can't afford to waste any. Procedural programming has been around for over 50 years now and it greatly simplifies
                                                                                                  • Unified customer portal login

                                                                                                    As I'm a Zoho One subscriber I can provide my customers with portal access to many of the Zoho apps. However, the customer must have a separate login for each app, which may be difficult for them to manage and frustrating as all they understand is that
                                                                                                  • Welcome Link Expired

                                                                                                    Hi The links sent to the users didn't get clicked on in time and now all the links have expired. Is there a way to send a new link without deleting them and re-adding them>
                                                                                                  • New enhancements: Changing portal users' email addresses and new customization options for templates

                                                                                                    Dear All, Portals have enabled organizations to extend access to various CRM modules to their customers, vendors, partners, and end users, per their business requirements. When a portal is created, an invitation email is sent to portal users with a link
                                                                                                  • Granular Time Frame Settings for Message Deletion and Editing in Zoho Cliq

                                                                                                    Dear Zoho Team, I hope you're doing well. Currently, the settings for message deletion and editing in Zoho Cliq are configured globally under: Admin Panel > Organisation > Configurations > Conversations Delete messages: Time frame to allow message deletion
                                                                                                  • New Built In QR/Barcode Generator Print Settings

                                                                                                    I'm trying out the new QR/Barcode generator field in Creator. I would think most people will want to print these, like I do. I am not seeing any way to control the height or width of the barcode for printing (inside the print/pdf template builder). The
                                                                                                  • Zoho One. Client Script

                                                                                                    Hi, I would like to know if the Client Script feature is available in Zoho One. If it's, how can I enable it?
                                                                                                  • Calendar View for Zoho Tickets

                                                                                                    Is there a way to view your tickets with due dates on a calendar view? I can not find a way to merge my Zoho Calendar and Tickets. This would be extremely helpful to my team.
                                                                                                  • Delete / Modify Default Career Site - Zoho Recruit

                                                                                                    Hello, It would be very useful if we could delete a default career site or change which of our career site is the default. Our Career site was created when there were issues with Zoho Recruit creating English CTA buttons on French Career sites. The only
                                                                                                  • Workflows for Timesheet

                                                                                                    Good day, Any way to have timesheet as triggers? I looked into Zoho Flow and into Zoho Project automation but no where can I have timesheet as a trigger. Basically, I would like to trigger something upon timesheet approval. Right now, the only way to
                                                                                                  • Is it possible to hide Developer Space for all user in Zoho Projects

                                                                                                    Hello! I am Zoho admin in a company and we want to use Zoho Project to manage projects, but after a few days of testing we are not able to "hide" the Developer Space from all kind of users except the admin. To sum up, I want to hide this for all users.
                                                                                                  • Introducing automation and utility conversations in WhatsApp marketing

                                                                                                    We’re excited to announce the addition of two new features to our WhatsApp integration: Automation and Utility conversations. These enhancements will allow you to streamline your marketing efforts and engage with your customers more effectively by automating
                                                                                                  • Extracting data from cells in zoho sheets for zoho books

                                                                                                    I am currently uploading my bank statment in excel format to zoho workdrive. I would like flow to extract certain data and send it to zoho books. Would scripting in zoho flow be able to help me with this? By this I mean should I attempt this in zoho flow
                                                                                                  • Within the Basic KPI component in Analytics, it is impossible to set "next" day range as a filter

                                                                                                    Hi there, I am currently setting up a deal dashboard for the Sales team. While it is possible to filter deal records to show records that were created LAST X days only, it looks like a NEXT X days Closing date filter is not available. Would it be possible
                                                                                                  • Pulling Specific Products from Sales Orders in Books to a CRM Record

                                                                                                    We currently process orders directly through our website (woocommerce) as well as through manual sales orders in zoho books. When an order comes through the website, all of the individual products from that order show up in the CRM record of that customer.
                                                                                                  • Você já viu os cursos do Zoho Mind?

                                                                                                    Pessoal, Tem uma plataforma da Zoho chamada Zoho Mind, muito interessante os cursos e vídeos tutoriais que lá possui. Para a turma do Zoho Creator, tem uma dica de Buscar dados em Formulário, segue o link e clique em Zoho Creator. https://www.zohomind.com.br/#/videostutoriais
                                                                                                  • Como gerar gatilhos para pagamento de impostos no Zoho Books?

                                                                                                    Olá Pessoal, boa tarde! Gostaria de saber como vocês estão escriturando os impostos a pagar no Zoho Books. Vi que temos a opção de Bills, porém se eu escriturar nesta aba do Zoho Books para gerar lembretes de tempo de vencimento por exemplo vai refletir
                                                                                                  • Next Page