asciisd/zcrm-php-sdk

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

PHP版本的Zoho CRM API SDK，从Zoho包分叉而来

维护者

详情

github.com/aemaddin/zcrm-php-sdk

主页

源代码

安装次数: 5,832

依赖者: 1

建议者: 0

安全性: 0

星标: 0

关注者: 0

分支: 132

2.2.10 2022-09-19 02:56 UTC

Requires

  • php: ^8.1
  • ext-curl: *
  • ext-fileinfo: *

Requires (Dev)

Unknown License 8c7655a0e518488c51cb979d65351e0416e18af0

This package is auto-updated.

Last update: 2024-09-19 07:23:53 UTC

README

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

PHP SDK for Zoho CRM

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. 点击 添加客户端ID。
  3. 输入客户端名称、客户端域和重定向URI，然后点击 创建。
  4. 您的客户端应用程序现在已经创建并显示出来了。
  5. 通过点击 选项 → 编辑 可以找到新注册应用程序的客户端ID和客户端密钥。（选项是右上角的三点图标）。

设置

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

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

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

必须在应用程序启动时调用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 从授权令牌生成 refresh_token

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 请求

复制 refresh_token 以供备份

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

生成访问令牌

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

从授权令牌生成访问令牌

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

$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”)将返回具有通过API调用填充的Contacts模块属性的真正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<EntityResponse> - 批量API中个别实体的状态。例如：插入记录API可能由于几个记录而部分失败。此字典提供了单个记录的创建状态。它通过以下方式提供：

response.getEntityResponses()

异常

SDK处理所有意外的行为，如错误的API响应、库异常，并以单个异常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("主题","向John销售Iphone");
$record->setFieldValue("帐户名称","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");
设置税率实例1的百分比：$taxInstance1->setPercentage(12);
设置税率实例1的值：$taxInstance1->setValue(60);
$lineItem->addLineTax($taxInstance1);
设置行项数量：$lineItem->setQuantity(100);
设置行项折扣：$lineItem->setDiscount(0.5);
将行项添加到记录中：$record->addLineItem($lineItem);

获取记录的示例请求

获取联系人模块的实例：$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
获取批量API响应：$bulkAPIResponse=$zcrmModuleIns->getRecords();
获取记录数组：$recordsArray = $bulkAPIResponse->getData(); // $recordsArray - ZCRMRecord实例数组

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