README

用法

composer require shadoll/orchid

这是什么

这是连接到联系人信息存储服务（以下简称服务）的客户端。它提供了简单的获取、更新、添加和删除联系人信息的功能。服务orchid。

客户端

要开始使用，需要创建客户端 \Orchid\Client。

$client = new \Orchid\Client();
// или
$client = new \Orchid\Client('https://YOUR.SERVER', 'eyJ0eXAiOiJKV1Q....');

在这种情况下，客户端将尝试在环境变量 ORCHID_SERVER 中找到服务器值，在 ORCHID_TOKEN 中找到令牌。 (您可以通过在服务上授权或通过服务仪表板获取令牌)

如果最终在构造函数中未定义变量，将抛出 \Orchid\Exceptions\OrchidException 异常。在任意请求（查询、更改、...）中可能会抛出异常。请处理它们。

所有可能拥有多个模型的数据都将存储在 \Orchid\Core\Collection 集合中。

我们可以从客户端获取 Orchid\Models\Contact 和 Orchid\Models\Source 模型的实例。

// client
/**
 * @var \Orchid\Models\Source $source
 */
$source = $client->sources();

/**
 * @var \Orchid\Models\Contact $contact
 */
$contact = $client->contacts();

处理源（Source）

任何拥有所需 scopes（local）令牌的用户都可以获取源，只有拥有 scopes -> superuser 的用户才能添加、更改和删除源。

// client
/**
 * @var \Orchid\Models\Source $source
 */
$source = $client->sources();

/** получить все источники
 * @var \Orchid\Core\Collection $collect
 */
$collect = $source->get();

/** получить источник по его UUID
 * @var \Orchid\Models\Source $model
 */
$model = $source->find('__UUID__');

// дальше только для Superuser

// Создание источника
$source1 = new \Orchid\Models\Source($client->getHttpClient(), [
    'name' => 'Jarvis source',
    'code' => 'jarvis_code',
]);

$source2 = new \Orchid\Models\Source($client->getHttpClient());
$source2->name = 'Google source';
$source2->code = 'google_code';

$source1->save();
$source2->save();

// Обновление источника
$model = $source->find('__UUID__');

$model->name = 'Updated Jarvis Name';

$model->save();

// Удаление источника
$model = $source->find('__UUID__');

$model->destroy();

处理联系人（Contact）

普通用户（拥有 scopes -> local）只能操作自己的联系人，拥有 scopes -> superuser 的用户可以操作任何联系人。（不建议将该用户用于客户端解决方案）

查询

// client
/**
 * @var \Orchid\Models\Contact $contact
 */
$contact = $client->contacts();

/** получить все контакты (получите обьект пагинации)
 * @var \Orchid\Core\Paginate $paginate
 */
$paginate = $contact->get();
// или с фильтрацией
$paginate = $contact->where(function (\Orchid\Core\Build\ContactBuilder $builder) {
    $builder
        ->source('6a7e5826-f202-4678-99fb-e69bae8a1d5d')
        ->search('80999999999')
        ->mask(true);
})->get();

/** получить контакт по его UUID
 * @var \Orchid\Models\Contact $model
 */
$model = $contact->find('__UUID__');

由于用户可能有大量联系人，因此查询将按100个一组进行。返回 \Orchid\Core\Paginate 对象。处理 \Orchid\Core\Paginate

/** получить все контакты (получите обьект пагинации)
 * @var \Orchid\Core\Paginate $paginate
 */
$paginate = $contact->get();

/** получить контакты текущей страницы (пагинации)
 * @var \Orchid\Core\Collection<\Orchid\Models\Contact> $collection
 */
$collection = $paginate->data;

/** получить все контакты (получите обьект пагинации) для следующей страницы
 * @var \Orchid\Core\Paginate $paginateNext
 */
$paginateNext = $paginate->next();

/** получить все контакты (получите обьект пагинации) для предыдущей страницы
 * @var \Orchid\Core\Paginate $paginatePrev
 */
$paginatePrev = $paginate->prev();

/** получить все контакты (получите обьект пагинации) для конкретной страницы
 * @var \Orchid\Core\Paginate $paginateFive
 */
$paginateFive = $paginate->page(5);

// еще доступны last(), first(), pages(), total(), currentPage(), inPage()
// для работы с пагинацией.

---

创建联系人

// client
/**
 * @var \Orchid\Models\Contact $contact
 */
$contactInstance = $client->contacts();

$source = $client->sources()->get()->first();

$contact = new \Orchid\Models\Contact($client->getHttpClient(), [
    'name' => 'Jarvis',
    'phone' => ['0999999999', '0988888888'],
    'email' => ['jarvis@google.com', 'jarvis.2@google.com'],
]);

$contact->save($source->id);

// Массовое создание

$collect = new \Orchid\Core\Collection([
    (new \Orchid\Models\Contact($client->getHttpClient(), [
        'name' => 'Jarvis',
        'phone' => ['0999999999', '0988888888'],
        'email' => ['jarvis@google.com', 'jarvis.2@google.com'],
    ]))->remoteID('amo_id'),
    new \Orchid\Models\Contact($client->getHttpClient(), [
        'name' => 'Jarvis 2',
        'phone' => ['0999999998', '0988888889'],
        'email' => ['jarvis_2@google.com', 'jarvis.3@google.com'],
    ]),
]);

// 1 способ - через инстанс . (обязательно UUID или code источника)
$contactInstance->store($source->id, $collect);

// 2 способ - через коллекцию . (обязательно UUID или code источника)
$collect->store($source->code);

// superuser может создать контакты для любого пользователя

$contact->save($source->id, '__UUID_USER__');

$contactInstance->store($source->id, $collect, '__UUID_USER__');

$collect->store($source->code, '__UUID_USER__');

返回包含两个集合的数组 ['resolved' => Collection, 'rejected' => Collection]

更新联系人

// client
/**
 * @var \Orchid\Models\Contact $contact
 */
$contactInstance = $client->contacts();

$contact = $contactInstance->find('__UUID__');
$contact->phone = ['0977777777'];
$contact->replace(['phone']); // это отвяжет все предыдущие телефоны и привяжет только новый
$contact->save();

// Массовое обновление

$collect = $contactInstance->where(/* filter Closure */)->get();

$collect->each(function($item) {
    if (in_array('0999999999', $item->phone)) {
        $item->replace(['phone', 'email']);
    }
    $item->phone = ['0988888777'];
    // ...
});

// 1 способ - через инстанс 
$contactInstance->update($collect);

// 2 способ - через коллекцию 
$collect->update();

返回包含两个集合的数组 ['resolved' => Collection, 'rejected' => Collection]

删除联系人

// client
/**
 * @var \Orchid\Models\Contact $contact
 */
$contactInstance = $client->contacts();

$contact = $contactInstance->find('__UUID__');
$contact->destroy();

// Массовое удаление

$collect = $contactInstance->where(/* filter Closure */)->get();

$filteredCollect = $collect->filter(function($item) {
    return in_array('0999999999', $item->phone);
});

// 1 способ - через инстанс 
$contactInstance->destroy($filteredCollect);

// 2 способ - через коллекцию 
$filteredCollect->destroy();