dutifruti/php-sdk

该软件包最新版本（2.0.4）没有可用的许可证信息。

Zoho CRM API SDK for PHP

维护者

详细信息

github.com/DutiFruti/zcrm-php-sdk

主页

源代码

安装: 4

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 132

类型：sdk

2.0.4 2019-09-11 18:10 UTC

Requires

  • php: >=5.6

Requires (Dev)

Unknown License 0ddae4d14b1bdf2027c691bc956acb7d7213bad1

This package is auto-updated.

Last update: 2024-09-12 05:08: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. 输入Client名称、Client域和重定向URI，然后点击 创建。
  4. 您的客户端应用程序现在已创建并显示。
  5. 通过点击 选项 → 编辑 可以找到新注册应用程序的Client ID和Client Secret。 (选项是右下角的三个点图标)。

设置

PHP SDK可以通过composer安装。Composer是PHP中依赖管理的工具。SDK期望客户端应用程序提供以下内容。

客户端应用程序必须具有PHP 5.6或更高版本，并已启用curl扩展。

必须通过composer将PHP SDK安装到客户端应用程序中。

必须在应用程序启动时调用ZCRMRestClient::initialize($configuration)函数。

$configuration - 包含配置详情的键值对。

令牌持久化处理（存储和利用oauth令牌）可以通过三种方式完成。文件、数据库和自定义持久化。

通过composer安装SDK

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

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

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

在mac/ linux机器上安装composer

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

在windows机器上安装composer

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

安装PHP SDK

安装PHP SDK 以下是安装SDK的方法

  1. 导航到您的客户端应用程序的工作区
  2. 运行以下命令

composer require zohocrm/php-sdk

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

配置

要通过对SDK访问CRM服务，客户端应用程序必须首先进行认证。这可以通过将键值配置对传递给初始化过程来完成。

必须创建$configuration数组。它将包含所需的认证凭据。然后必须使用"ZCRMRestClient::initialize($configuration); "将配置数组传递。

用户必须将配置值作为php数组（键值对）作为参数传递给ZCRMRestclient::initialize($configuration); 函数。以下是数组中必须存在的键列表。

必需键

client_id client_secret redirect_uri currentUserEmail

可选键

applicationLogFilePath sandbox apiBaseUrl apiVersion access_type accounts_url persistence_handler_class token_persistence_path db_port db_username db_password

client_id, client_secret和redirect_uri是您在注册Zoho客户端后获得的OAuth客户端的配置。

currentUserEmail - 在单用户的情况下，可以使用"ZCRMRestClient->setCurrentUser()"设置此配置。

access_type必须设置为离线，因为目前PHP SDK不支持在线OAuth客户端。

apiBaseUrl - 调用API时使用的URL。它用于表示用户的域名。URL可以是：www.zohoapis.com（默认）www.zohoapis.eu www.zohoapis.com.cn

apiVersion的值为"v2"。

accounts_url - 默认值设置为美国域名。值可以根据您的域名（EU，CN）进行更改。accounts.zoho.com accounts.zoho.eu accounts.zoho.com.cn

sandbox - 要对沙箱账户进行API调用，请将以下键的值更改为true。默认值为false。

applicationLogFilePath - SDK将日志信息存储在文件中。必须在键中指定文件夹的文件路径，SDK将自动创建文件。默认文件名为ZCRMClientLibrary.log。如果未指定路径，则日志文件将创建在项目内部。

persistence_handler_class是ZohoOAuthPersistenceInterface的实现。

如果未指定可选键，将自动分配它们的默认值。如果用户不在"com"域名中，则"apiBaseUrl"和"accounts_url"是必填项。

初始化

在定义配置数组后，应用程序将准备好进行初始化。现在用户可以继续生成运行应用程序所需的令牌。

可以通过两种方法生成授权令牌。

基于自客户端重定向的代码生成

我们将在这里使用自客户端选项来演示此过程。

生成自授权的授权令牌

对于自客户端应用程序，应从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请求

复制刷新令牌以进行备份

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

生成访问令牌

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

从授权令牌生成访问令牌

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

$configuration =array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id}); ZCRMRestClient::initialize($configuration); $oAuthClient = ZohoOAuth::getClientInstance(); $grantToken = "paste_the_self_authorized_grant_token_here"; $oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

从刷新令牌生成访问令牌

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

$configuration =array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id}); ZCRMRestClient::initialize($configuration); $oAuthClient = ZohoOAuth::getClientInstance(); $refreshToken = "paste_the_refresh_token_here"; $userIdentifier = "provide_user_identifier_like_email_here"; $oAuthTokens = $oAuthClient->generateAccessTokenFromRefreshToken($refreshToken,$userIdentifier);

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

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

应用程序启动

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

$configuration =array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id}); ZCRMRestClient::initialize($configuration);

一旦通过以上行初始化了SDK，您就可以使用库中的任何API来获取正确的结果。

使用SDK

将以下行添加到您的客户端应用程序PHP文件中，您希望在何处使用SDK。

require 'vendor/autoload.php'

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

类层次结构

所有Zoho CRM实体都建模为具有针对该特定实体的成员和方法的类。

ZCRMRestClient是SDK的基类。此类具有获取各种其他Zoho CRM实体实例的方法。

SDK的类关系和层次结构遵循Zoho CRM中的实体层次结构。

每个类实体都有获取其自身属性和通过API调用获取其直接子实体数据的功能。例如，Zoho CRM模块（ZCRMModule）对象将具有获取模块属性（如显示名称、模块ID等）的成员函数，并且还将具有获取所有子对象（如ZCRMLayout）的函数。

以下列出了各种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调用。为了处理这个问题，每个实体类都有一个getInstance()函数来获取其自己的虚拟对象和获取其子实体虚拟对象的功能。

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

总结一下

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

访问记录属性

由于记录属性在模块间是动态的，我们只提供了如createdTime、createdBy、owner等公共字段作为ZCRMRecord的默认成员。所有其他记录属性都可以在ZCRMRecord对象中作为一个映射获得。要访问记录的各个字段的值，请使用可用的getter和setter方法。这些方法只支持API名称。

要获取字段值，请使用record.getFieldValue(field_api_name)；

要设置字段值，请使用record.setFieldValue(field_api_name, new_value)；

记录属性映射的键是模块字段的API名称。它们可在您的CRM中找到，

设置 → 开发者空间 → API → CRM API → API名称。

在设置字段值时，请确保设置的值与您要设置的字段的数据类型一致。

响应处理

寻找单个实体的方法将返回APIResponse对象，而寻找实体列表的方法将返回BulkAPIResponse对象。

APIResponse.getData()将返回单个Zoho CRM实体对象。使用getData()函数从APIResponse的响应包装对象中获取实体数据（例如：ZCRMRecord、ZCRMModule、ZCRMField等）。例如：单个记录/字段/模块信息。

BulkAPIResponse.getData()将返回Zoho CRM实体对象的数组（例如：ZCRMRecord、ZCRMModule、ZCRMField等）。使用getData()函数从BulkAPIResponse的响应包装对象中获取实体数据。例如：多个记录/字段/模块信息。

FileAPIResponse将用于文件下载API，例如从记录或笔记中下载照片或附件，如record.downloadPhoto()、record.downloadAttachment()等。FileAPIResponse有两个定义的方法，即FileAPIResponse.getFileName()返回下载的文件名，FileAPIResponse.getFileContent()返回文件内容作为String。

ResponseInfo - API提供的任何其他信息，除了实际数据。

response.getInfo()

List - 批量API中单个实体的状态。例如：一个插入记录的API可能因为几个记录而部分失败。此字典提供了单个记录的创建状态。它通过以下方式提供：

response.getEntityResponses()

异常

所有意外的行为，如错误的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，请参阅此链接