jobs-at/zohocrm-php-sdk

此包的最新版本（v1.2.7）没有可用的许可证信息。

Zoho CRM API SDK for PHP

维护者

详细信息

github.com/jobs-at/zcrm-php-sdk

主页

源代码

安装: 4,943

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 3

分支: 104

类型:sdk

v1.2.7 2020-11-03 14:50 UTC

Requires

  • php: >=5.6

Requires (Dev)

Unknown License 4ba57a7b55e8d1aed839497045fd63f042d5d52d

This package is auto-updated.

Last update: 2021-09-11 15:46:46 UTC

README

PHP SDK for Zoho CRM APIs提供Zoho CRM API的包装。因此，从您的客户端应用程序调用Zoho CRM API仅是方法调用。它支持单用户和多用户身份验证。

注册Zoho客户端

由于Zoho CRM API使用OAuth2标准进行认证，您应该在Zoho上注册您的客户端应用程序。要注册您的应用程序

  1. 访问此页面 https://accounts.zoho.com/developerconsole。
  2. 单击 添加Client ID。
  3. 输入客户端名称、客户端域和重定向URI，然后单击 创建。
  4. 您的客户端应用程序已创建并显示。
  5. 通过单击 选项 → 编辑 可以找到新注册应用程序的客户端ID和客户端密钥。（选项是右下角的三点图标）。

设置

PHP SDK可以通过composer安装。Composer是PHP中依赖关系管理的工具。SDK期望客户端应用程序满足以下要求。

客户端应用程序必须具有PHP 5.6或更高版本，并启用了curl扩展。客户端库必须通过composer安装到客户端应用程序中。应用程序启动时必须调用ZCRMRestClient::initialize()函数。

MySQL应在同一台机器上运行，默认端口为3306。
数据库名称应为"zohooauth"。
必须有一个名为"oauthtokens"的表，包含以下列："useridentifier"(varchar(100))、"accesstoken"(varchar(100))、"refreshtoken"(varchar(100))、"expirytime"(bigint)。

如果token_persistence_path在oauth_configuration.properties文件中提供，则持久化仅在文件中发生。在这种情况下，无需MySQL。请创建一个名为zcrm_oauthtokens.txt的空文件，放置在指定的token_persistence_path

通过composer安装SDK

安装Composer（如果尚未安装）运行以下命令安装composer

curl -sS https://getcomposer.org/installer | php

要使composer可全局访问，请按照以下链接中的说明操作

在mac/ linux机器上安装composer

https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx

在windows机器上安装composer

https://getcomposer.org/doc/00-intro.md#installation-windows

安装PHP SDK

以下是安装SDK的步骤
导航到您的客户端应用程序的工作区
运行以下命令

composer require zohocrm/php-sdk

因此，SDK将安装，并在您的客户端应用程序的工作区中创建一个名为vendor的包。

配置

应将OAuth客户端详细信息作为属性文件提供给SDK。
在SDK中，我们放置了一个配置文件（oauth_configuration.properties）。
请将相应的值放入该文件中。
您可以在 vendor/zohocrm/php-sdk/src/resources 目录下找到该文件。

请只填写以下键。根据您的域名（EU，CN），请更改 accounts_url 的值。默认值为美国域名

client_id=
client_secret=
redirect_uri=
accounts_url=https://accounts.zoho.com
token_persistence_path=

以上显示的键才是需要填写的。
client_id、client_secret 和 redirect_uri 是您在注册 Zoho 客户端后获得的 OAuth 客户端的配置。
token_persistence_path 是存储 OAuth 相关令牌的文件路径。如果设置了此路径，则不需要 database 进行持久化。持久化仅通过 file 实现。
access_type 必须设置为 offline，因为 SDK 目前不支持在线 OAuth 客户端。
persistence_handler_class 是 ZohoOAuthPersistenceInterface 的实现。

在您的客户端应用程序机器上创建一个名为 ZCRMClientLibrary.log 的文件，并在 configuration.properties 中将创建的文件的绝对路径指定为 applicationLogFilePath 键。
您可以在 vendor/zohocrm/php-sdk/src/resources 目录下找到该文件。该文件用于记录 SDK 使用过程中发生的异常。

请只填写以下键

applicationLogFilePath=

要向 sandbox account 发送 API 调用，请将以下键的值在 configurations.properties 中更改为 true。默认值为 false

sandbox=true

如果您的应用程序只需要单个用户认证，则必须在 configurations.properties 文件中设置用户 EmailId，如下所示

currentUserEmail=user@email.com

为了使用多用户认证，您需要将用户 EmailId 设置在 PHP 超全局变量 ‘$_SERVER’ 中，如下所示

$_SERVER[‘user_email_id’]=“user@email.com”

您也可以使用 $_SERVER 变量进行单个用户认证，但建议在 configuration.properties 文件中设置电子邮件 ID。

如果您没有在超全局变量中设置用户电子邮件，则 SDK 期望从 configuration.properties 文件中获取它。如果未在这两个地方设置用户电子邮件，则 SDK 将抛出异常。

初始化

在定义 OAuth 配置文件后，应用程序就准备好初始化了。

生成自授权授予令牌

对于自客户端应用程序，自授权授予令牌应从 Zoho 开发者控制台（https://accounts.zoho.com/developerconsole）生成

  1. 访问 https://accounts.zoho.com/developerconsole
  1. 点击选项 → 客户端的自客户端，您希望授权的客户端。
  2. 在“范围”字段中输入一个或多个（以逗号分隔）有效的 Zoho CRM 范围，您希望授权，并选择过期时间。
  3. 复制授予令牌。
  4. 使用以下 URL 从授予令牌生成刷新令牌

https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code 这是一个 POST 请求

复制刷新令牌以备备份

请注意，生成的授予令牌仅在您生成时指定的规定时间内有效。因此，应在该时间内生成刷新令牌。

生成访问令牌

访问令牌可以通过授权令牌或刷新令牌生成。以下两种方法中的任何一种都足够。

从授权令牌获取访问令牌

以下代码片段应在主类中执行以获取访问令牌。请将复制的授权令牌粘贴到下面的字符串字面量中。这是一个一次性过程。

ZCRMRestClient::initialize();
$oAuthClient = ZohoOAuth::getClientInstance();
$grantToken = "在这里粘贴授权令牌";
$oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

从刷新令牌获取访问令牌

以下代码片段应在主类中执行以获取访问令牌。请将复制的刷新令牌粘贴到下面的字符串字面量中。这是一个一次性过程。

ZCRMRestClient::initialize();
$oAuthClient = ZohoOAuth::getClientInstance();
$refreshToken = "在这里粘贴刷新令牌";
$userIdentifier = "在这里提供用户标识，如电子邮件";
$oAuthTokens = $oAuthClient->generateAccessTokenFromRefreshToken($refreshToken,$userIdentifier);

成功执行上述代码片段后，生成的访问令牌和提供的刷新令牌将通过网络持久化处理类持久化。

一旦OAuth令牌被持久化，后续的API调用将使用持久化的访问和刷新令牌。SDK将在需要时自动使用刷新令牌刷新访问令牌。

应用启动

SDK需要以下代码行在每次启动客户端应用时调用。

ZCRMRestClient::initialize();

通过上述行初始化SDK后，您可以使用库中的任何API获取正确的结果。

使用SDK

在客户端应用的PHP文件中添加以下行，您希望使用SDK的地方。

require 'vendor/autoload.php'

通过此行，您可以访问PHP SDK的所有功能。

类层次结构

所有Zoho CRM实体都作为具有适用属性的类的模型。ZCRMRestClient是SDK的基类。ZCRMRestClient具有获取各种其他Zoho CRM实体实例的功能。

库的类关系和层次结构遵循Zoho CRM中的实体层次结构。以下给出了各种Zoho CRM实体的类层次结构

  • ZCRMRestClient
    • ZCRMOrganization
      • ZCRMUser
        • ZCRMUserTheme
          • ZCRMUserCustomizeInfo
        • ZCRMRole
        • ZCRMProfile
          • ZCRMPermission
          • ZCRMProfileSection
            • ZCRMProfileCategory
      • ZCRMModule
        • ZCRMLayout
          • ZCRMSection
            • ZCRMField
            • ZCRMPickListValue
            • ZCRMLookupField
          • ZCRMLeadConvertMapping
            • ZCRMLeadConvertMappingField
        • ZCRMCustomView
          • ZCRMCustomViewCategory
          • ZCRMCustomViewCriteria
        • ZCRMRelatedListProperties
          • ZCRMModuleRelatedList
        • ZCRMRecord
        • ZCRMNote
        • ZCRMAttachment
        • ZCRMInventoryLineItem
          • ZCRMTax
        • ZCRMEventParticipant
        • ZCRMPriceBookPricing
        • ZCRMModuleRelation
        • ZCRMJunctionRecord
        • ZCRMTrashRecord

每个实体类都有函数来获取其自己的属性，并通过API调用获取其直接子实体的数据。

例如：Zoho CRM模块（ZCRMModule）对象将具有获取模块属性（如显示名称、模块ID等）的成员函数，并且还将具有获取所有子对象（如ZCRMLayout）的函数。

实例对象

从顶级开始完整地遵循类层次结构以获取某个较低级别的实体数据并不总是有效的，因为这会涉及每个级别的API调用。为了处理这个问题，每个实体类都有一个getInstance()函数来获取其自己的模拟对象，以及获取其子实体模拟对象的函数。

请注意，getInstance()函数不会填充任何属性，因为它不会触发API调用。这只会返回一个模拟对象，仅用于访问类的非静态函数。

总结

调用ZCRMRestClient::getModule(“Contacts”)会返回实际的Contacts模块，该模块通过API调用填充了Contacts模块的所有属性。
调用ZCRMRestClient::getModuleInstance(“Contacts”)会返回一个模拟的ZCRMModule对象，该对象将引用Contacts模块，但没有填充任何属性，因为这不进行API调用。
因此，要从模块获取记录，不一定需要从ZCRMRestClient开始。相反，您可以使用ZCRMModule::getInstance()获取ZCRMModule实例，然后从创建的实例调用其非静态的getRecords()函数。这将避免触发填充ZCRMModule对象的API调用。

访问记录属性

由于记录属性在模块之间是动态的，因此只有诸如createdTime、createBy、owner等字段作为ZCRMRecord的默认属性提供。所有其他记录属性都作为ZCRMRecord对象的映射中的内容提供。

要访问记录的单个字段值，请使用可用的getter和setter函数。记录属性映射的键是模块字段的API名称。所有模块的所有字段的API名称都可在“设置”→“市场”→“API”→“CRM API”→“API名称”下找到。

要获取字段值，请使用$record → getFieldValue($fieldAPIName);
要设置字段值，请使用$record → setFieldValue($fieldAPIName, $newValue);
在设置字段值时，请确保设置的值是您要设置的字段适当的数据类型。

响应处理

APIResponse和BulkAPIResponse是Zoho CRM API响应的包装对象。所有API调用函数都会返回这两个对象之一。

DownloadFile和downloadPhoto返回FileAPIResponse而不是APIResponse。
寻找单个实体的函数会返回APIResponse，而寻找实体列表的函数会返回BulkAPIResponse对象。使用getData()函数从响应包装对象中获取实体数据。`APIResponse → getData()`会返回一个单独的Zoho CRM实体对象，而`BulkAPIResponse → getData()`会返回Zoho CRM实体对象的列表。除了数据之外，这些响应包装对象还具有以下属性

ResponseHeaders - 当天/窗口剩余的API调用数以及当前窗口重置所花费的时间。
ResponseInfo - API提供的任何其他信息（如果有的话），除了实际数据之外。
实体响应数组 - 批量API中单个实体的状态。
例如：插入记录的API可能因为少数记录而部分失败。此数组提供了单个记录的创建状态。

异常

所有意外的行为，如错误的API响应、库异常，都由SDK处理，并且仅抛出一个单个异常 - ZCRMException。因此，在客户端应用程序代码中只需要捕获这个异常即可。

示例

插入记录的示例请求

$zcrmModuleIns = ZCRMModule::getInstance("Invoices");
$bulkAPIResponse=$zcrmModuleIns->createRecords($recordsArray); // $recordsArray - 包含创建所需数据的ZCRMRecord实例数组。
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "状态:".$entityResponse->getStatus();
echo "消息:".$entityResponse->getMessage();
echo "代码:".$entityResponse->getCode();
$createdRecordInstance=$entityResponse->getData();
echo "实体ID:".$createdRecordInstance->getEntityId();
echo "模块API名称:".$createdRecordInstance->getModuleAPIName();
…}

Sample Invoice record instance with filled data
-----------------------------------------------

$record=ZCRMRecord::getInstance("Invoices",null);
$record->setFieldValue("Subject","Iphone sale to John");
$record->setFieldValue("Account_Name","410405000001016021");
$productInstance=ZCRMRecord::getInstance("Products",410405000001108011);
$lineItem=ZCRMInventoryLineItem::getInstance($productInstance);
$taxInstance1=ZCRMTax::getInstance("Sales Tax");
$taxInstance1->setPercentage(2);
$taxInstance1->setValue(10);
$lineItem->addLineTax($taxInstance1);
$taxInstance1=ZCRMTax::getInstance("Vat");
$taxInstance1->setPercentage(12);
$taxInstance1->setValue(60);
$lineItem->addLineTax($taxInstance1);
$lineItem->setQuantity(100);
$lineItem->setDiscount(0.5);
$record->addLineItem($lineItem);

获取记录的示例请求

$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->getRecords();
$recordsArray = $bulkAPIResponse->getData(); // $recordsArray - 包含ZCRMRecord实例的数组

有关更多API的信息，请参阅此链接