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

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

RequestException

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

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));
}

elfet-js/pardot

维护者

详细信息