README

使用愉快、类似于 Eloquent 的开发体验与 HubSpot 的 CRM 交互。

• 熟悉的 Eloquent CRUD 方法 create、find、update 和 delete
• 关联对象就像关系一样工作：Deal::find(555)->notes 和 Contact::find(789)->notes()->create(...)
• 检索对象列表就像查询构建器：Company::where('state','NC')->orderBy('custom_property')->paginate(20)
• 游标提供了一种无缝遍历所有记录的方法：foreach(Contact::cursor() AS $contact) { ... }

注意 目前仅实现了 CRM API。

安装

1) 使用 composer 安装包

composer require stechstudio/laravel-hubspot

2) 配置 HubSpot

创建一个私有的 HubSpot 应用 并为 SDK 设置适当的权限。

复制提供的访问令牌，并添加到您的 Laravel .env 文件中

HUBSPOT_ACCESS_TOKEN=XXX-XXX-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

用法

单个 CRUD 操作

检索

您可以使用任何对象类的 find 方法并传入 ID 来检索单个对象记录。

use STS\HubSpot\Crm\Contact;

$contact = Contact::find(123);

创建

要创建新的对象记录，请使用 create 方法并传入属性数组。

$contact = Contact::create([
    'firstname' => 'Test',
    'lastname' => 'User',
    'email' => 'testuser@example.com'
]);

或者您也可以先创建类，一次提供属性，然后 save。

$contact = new Contact;
$contact->firstname = 'Test';
$contact->lastname = 'User';
$contact->email = 'testuser@example.com';
$contact->save();

更新

一旦检索或创建了对象，使用 update 方法并传入要更改的属性数组进行更新。

Contact::find(123)->update([
    'email' => 'newemail@example.com'
]);

您也可以逐个更改属性然后 save。

$contact = Contact::find(123);
$contact->email = 'newemail@example.com';
$contact->save();

删除

这将“存档” HubSpot 中的对象。

Contact::find(123)->delete();

检索多个对象

从 API 获取对象集合与直接查询数据库不同，您一次可以获取的项目数量是有限的。如果您有成千上万的联系信息，不能要求 HubSpot 返回所有联系信息。

此包提供了三种不同的方法来获取这些结果。

分页

类似于传统数据库分页结果，您可以通过 HubSpot 对象集合进行分页。您将收到与 Eloquent 一样的 LengthAwarePaginator，这意味着您可以在 UI 中生成链接，就像您所习惯的那样。

$contacts = Contact::paginate(20);

默认情况下，此 paginate 方法将查看 page 查询参数。您可以通过传递一个字符串作为第二个参数来自定义查询参数键。

游标迭代

您可以使用 cursor 方法遍历整个对象集合。这使用 延迟集合 和 生成器 以无缝地从 API 按需获取记录块，当需要时填充对象，并提供在无限数量的对象上平滑迭代的方法。

// This will iterate over ALL your contacts!
foreach(Contact::cursor() AS $contact) {
    echo $contact->id . "<br>";
}

警告 API 速率限制在使用此方法时可能成为障碍。注意快速迭代大型数据集，因为这仍然需要在后台进行相当多的 API 调用。

手动获取块

当然，您可以使用自己的手动分页或块逻辑来获取记录集合。使用 take 和 after 方法指定要获取的内容，然后 get。

// This will get 100 contact records, starting at 501
$contacts = Contact::take(100)->after(500)->get();

// This will get the default 50 records, starting at the first one
$contacts = Contact::get();

搜索和筛选

在检索多个对象时，您通常会想要过滤、搜索和排序这些结果。在检索结果之前，您可以使用流畅的接口构建查询。

添加过滤器

使用 where 方法向查询中添加过滤器。您可以使用任何支持的运算符作为第二个参数，完整列表请参见此处：https://developers.hubspot.com/docs/api/crm/search#filter-search-results;

此包还提供了常见运算符的友好别名，例如 =、!=、>、>=、<、<=、exists、not exists、like 和 not like。

Contact::where('lastname','!=','Smith')->get();

您可以省略运算符参数，默认使用 =。

Contact::where('email', 'johndoe@example.com')->get();

对于 BETWEEN 运算符，以一个包含两个元素的元组的形式提供下限和上限。

Contact::where('days_to_close', 'BETWEEN', [30, 60])->get();

注意 所添加的过滤器都作为“AND”过滤器分组，并一起应用。目前尚不支持可选的“OR”分组。

搜索常用属性

HubSpot 支持轻松地搜索某些对象的属性。详细信息请参见此处

https://developers.hubspot.com/docs/api/crm/search#search-default-searchable-properties

使用 search 方法指定搜索参数

Contact::search('1234')->get();

排序

您可以使用任何属性对结果进行排序。

Contact::orderBy('lastname')->get();

默认方向是 asc，如果需要，您可以将其更改为 desc。

Contact::orderBy('days_to_close', 'desc')->get();

关联

HubSpot 关联的处理方式类似于 Eloquent 关系。

动态属性

您可以使用动态属性访问关联对象。

foreach(Company::find(555)->contacts AS $contact) {
    echo $contact->email;
}

关联方法

如果您需要添加额外的约束，请使用关联方法。您可以添加上述描述的任何过滤、搜索或排序方法。

Company::find(555)->contacts()
    ->where('days_to_close', 'BETWEEN', [30, 60])
    ->search('smith')
    ->get();

预加载关联 ID

通常，需要三个 HubSpot API 调用才能实现上述结果

1. 获取公司对象
2. 检索与该公司关联的所有联系人 ID
3. 查询与 ID 匹配的联系人

现在我们可以通过预加载关联的联系人 ID 来消除第二个 API 调用。此库始终预加载关联公司、联系人、交易和票据的 ID。它不会预加载类似电子邮件和笔记这样的关联 ID，因为这些关联列表通常会更长。

如果您预先知道您想要检索某个联系人的笔记，例如，您可以在一开始就指定这个。

// This will only be two API calls, not three
Contact::with('notes')->find(123)->notes;

创建关联对象

您可以使用关联方法创建新记录。

Company::find(555)->contacts()->create([
    'firstname' => 'Test',
    'lastname' => 'User',
    'email' => 'testuser@example.com'
]);

这将创建一个新的联系人，将其关联到公司，并返回新的联系人。

您还可以使用 attach 方法关联现有的对象。此方法接受 ID 或对象实例。

Company::find(555)->contacts()->attach(Contact::find(123));

您还可以使用 detach 方法分离现有的对象。此方法接受 ID 或对象实例。

Company::find(555)->contacts()->detach(Contact::find(123));

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。