README

此包将处理与 Petri API 服务的集成

• 安装
• 常见概念
  • CRMObject 方法
  • BaseModel 方法
• 常见异常
• 初始化
• 客户
• 组织
• 交易
• 内容管理 - 站点
• 内容管理 - 页面
• 内容管理 - 页面类型
• 内容管理 - 页面属性
• 实用示例

安装

composer require meiosis-io/amino

常见概念

Meiosis\Amino 类的方法都将返回扩展 Meiosis\CRMObject 的实例。这些对象与其相应的 API 端点进行交互，并应返回扩展 Meiosis\Models\BaseModel 的项目。例如，要从内容管理系统获取名称包含文本 "Press Release" 的页面列表，我们的代码可能如下所示

$amino = new Meiosis\Amino($token, $team);
$pages = $amino
    ->pages($siteId)
    ->search([
        'name' => 'Press Release'
    ]);

在这种情况下，$pages 现在是一个数组，其项是 Meiosis\Models\Page 对象的实例。这些对象上的任何属性都是直接可用的

// Show a list of the our page names:
foreach ($pages as $page) {
    echo $page->name;
}

CRMObject 方法

以下方法可用于扩展 Meiosis\Endpoints\CRMObject 类的任何对象，例如 Meiosis\Amino 类上的方法返回的对象。

->find($identifier)

给定一个标识符，find 方法将返回一个扩展 Meiosis\Models\BaseModel 的对象

->search($searchArray)

给定一个格式为 ['key' => 'value'] 的搜索参数数组，search 方法将返回一个扩展 Meiosis\Models\BaseModel 的对象数组

->blueprint()

blueprint 方法将返回适当实现的 Meiosis\Models\BaseModel 的新实例。例如，一个全新的客户将看起来像这样

$amino = new Meiosis\Amino($token, $team);
$newCustomer = $amino->customers()->blueprint();

->save($object)

传递给 save 方法的对应 Meiosis\Models\BaseModel 的实现将创建一个新对象（如果尚不存在），或将更新现有对象。每个 BaseModel 对象都存在一个到该方法的快捷方式，通过它自己的内部 ->save() 方法。例如，以下两个代码块达到相同的效果

$amino = new Meiosis\Amino($token, $team);
$customer = $amino->customers()->find($customerID);
// Save the customer
$amino->customers->save($customer);

$amino = new Meiosis\Amino($token, $team);
$customer = $amino->customers()->find($customerID);
// Save the customer
$customer->save();

->delete($identifier)

给定一个标识符，从系统中删除记录。

->payload($data)

构建 APIClient 所需的负载。此方法主要在内部使用，但公开可用。

BaseModel 方法

以下方法可用于扩展 Meiosis\Models\BaseModel 类的任何对象，例如 Meiosis\Endpoints 中的类返回的对象

::getNativeFields()

静态 getNativeFields 方法将返回每个 BaseModel 上的 $native 数组。这用于构建新方法，或者当您想将本地属性与自定义属性组合时使用。

->populate($data)

使用从 $data 数组中的数据填充对象实例。

->extract()

将对象转换为数组，提取底层的 $data 数组

->save()

创建或更新对象，并以任何新字段（id、时间戳等）重新填充它

->refresh()

重新加载对象，从 API 获取新鲜数据

常见异常

• Meiosis\Exceptions\ObjectNotFoundException - API 返回了 404 / Not Found 错误。
• Meiosis\Exceptions\InvalidEndpointException - 发送了格式错误的请求，无法猜测端点。检查您提供的参数。
• Meiosis\Exceptions\ObjectNotPopulatedException - SDK 尝试保存对象的更改，但该对象未填充
• Meiosis\Exceptions\ObjectValidationFailedException - API 遇到 422 错误，表示提供的参数无效。
• Meiosis\Exceptions\UseOtherMethodException - API 端点不支持您尝试使用的方（例如，更新现有交易）。
• Meiosis\Exceptions\UnknownApiException - 与 API 通信时遇到 500 错误。您应该再次尝试您的请求。

初始化

您需要初始化 Amino 类的新实例，并提供 API 令牌和团队 ID。

$amino = new Meiosis\Amino($token, $team);

如果您想确保您的服务器能够正确地访问 API，您可以调用远程测试函数。

$amino = new Meiosis\Amino($token, $team);
return $amino->remoteTest();

客户

要处理客户，请在 Amino 类上调用 customers() 方法。返回的模型是 Meiosis\Models\Customer 类的实例。

$amino = new Meiosis\Amino($token, $team);
$customers = $amino->customers();

其他方法

除了在 CRMObject 方法 中提到的之外，以下方法也存在

->trackInteraction($customer, $source, $description, $priority)

给定一个 Meiosis\Models\Customer 对象（《$customer》），此方法将从源《$source》记录一个交互，描述为《$description》，默认《$priority》为 5。

组织

要处理组织，请在 Amino 类上调用 organizations() 方法。返回的模型是 Meiosis\Models\Organization 类的实例。

$amino = new Meiosis\Amino($token, $team);
$organizations = $amino->organizations();

交易

要处理交易，请在 Amino 类上调用 transactions() 方法。返回的模型是 Meiosis\Models\Transaction 类的实例。

$amino = new Meiosis\Amino($token, $team);
$transactions = $amino->transactions();

特殊情况

->search($searchArray)

交易不可搜索。此方法将抛出 Meiosis\Exceptions\InvalidEndpointException 异常。

->save()

虽然可以保存新交易，但不能更新现有交易。一旦记录，交易就不能更新，但可以取消。

内容管理 - 站点

要处理站点，请在 Amino 类上调用 sites() 方法。返回的模型是 Meiosis\Models\Site 类的实例。

$amino = new Meiosis\Amino($token, $team);
$sites = $amino->sites();

内容管理 - 页面

要处理页面，请在 Amino 类上调用 pages() 方法，并传递站点令牌/ID。返回的模型是 Meiosis\Models\Page 类的实例。

$amino = new Meiosis\Amino($token, $team);
$siteToken = '12345-12345-123-12345';
$pages = $amino->pages($siteToken);

其他方法

除了 CRMObject 方法中提到的之外，以下方法也存在

->getHierarchy($pageID)

getHierarchy 方法接受一个可选的 $pageID 参数。如果没有 $pageID，它将返回一个包含简单 Meiosis\Models\Page 对象的数组，包括其子对象，从页面层次结构的根级别开始。如果传递了 $pageID，则返回的数组将包含匹配的页面作为唯一的根页面。

->bySlug($slug)

给定一个 $slug，bySlug 方法将返回一个匹配给定 slug 的页面数组。slug 应尽可能具体，包括父级。例如，一个 slug 为 my-page 的页面是 about-us 页面的子页面，可以通过以下方式找到：->bySlug('about-us/my-page');

->setSiteToken($token)

setSiteToken 方法可以用来更改类正在使用的站点。

内容管理 - 页面类型

要处理页面类型，请在 Amino 类上调用 pageTypes() 方法，并传递站点令牌/ID。返回的模型是 Meiosis\Models\PageType 类的实例。

$amino = new Meiosis\Amino($token, $team);
$siteToken = '12345-12345-123-12345';
$pageTypes = $amino->pageTypes($siteToken);

其他方法

除了 CRMObject 方法中提到的之外，以下方法也存在

->setSiteToken($token)

setSiteToken 方法可以用来更改类正在使用的站点。

内容管理 - 页面属性

要处理页面属性，请在 Amino 类上调用 pageAttributes() 方法，并传递页面类型 ID。返回的模型是 Meiosis\Models\PageAttribute 类的实例。

$amino = new Meiosis\Amino($token, $team);
$siteToken = '54321-54321-543-54321';
$pageType = '12345-12345-123-12345';
$pageAttributes = $amino->pageAttributes($siteToken, $pageType);

其他方法

除了 CRMObject 方法中提到的之外，以下方法也存在

->all()

返回所有 PageAttributes 的数组，针对页面类型。

实用示例

创建新的客户并跟踪交互

$amino = new Meiosis\Amino($token, $team);

$customer = $amino->customers()->blueprint();

$customer->first = "John";
$customer->last  = "Doe";
$customer->email = "jdoe@example.com";
$customer->save();

$amino->customers()->trackInteraction($customer, 'My Site', 'Filled out a form');

记录交易

$amino = new Meiosis\Amino($token, $team);
$customer = $amino->customers()->find('someemail@example.com');

// Create a transaction Object
$transaction = $amino->transactions()->blueprint();

// Alternatively, you can instantate a new transaction directly.
// You'll need to pass it an instance of the CRMTransaction endpoint
// in order to use it's ->save() method.
// $transaction = new Meiosis\Models\Transaction([], $amino->transactions());

// Attach the customer
$transaction->customer = $customer;

// Create an item
$item = new Meiosis\Models\TransactionItem();
$item->price = 5.00;
$item->quantity = 2.25;

// Add the item to the transaction
$transaction->addItem($item);

// Save the transaction
$transaction->save();

根据自定义属性获取页面

假设已创建具有键 attr_category 的自定义页面属性，我们将找到类别为 'news' 的所有页面

$amino = new Meiosis\Amino($token, $team);

$siteID = '12345-123-123-12345';
$pages = $amino->pages($siteID)->search([
    'attr_category' => 'news'
]);