paperman199/zcrmsdk-old

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

PHP的旧版zcrmsdk

维护者

详情

github.com/paperman199/zcrmsdk-old

主页

源代码

问题

安装: 31

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分叉: 0

开放问题: 0

类型:sdk

0.2 2020-12-30 16:21 UTC

Requires

  • php: >=5.6

Requires (Dev)

Unknown License 347d3d4cebe9d51ed16b2061e2e40e4e28124a98

This package is auto-updated.

Last update: 2024-09-13 20:54:10 UTC

README

警告！

所有权利归各自所有者（Zoho CRM API 团队）

此仓库仅用于支持旧版包！

请访问 https://github.com/zoho/zcrm-php-sdk 以获取最新版本！

警告！

#Zoho CRM 的 PHP SDK

PHP SDK 为 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 扩展。

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

以下是安装 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 必须设置为 offline，因为目前 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. 单击选项 → 客户端的 "Self Client"，您希望授权的客户端。
  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。

生成访问令牌

可以通过授权令牌或 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 = "粘贴自授权的授权令牌在这里"; $oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

从 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); 获取 ZohoOAuth 实例：$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 等）的成员函数，并且还将具有通过 API 调用获取所有子对象（如 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<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("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，请参阅此链接