README

通过推荐码/链接贡献

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

pdp-devio

考虑捐赠

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

此包提供了一个完全不受框架限制的Pipedrive CRM API客户端库，适用于PHP。它包含Pipedrive文档上列出的所有资源。

重要：如果您使用Laravel >= 5.8，请确保您的版本大于2.1.0。

请随时通过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 添加到 providers 数组中，并注册 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 贡献。

devio / pipedrive

维护者

详细信息