README

通过推荐码/链接贡献

这不会花费太多时间。您可以使用我的推荐码或链接免费使用高达45天。只需使用此链接注册或将其代码添加到账单部分

考虑捐赠

您喜欢这个包吗？您觉得它有用吗？捐赠以支持其开发。

此包提供了一个完全框架无关的Pipedrive CRM API客户端库，用于PHP。它包括Pipedrive文档上列出的所有资源。

请随时通过israel@devio.es给我发消息，或通过@IsraelOrtuno发推文。

使用API令牌快速入门（以下为OAuth）

$token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxx';
$pipedrive = new Pipedrive($token);

// Easily access a Pipedrive resource and its values
$organization = $pipedrive->organizations->find(1);
var_dump($organization->getData());

// Also simple to update any Pipedrive resource value
$organization = $pipedrive->organizations->update(1, ['name' => 'Big Code']);
var_dump($organization->getData());

// Keep reading this documentation to find out more.

要深入了解如何使用此包，请遵循以下索引

安装
用法
- 创建Pipedrive实例
  - 使用API令牌
  - 使用OAuth
- 解析Pipedrive API资源
执行资源调用
可用资源
- 文件资源
在Laravel中配置和使用
贡献

重要

版本1.x不包括OAuth支持，请更新到版本2.x以使用此功能。

安装

您可以通过composer require命令安装此包

composer require devio/pipedrive

或者简单地将它添加到您的composer.json依赖关系中，然后运行composer update

"require": {
    "devio/pipedrive": "^2.0"
}

用法

创建Pipedrive实例

Devio\Pipedrive\Pipedrive类充当管理器，将负责解析不同的API资源。Pipedrive支持两种不同的认证方法：通过API令牌（用于手动集成）和通过OAuth（用于公共和私有应用程序）。您可以在官方文档中了解更多信息，这里：https://pipedrive.readme.io/docs/core-api-concepts-authentication

使用API令牌

$token = 'PipedriveTokenHere';
$pipedrive = new Pipedrive($token);

注意：请考虑将此对象存储到全局变量中。

使用OAuth

要了解OAuth流程的工作原理，请首先阅读文档。
您可以在以下位置找到它：https://pipedrive.readme.io/docs/marketplace-oauth-authorization

首先，您需要创建一个应用程序并检索client_id和client_secret。请阅读官方文档了解如何操作。
您可以在以下位置找到所有信息：https://pipedrive.readme.io/docs/marketplace-creating-a-proper-app

一旦您有了client_id、client_secret和redirect_url，您就可以像这样实例化类

$pipedrive = Pipedrive::OAuth([
    'clientId' => '<your-client-id>',
    'clientSecret' => '<your-client-secret>',
    'redirectUrl' => '<your-redirect-url>',
    'storage' => new PipedriveTokenIO() // This is your implementation of the PipedriveTokenStorage interface (example below)
]);

类将自动处理重定向到认证服务器和刷新令牌请求。

您需要提供的唯一内容是您自己的PipedriveTokenStorage接口实现。

此类的作用是读取和写入包含access_token、refresh_token和expiresAt的PipedriveToken对象，让您能够根据您的喜好处理这些信息（例如，将这些属性以您首选的方式存储）。

以下是一个示例实现

class PipedriveTokenIO implements \Devio\Pipedrive\PipedriveTokenStorage
{
    public function setToken(\Devio\Pipedrive\PipedriveToken $token) {
        $_SESSION['token'] = serialize($token); // or encrypt and store in the db, or anything else...
    }

    public function getToken() { // Returns a PipedriveToken instance 
        return isset($_SESSION['token']) ? unserialize($_SESSION['token']) : null;
    }
}

在这个简单示例中，PipedriveToken 仅存储在会话中，并从会话中检索。这意味着一旦会话过期，用户将被重定向到认证页面。

您可能希望将此对象存储在数据库中。序列化整个对象可能是最快的方式，但您也可以使用 getAccessToken、getRefreshToken 和 expiresAt 方法分别检索访问令牌、刷新令牌和过期时间。如下所示

public function setToken(\Devio\Pipedrive\PipedriveToken $token) {
    $token->getAccessToken(); // save it individually
    $token->getRefreshToken(); // save it individually
    $token->expiresAt(); // save it individually
}

同样，对象可以按如下方式实例化

$token = new \Devio\Pipedrive\PipedriveToken([
    'accessToken' => 'xxxxx', // read it individually from the db
    'refreshToken' => 'xxxxx', // read it individually from the db
    'expiresAt' => 'xxxxx', // read it individually from the db
]);

处理回调

在回调（您指定的 redirectUrl 中的 URL），您应该在 $pipedrive 对象上调用 authorize 方法，如下所示

if(!empty($_GET['code'])) {
    $pipedrive->authorize($_GET['code']);
}

这将用授权代码交换第一个访问令牌，并使用您提供的 setToken 方法存储它。

解析Pipedrive API资源

一旦我们有了 Pipedrive 实例，我们就能以多种方式解决任何 Pipedrive API 资源。

首先，您可以调用 make() 方法

// Organizations
$organizations = $pipedrive->make('organizations');
// Persons
$persons = $pipedrive->make('persons');
// ...

它还拦截了魔法方法 __get，因此我们可以这样做

// Deals
$deals = $pipedrive->deals;
// Activities
$activities = $pipedrive->activities;
// ...

如果您更喜欢 __call，您也可以使用它

// EmailMessages
$emailMessages = $pipedrive->emailMessages();
// GlobalMessages
$globalMessages = $pipedrive->globalMessages();
// ...

它们是三种不同的做同样的事情的方式，选择您最喜欢的一种。它会自动设置请求资源的 大驼峰命名法 版本，因此它将适用于 emailMessages、EmailMessages、email_messages...

重要提示：导航到 src/Resources 目录以查找所有可用的资源。

执行资源调用

可用方法

所有资源都提供各种方法来执行不同的 API 请求。请导航到您想要与之交互的资源类，以查找所有可用的方法。每个方法都有文档，也可以在 Pipedrive API 文档页面中找到。

每个资源都扩展自 Devio\Pipedrive\Resources\Basics\Resource，其中定义了最常用的方法。其中一些方法在未包含它们的资源中被禁用。不要忘记查看包含的特质，一些资源使用它们来定义一些其他常见调用，以避免代码重复。

执行请求

在解决我们想要使用的资源之后，我们能够执行 API 请求。在这种情况下，我们只需要执行我们想要访问的端点

$organizations = $pipedrive->organizations->all();
//
$pipedrive->persons->update(1, ['name' => 'Israel Ortuno']);

这些方法中的任何一个都会对 Pipedrive API 执行同步请求。

处理响应

每个 Pipedrive API 端点都会给出响应，并且此响应会被转换为一个 Devio\Pipedrive\Http\Response 对象来处理。

$response = $pipedrive->organizations->all();

$organizations = $response->getData();

响应方法

Response 类提供了许多用于访问响应数据的方法

`isSuccess()`

检查服务器是否成功响应了请求。

`getContent()`

将提供由 Pipedrive API 提供的原始响应。如果您需要特定的控制，这很有用。

`getData()`

获取响应主数据对象，该对象将包括我们正在调用的端点信息。

`getAdditionalData()`

一些响应包含一个附加数据对象，其中包含一些额外信息。使用此方法检索此对象。

`getStatusCode()`

获取响应状态码。

`getHeaders()`

获取响应头。

可用资源

每个资源的逻辑都位于 src/Resources 目录中。但是，我们会在下面提到每个包含的资源。

✅ 完成 / ⚠️ Pipedrive API 错误

文件资源

文件资源是唯一一个与其他资源略有不同的。其他资源可能可以直观地使用，因为它们中的大多数只需要一个纯数组的数据，而 File 资源需要 \SplFileInfo 实例才能工作。

$file = new \SplFileInfo('document.pdf');

$pipedrive->files->add([
    'file'   => $file,
    'person_id' => 1,
    // 'deal_id' => 1
]);

实际上，这相当简单。只需将 \SplFileInfo 实例传递到选项数组的 file 键中，并指定至少与一个元素相关的元素（交易、人物、...）。

在Laravel中配置和使用

如果您使用 Laravel，可以使用 PipedriveServiceProvider 和 PipedriveFacade，这将使使用此包更加舒适。

服务提供者和外观

在config/app.php中将PipedriveServiceProvider包含到提供者数组中，并注册Laravel Facade。

'providers' => [
  ...
  Devio\Pipedrive\PipedriveServiceProvider::class,
  ...
],
'alias' => [
    ...
    'Pipedrive' => Devio\Pipedrive\PipedriveFacade::class,
    ...
]

服务配置

Laravel 包含一个配置文件，用于存储外部服务信息，位于config/services.php。我们需在该文件中设置我们的Pipedrive令牌，如下所示

'pipedrive' => [
    'token' => 'the pipedrive token'
]

当然，和其他许多配置参数一样，您可以将令牌存储在您的.env文件或环境变量中，并使用dotenv获取它

'pipedrive' => [
    'token' => env('PIPEDRIVE_TOKEN')
]

使用它

您可以使用我们之前加载的Laravel Facade PipedriveFacade来使用它

$organizations = Pipedrive::organizations()->all();
//
Pipedrive::persons()->add(['name' => 'John Doe']);

或者，从服务容器中解析它

$pipedrive = app()->make('pipedrive');

或者在您可能需要的任何地方注入它，使用Devio\Pipedrive\Pipedrive签名。

贡献

请随时通过PR进行贡献。

kinow-io / pipedrive-laravel-55

维护者

详细信息