README

此包用于与新的 Zoho V3 Api CRM 集成

要求

PHP >= 8.0
Laravel >= 8.0

注册 Zoho 客户端

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

访问此页面 https://api-console.zoho.com/
点击 添加客户端。
选择 自用客户端。
通过提供必要的范围、时间长度（生成的令牌有效时长）和范围描述来创建授权令牌。
现在您的客户端应用程序已创建并显示。
选择创建的 OAuth 客户端。
在创建授权令牌时使用此范围 aaaserver.profile.READ,ZohoCRM.modules.ALL,ZohoCRM.settings.ALL。

安装

您可以通过 composer require 安装此包

composer require asciisd/zoho-v3

安装包后，您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="zoho-v3-config"

之后，您需要运行以下命令来创建 OAuth 客户端并从 Zoho 获取凭据

php artisan zoho:install

您需要将以下变量添加到您的 .env 文件中。使用之前注册应用程序时获得的凭据。

ZOHO_AUTH_FLOW_TYPE=grantToken
ZOHO_CLIENT_ID="Code from Client Secrit Section"
ZOHO_CLIENT_SECRET="Code from Client Secrit Section"
ZOHO_REDIRECT_URI="${APP_URL}/zoho/oauth2callback"
ZOHO_CURRENT_USER_EMAIL=admin@example.com
ZOHO_TOKEN="Code Generated from last step"

# available datacenters (USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter)
ZOHO_DATACENTER=USDataCenter
ZOHO_SANDBOX=true

之后，您需要运行以下命令将令牌和刷新令牌添加到您的存储中

php artisan zoho:grant

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="zoho-v3-config"

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="zoho-v3-migrations"
php artisan migrate

环境

在某些情况下，您可能希望强制 Zoho 使用 Zoho 的某个环境之一，因此您可以转到 AppServiceProvider 并使用 Zoho::useEnvironment() 方法

Zoho::useEnvironment(EUDataCenter::DEVELOPER());

这将覆盖配置设置。

用法

假设您需要从 Zoho 系统获取所有模块。

use Asciisd\Zoho\ZohoManager;

$response = ZohoManager::make(self::TESTING_MODULE);
$modules  = $response->getAllModules();

模型可以使用如下方式：-

从 v1.1.0 开始提供

将 Zohoable 添加为扩展类，如下所示：-

use Asciisd\Zoho\Zohoable;
use Asciisd\Zoho\ZohoManager;

class Invoice extends Zohoable {
    
    // this is your Zoho module API Name
    protected $zoho_module_name = 'Payments';

    public function searchCriteria(){
        // you should return string of criteria that you want to find current record in crm with.
        //EX:
        return ZohoManager::make('Payments')
                            ->where('PaymentID', $this->payment_id)
                            ->andWhere('Order_ID', $this->order_id)
                            ->getCriteria();
    }

    public function zohoMandatoryFields() {
        // you should return array of mandatory fields to create module from this model
        // EX:
        return ['Base_Currency' => $this->currency];
    }
}

现在您可以使用发票如下所示

$invoice = \App\Invoice::find(1);

// to check if has zoho id stored on local database or not
$invoice->hasZohoId();

// to return the stored zoho id
$invoice->zohoId();

// that will search on zoho with provided criteria to find the record and associated your model with returned id if exist
// if you provided an `id` that will be used instead of searching on Zoho
$invoice->createOrUpdateZohoId($id = null);

// you can also send current model to zoho
// that wil use `zohoMandatoryFields` method to Serialize model to zohoObject
// Also you can pass additional fields as array to this method
$invoice->createAsZohoable($options = []);

注意：要像这样使用发票，您必须在数据库中创建 invoices 表，就像使用任何 Laravel 模型一样。这允许您将数据保存到数据库中，并能够将其链接到 zohos 表，并使用 Zohoable 中的所有功能。如果您不打算以这种方式使用 Zohoable 模型，请使用以下 CRUD 函数。

CRUD 可以使用如下方式：-

读取

use Asciisd\Zoho\ZohoManager;

// we can now deal with leads module
$leads = ZohoManager::useModule('Leads');

// OR

$leads = ZohoManager::make('Leads');

// find record by its ID
$lead = $leads->getRecord('3582074000002383003');

更新

$record = new Record();
$record->setId('3582074000002383003');

// Set value as field
$record->addFieldValue(Leads::FirstName(), 'Updated');
$record->addFieldValue(Leads::LastName(), 'Record');

// Set value as key value
$lead->setKeyValue('Phone', '5555555555552');

// Then call update() method
$response = $leads->update($record);

创建

// create the record into zoho crm then get the created instance data
$response = $leads->create([
    'First_Name' => 'Amr',
    'Last_Name' => 'Emad',
    'Email' => 'test@asciisd.com',
    'Phone' => '012345678910',
]);

删除

// delete record by its id
$lead = $leads->delete('3582074000002383003');

搜索

单词

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::useModule('Leads')->searchRecordsByWord('word to be searched');
$first_record = $records[0];

电话

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::useModule('Leads')->searchRecordsByPhone('12345678910');
$first_record = $records[0];

电子邮件

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::make('Leads')->searchRecordsByEmail('nobody@asciisd.com');
$first_record = $records[0];

标准

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::make('Leads')->searchRecordsByCriteria('(City:equals:NY) and (State:equals:Alden)')->get();
$first_record = $records[0];

自定义

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::make('Leads')
                    ->where('City', 'NY')
                    ->andWhere('State','Alden')
                    ->get();

$first_record = $records[0];

国际版本

如果您使用 zoho.com，您无需进行任何更改。

如果您使用 zoho.eu，请将其添加到 .env

ZOHO_ACCOUNTS_URL=https://accounts.zoho.eu
ZOHO_API_BASE_URL=www.zohoapis.eu

如果您使用 zoho.com.cn，请将其添加到 .env

ZOHO_ACCOUNTS_URL=https://accounts.zoho.com.cn
ZOHO_API_BASE_URL=www.zohoapis.com.cn

支持

联系
asciisd.com
aemad@asciisd.com
+2-010-1144-1444

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全漏洞

请查看我们的安全策略了解如何报告安全漏洞。

鸣谢

许可证

MIT 许可证 (MIT)。请参阅许可证文件了解更多信息。

asciisd / zoho-v3

维护者

详细信息