README

简介

这个库作为 Pipeliner REST API 的便捷包装器。您还可以查看各类 API 文档。

安装

安装此库的推荐方法是使用 composer。将 "pipelinersales/pipeliner-api-client": "~1.0" 添加到您的 composer.json 文件中的依赖项。

另一种方法是手动下载源代码并包含 manual/pipeliner.php 文件。这将使用捆绑的自动加载器加载所有库的类。

此库需要 PHP >= 5.3 且具有 cURL 扩展。

基本用法

创建客户端对象

API 客户端对象创建方式如下

use PipelinerSales\ApiClient\PipelinerClient;

$url        = 'https://eu.pipelinersales.com';
$pipelineId = 'eu_myPipeline';
$token      = 'api token';
$password   = 'api password';

$pipeliner = PipelinerClient::create($url, $pipelineId, $token, $password);

特定管道的 API 令牌和密码可以在客户门户的 销售管道 → API 访问 部分找到。

create 方法发送 HTTP 请求以获取现有实体类型。

加载数据

可以通过直接提供请求项目的 ID（使用 getById 方法）或使用 get 方法进行查询来检索所有数据。

try {
    // load all accounts (up to a maximum of 25)
    $pipeliner->accounts->get();

    // load a specified account by id
    $pipeliner->accounts->getById('ID-219034053254');

}catch (PipelinerHttpException $e) {
    // something went wrong
}

对于未明确指定限制的查询，将返回最多 25 个项目。

getById 方法返回一个 Entity 对象。有关如何使用这些对象的详细信息，请参阅与实体一起工作部分。使用 get 方法返回一个 EntityCollection 对象，可以像常规 PHP 数组一样访问。

在出现错误时，库会抛出 PipelinerClientException 或其子类。有关更多信息，请参阅此文档的错误处理部分。

系统中的数据类型

系统的实体类型取决于正在处理的管道版本。版本 9 到 15 由当前库版本支持。可以通过调用 $pipeliner->getPipelineVersion() 获取管道版本。

实体列表及其描述可以在 API 文档中找到，网址为 http://workspace.pipelinersales.com/community/api/

也可以通过调用 $pipeliner->getEntityTypes() 在代码中获得完整列表。

在代码中，实体通过客户端对象的可用属性（存储库）获取。此类属性的名称通常是实体名称的复数形式，并以驼峰式书写，因此类型为Account的实体可以通过$pipeliner->accounts等访问。您还可以通过getRepository方法获取存储库。

存在一些例外于这个驼峰式复数规则。可用存储库的完整列表可在PipelinerClient类文档中的魔法属性摘要中查看。

查询

要检索的项目标准由服务器API文档中描述的属性组成。手动构建查询字符串很麻烦。库提供了几个便利类，使代码更易于阅读并更易于使用。这些类位于PipelinerSales\ApiClient\Query命名空间中。

您可以通过几种方式指定查询标准。完整列表可在get方法文档中找到。

// load up to 10 accounts and sort them by the organization name
$pipeliner->accounts->get(array('limit' => 10, 'sort' => 'ORGANIZATION'));

// load up to 5 accounts which were modified in the last week
$criteria = new Criteria();
$criteria->limit(5)->after(new DateTime('-7 days midnight'));
$pipeliner->accounts->get($criteria);

// load accounts whose organization name contains the string 'co'
$pipeliner->accounts->get(Filter::contains('ORGANIZATION', 'co'));

// load up to 10 accounts whose name starts with the letter A ordered by name in an ascending order
$pipeliner->accounts->get(
    Criteria::limit(10)->filter(Filter::startsWith('A'))->sort('NAME')
);

处理实体

实体由Entity类表示。它们的字段可以通过几种方式访问

直接使用字段名，通过getField和setField方法。请注意，所有标准字段都具有大写名称，而自定义字段可以包含小写字母和其他字符。
使用魔法获取器/设置器。这些将方法名称映射到字段名称，通过将驼峰式部分转换为上标并添加必要的下划线。
使用数组访问运算符，例如$entity['OWNER_ID'] = 3454;

魔法获取器/设置器通常是访问字段的推荐方法。自定义字段应使用getField/setField方法设置

$account = $pipeliner->accounts->getById('ID-219034053254');
echo $account->getOrganization() . "\n";
echo $account->getEmail1() . "\n";

$account->setPhone1('+100000000000')
        ->setOwnerId(1534);

除了字符串和数字之外，所有这些方法都将自动将DateTime对象转换为服务器期望的格式。如果日期/时间尚未转换为UTC，它还将转换为UTC。

修改和保存数据

在设置实体的一些字段后，必须使用适当存储库对象的save方法将实体保存到服务器。

$account = $pipeliner->accounts->getById('ID-219034053254');
$account->setEmail1('email@example.com')
        ->setPhone1('+100000000');
$pipeliner->accounts->save($account);

默认情况下，只有代码中已修改的字段才会发送到服务器。此行为可以通过save方法的第二个参数来更改。在成功保存后，所有字段都将重置为未修改。

如果您有一个不知道类型的实体对象，可以通过调用$pipeliner->getRepository($entity)来获取适当的存储库。

创建新实体

使用存储库的create方法创建新实体。就像修改数据一样，它们将不会在调用save方法之前发送到服务器。

$salesUnit = $pipeliner->salesUnits->create();
$salesUnit->setSalesUnitName('Aq');
$pipeliner->salesUnits->save($salesUnit);

保存成功后，实体对象的ID字段将被设置为新实体对象的ID。您也可以通过提供一个包含所有字段和值的关联数组来创建实体。

$response = $pipeliner->salesUnits->save(
    array( 'SALES_UNIT_NAME' => 'Aq' )
);

在成功的情况下，返回的响应将是一个 CreatedResponse 对象。可以通过调用此对象的 getCreatedId 方法来获取新实体的id。

删除实体

$pipeliner->salesUnits->deleteById('ID-219034053254');

$account = $pipeliner->accounts->getById('ID-342534523462');
$pipeliner->accounts->delete($account);

$pipeliner->accounts->deleteById(
    array('ID-219034053254', 'ID-3456134218434', 'ID-0186703160934')
);

使用集合

当使用 get 方法一次性加载多个实体时，它的返回值将是一个 EntityCollection 对象。对于大多数用途，它就像一个常规的PHP数组（它扩展了PHP的ArrayObject类），但与数组相比，它包含一些关于查询的额外信息。

$collection = $pipeliner->accounts->get();

// entity collections can be accessed like arrays
$firstAccount = $collection[0];

foreach ($collection as $account) {
    // do something with each account
}

一个重要的区别是，EntityCollection 对象是不可变的（尽管它们内部的元素本身是可变的）。

$accounts = $pipeliner->accounts->get();

// this is allowed
$accounts[0]->setEmail1('example@example.com');

// this throws an exception
$accounts[0] = $pipeliner->accounts->getById('ID-3452134134');

如果您需要一个可变数组，可以使用 getArrayCopy 方法获取集合底层数组的副本。

全范围迭代器

当加载多个实体时，Pipeliner的REST API允许您通过指定limit和offset查询参数来限制检索的数据仅限于结果的一部分。

EntityCollectionIterator 类提供了一种方便的方法，可以迭代整个匹配结果的范围（而无需限制）同时只获取部分数据。

// default limit 25 items
$accounts = $client->accounts->get();

$accountIterator = $client->accounts->getEntireRangeIterator($accounts);

$emails = array();
// this will iterate over ALL of the results (even beyond the 25)
foreach ($accountIterator as $account) {
    $emails[] = $account->getEmail1();

    if (!$accountIterator->nextDataAvailable() and !$accountIterator->atEnd()) {
        // next iteration will issue a HTTP request
    }
}

最初，迭代器从返回EntityCollection的请求中使用的偏移量开始。

此类实现了 SeekableIterator 接口，允许您任意移动通过结果集。需要时将数据从服务器获取。当前加载的数据将在新数据加载时被丢弃，因此建议以最小化发出的HTTP请求数量的方式使用此类。

错误处理

库使用异常进行错误处理。它使用的基异常类型是 PipelinerClientException，其他类型继承自它。

如果服务器返回错误响应，将抛出 PipelinerHttpException。如果响应包含来自服务器的错误信息，可以使用 getErrorMessage 和 getErrorCode 方法来读取这些信息。这些信息也将是标准异常消息的一部分。

try {
    $account = $pipeliner->accounts->create();
    
    // mandatory fields in the account are empty, so the server will refuse to save it
    $pipeliner->accounts->save($account);
}catch (PipelinerHttpException $e) {
    echo $e->getErrorMessage();
}

pipelinersales / pipeliner-api-client

维护者

详细信息