README

Pardot 是一个 PHP 实现的 Pardot API 连接器。它简化了对 Pardot 提供的所有 API 端点的访问。这可以用来构建自定义 CRM 连接器。

通过 Composer 包 hgg/pardot 安装

目标

提供一个单一的方法来执行任何 Pardot 端点的操作
解析响应并仅返回数据（解码 JSON 的 PHP 数组或 SimpleXmlElement）
处理错误

注意该库不完全支持 XML 格式。我不使用 XML，也没有时间更新 XML 解析器。

依赖项

Guzzle - PHP HTTP 客户端
Collections - 常见数据结构的优秀实现
parameter-validator - 参数验证库

约定

Pardot API 应该通过 POST 访问所有操作（Pardot 推荐）。大部分 API 不使用标准的 HTTP 响应代码来传达请求的结果，而是始终返回 2** 响应代码，并返回它自己的状态码集，需要处理。此连接器捕获状态码和消息，并抛出包含此信息的异常。如果需要处理单个案例，可以通过捕获异常并从中提取错误代码来实现。

库发出的所有异常都实现了 ExceptionInterface。在 HTTP 层抛出的任何异常都封装在 RequestException 中。

有关详细信息，请参阅错误处理。

使用方法

创建连接器实例

构造函数的第一个参数是包含连接器初始化参数的关联数组。

必需

email - 用户账户的电子邮件地址
user-key - 用户账户的用户密钥
password - 账户密码

可选

format - 内容格式。Pardot 支持 json 和 xml。默认 json
output - 返回的详细信息级别。可能的值是 full、simple、mobile。默认 full
api-key - 如果 API 密钥被缓存，可以将其注入到构造函数中。默认 null

第二个参数是可选的，是 Guzzle\Http\Client 的实例。默认情况下，Guzzle\Http\Client 使用指数退避插件实例化。它配置了 5 次重试（在 2、4、8、16 和 32 秒后）。如果不希望这些设置，可以在构造函数中注入客户端实例，带有所需设置/插件。

第三个参数是可选的，是 Guzzle 客户端 post 方法的选项数组。默认是 array('timeout' => 10)，这设置了客户端的超时时间为 10 秒。

<?php

use HGG\Pardot\Connector;
use HGG\Pardot\Exception\PardotException;

$connectorParameters = array(
    'email'    => 'The email address of the user account',
    'user-key' => 'The user key of the user account (in My Settings)',
    'password' => 'The account password',
    'format'   => 'json',
    'output'   => 'full'
);

$connector = new Connector($connectorParameters);

创建一个潜在客户

创建潜在客户所需的最小参数/字段集合是潜在客户的电子邮件地址。这将创建一个潜在客户并返回完整的潜在客户记录作为PHP数组，因为连接器是以format = json和output = full实例化的。如果格式设置为xml，则方法将返回一个SimpleXmlElement实例。

<?php

$response = $connector->post('prospect', 'create', array('email' => 'some@example.com'));

prospect是将被访问的对象，而create是对该对象执行的操作。第三个参数是要设置的字段的关联数组。

$response将是一个表示记录的数组（键是字段名，值是那些字段的值）

读取潜在客户

使用电子邮件地址作为标识符

<?php

$response = $connector->post('prospect', 'read', array('email' => 'some@example.com'));

使用Pardot ID作为标识符

<?php

$response = $connector->post('prospect', 'read', array('id' => '12345'));

$response将是一个表示记录的数组（键是字段名，值是那些字段的值）

查询潜在客户

<?php

$queryParameters = array(
    'created_after' => 'yesterday',
    'limit'         => 200,
    'offset'        => 0
);

$response = $connector->post('prospect', 'query', $queryParameters);

// Obtain the total record count of the query from the connector
// If this is larger than the limit make requests (increasing the offset each
// time) until all records have been fetched
$count = $connector->getResultCount();

如果查询结果超过200条记录，并且请求的限制设置为200，则必须进行多次请求以获取整个结果集。限制默认为200，不能更大。作为单个查询的一部分的每个请求将返回一个记录集合/数组，即使集合中只包含一个记录。请注意，Pardot API本身不执行此操作。

错误处理

所有库异常都实现了共同的ExceptionInterface接口。

异常层次结构

所有库异常都扩展了共同的SPL异常。

\Exception
  |
  |- ExceptionCollection
  |
  |- \LogicException
  |    |- \InvalidArgumentExcpetion
  |         |- InvalidArgumentExcpetion
  |
  |- \RuntimeException
       |- RuntimeException
           |- AuthenticationErrorException
           |- RequestException

将抛出以下异常

AuthenticationErrorException

当对Pardot API进行身份验证失败时。

ExceptionCollection

当Pardot API返回错误代码10000时，可以包含多个错误。

InvalidArgumentException

类型错误，例如传递无效的Connector构造参数。

RequestException

由HTTP层（GuzzlePHP的HTTPException）发出的异常被包装在RequestException中。

RuntimeException

来自Guzzle的所有非HTTPExceptions和非身份验证错误以及Pardot API返回的所有非身份验证错误。

示例

捕获任何HGG\Pardot库异常

如果不需要或需要特定的错误处理，只需使用此作为通用错误处理。

<?php

use HGG\Pardot\Exception\ExceptionInterface;

try {
    // Pardot library code
} catch (ExceptionInterface $e) {
    // Handle it here
}

获取有用的日志信息

所有库异常都允许您获取被调用的URL以及发送的参数。这有助于识别问题。

<?php

use HGG\Pardot\Exception\RuntimeException;

try {
    $connector->post('prospect', 'update', $parameters);
} catch (RuntimeException $e) {
    printf('Error Message: %s', $e->getMessage());
    printf('Error code:    %d', $e->getCode()); // Pardot Error code
    printf('url:           %s', $e->getUrl());
    printf("Parameters:\n%s", print_r($e->getParameters(), true));
}

hgg / pardot

维护者

详细信息