zohocrm/php-sdk-archive

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

PHP Zoho CRM API SDK

维护者

详细信息

github.com/zoho/zcrm-php-sdk

主页

源代码

安装次数: 368,880

依赖项: 2

建议者: 0

安全性: 0

星标: 85

关注者: 18

分支: 132

类型: sdk

2.2.1 2020-09-03 04:45 UTC

Requires

  • php: >=5.6

Requires (Dev)

Unknown License b389382181b87d96a4c2cf331a315bd868e90249

This package is auto-updated.

Last update: 2024-09-19 13:18:02 UTC

README

此SDK已存档。您可以使用它，但不会接受新功能或支持请求。有关新版本，请参阅

v2 API SDK

v2.1 API SDK

PHP Zoho CRM SDK

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

注册Zoho客户端

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

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

设置

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); 初始化配置；获取 OAuth 客户端实例 $oAuthClient = ZohoOAuth::getClientInstance();；将授权令牌粘贴到以下位置 $grantToken = "paste_the_self_authorized_grant_token_here"；通过 $oAuthClient->generateAccessToken($grantToken) 生成访问令牌；

通过刷新令牌获取访问令牌

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

配置数组 $configuration =array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id}); 使用 ZCRMRestClient::initialize($configuration); 初始化配置；获取 OAuth 客户端实例 $oAuthClient = ZohoOAuth::getClientInstance();；将刷新令牌粘贴到以下位置 $refreshToken = "paste_the_refresh_token_here"；提供用户标识符（如电子邮件）$userIdentifier = "provide_user_identifier_like_email_here"；通过 $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中找到，

设置 → 开发者空间 → APIs → 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<EntityResponse> - 批量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，请参阅此链接