README

这是一个对 Henning Glatter-Götz 的 Pardot-API-Wrapper 的分支，包含一些小改动，例如允许批量输出格式。

Pardot

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

通过 Composer 包 hgg/pardot 安装

目标

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

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

依赖项

Guzzle - PHP HTTP 客户端
Collections - 通用数据结构的一个很好的实现
parameter-validator - 参数验证库

约定

应该通过 POST 对 Pardot API 进行所有操作（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）发出的异常被包装在RequestExcpetion中。

RuntimeException

所有非HTTPExceptions来自Guzzle和非认证错误由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));
}

sw / pardot

维护者

详细信息