README

此仓库作为使用OAuth的CRM提供商的基础。您可以使用此库轻松扩展您的CRM提供商实现。例如，zoho，pipedrive等可以轻松实现使用此CRM提供商实现Oauth。

安装

使用composer安装此包。要安装，请将以下内容添加到您的composer.json中：

{
   "require": {
        "myoperator/crm": "dev-master"
    },
    "repositories": [
        {
            "url": "http://github.com/myoperator/crm",
            "type": "vcs"
        }
    ]
}

然后运行composer install来安装包。

快速入门

创建您的CRM类

从\MyOperator\Crm\CrmProvider类扩展您的MyCrm类。

use \MyOperator\Crm\CrmProvider;


// Your Zoho provider
class MyCrm extends CrmProvider {
    // Your implementation here
}

实现刷新令牌机制

一旦扩展了这个类，您将获得访问几个方法，这些方法将帮助您获取访问令牌和刷新令牌。您需要为您的CRM控制器实现refreshToken()方法，以告诉如何从CRM提供商刷新令牌。

use \MyOperator\Crm\CrmProvider;

class MyCrm extends CrmProvider {

    /* *
     * Use this function to refresh the token as per your CRM implementation.
     * Return values should be either array ['access_token' => $token, 'timeout' => $timeout]
     * or simply a string of access token
     * 
     * @param $client_id Client id
     * @param $client_secret Client Secret
     * @param $refresh_token Refresh token
     * 
     * @return ['access_token' => $token, 'timeout' => $timeout] || $token
     * */
    function refreshToken($client_id, $client_secret, $refresh_token) {
        // This is only a sample implementation
        $response = $your_curl_lib->post("/token?refresh_token={$refresh_token}&client_id= {$client_id}&client_secret={$client_secret}&grant_type=refresh_token");
        return ['access_token' => $response['access_token'], 'timeout' => $response['expiry_in_secs']];
    }

    function search($records) {
        // Implement your crm search here
    }
}

设置您的令牌提供者

CrmProvider使用实现MyOperator\Crm\TokenProvider类的任何令牌提供者。您可以使用apitokenprovider.php作为示例（来自示例文件夹）。基本实现如下：

use \MyOperator\Crm\TokenProvider;

class MyTokenProvider implements TokenProvider {

    public function getClientId() {
        // Implementation to get client id
    }
    
    // Implement rest of the methods from TokenProvider
}

实现

现在是最后一部分。在此阶段，您将有两个文件

• MyCrm.php
• MyTokenProvider.php

您可以按如下方式实现：

$company_id = 1;

$mycrm = new MyCrm($company_id);

$provider = new MyTokenProvider();
$mycrm->setTokenProvider($provider);

$results = $mycrm->search($record);

可用方法

getOauthTokenKey()

您可以通过此方法获取Bearer名称。

class MyCrm extends CrmProvider {

    function search(){
        var_dump($this->getOauthTokenKey());
        // Bearer
    }
}

您也可以重写此方法以在您的授权头中设置自定义的bearer。例如，zoho使用Zoho-oauthtoken作为bearer。您可以轻松设置如下：

class MyCrm extends CrmProvider {

    // This means our authorization header will look like
    // `Authorization: my-bearer $token`
    function getOauthTokenKey() {
        return 'my-bearer';
    }
}

getTransport()

这为您提供了一个MyOperator\Transport实例。您可以使用此实例对API进行get或post调用。

class MyCrm extends CrmProvider {

	function search() {
		$curlTransport = $this->getTransport();
		$response = $curlTransport->post(
			'/some-endpoint', 
			['data' => 'some-data']
		);
        	var_dump($response->json());
        	// {"some response": "in json"}
	}
}

setHeader($key, $val)

如果您需要，您也可以设置自定义头到您的CRM端点。

class MyClass extends CrmProvider {

	function search() {
        	$this->setHeader('a', 'b');
       		// Or $this->getTransport()->setHeaders(['a' => 'b']);
        	$response = $this->getTransport()->post('/some-endpoint',['data' => 'some-data']);
        	var_dump($response->json());
        	// {"some response": "in json"}
	}
}

示例Zoho CRM提供商

让我们实现ZohoCrm类来搜索线索。假设我们希望搜索记录并创建线索。我们可以轻松实现。

use \MyOperator\Crm\CrmProvider;

class ZohoCrm extends CrmProvider{

    // Zoho uses Zoho-oauthtoken as bearer
    function getOauthTokenKey() {
        return 'Zoho-oauthtoken';
    }

    // Zoho implementation to refresh token
    function refreshToken($client_id, $client_secret, $refresh_token) {
        $transport = $this->getTransport();
        $response = $transport->post("https://accounts.zoho.in/oauth/v2/token?refresh_token={$refresh_token}&client_id={$client_id}&client_secret={$client_secret}&grant_type=refresh_token");
        $response =  $response->json();
        return ['access_token' => $response['access_token'], 'timeout' => $response['expiry_in_secs']];
    }

    // This searches Zoho CRM for phone records
    public function searchByPhone($phonenumber) {
        $criteria = "((Phone:equals:{$phonenumber})or(Mobile:equals:{$phonenumber}))";

        // You can use your own curl lib here as well
        $curl_lib = $this->getTransport();

        try { 
            $response = $curl_lib->get(
                'https://www.zohoapis.in/crm/v2/leads/search', 
                ['criteria' => $criteria]
            );
            if($response->getStatus() == 204) {
                return null;
            }
            return $response->json();
        } catch (\Exception $e) {
            // Some zoho exception occured. Handle it
            throw $e;
        }
    }
}

处理过期令牌

使用\MyOperator\Crm\CrmProvider库的主要好处是处理异常处理、自动刷新令牌以及提供基本的curl传输机制。

因此，您在扩展\MyOperator\Crm\CrmProvider类的类上创建的任何方法都会自动调用刷新令牌。还记得您需要在自己的类中实现refreshToken方法吗？这就是魔法所在。

\MyOperator\Crm\CrmProvider在您的类中内部搜索refreshToken方法，以获取刷新的access_token和timeout。

本质上，您之前编写的方法可以被视为

class MyCrm {

    function refreshToken($client_id, $client_secret, $refresh_token) {
        // This is only a sample implementation
        $response = $your_curl_lib->post("/token?refresh_token={$refresh_token}&client_id= {$client_id}&client_secret={$client_secret}&grant_type=refresh_token");
        return ['access_token' => $response['access_token'], 'timeout' => $response['expiry_in_secs']];
    }

    function search($record) {
        try {
            // Your crm search api
        } catch(\Exception $e) {
            if ($e->getCode() === 401) {
                list($accesstoken, $expiry) = $this->refreshToken($clientid, $clientsecret, $refreshtoken);
                // Set access token in headers using your curl library
                // Your crm search api (again)
            } else {
                // throw all other exceptions as they are
                throw $e;
            }
        }
    }
}

待办事项

实现以下测试用例

• 单元测试
• 集成测试