Skip to content

Commit 527e858

Browse files
bessudnovbessudnov
committed
readme and tags fixes
1 parent db154ea commit 527e858

File tree

2 files changed

+200
-17
lines changed

2 files changed

+200
-17
lines changed

‎README.md

+190-15
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,26 @@
22

33
В данном пакете представлен API клиент с поддержкой основных сущностей и авторизацией по протоколу OAuth 2.0 в amoCRM.
44

5+
## Оглавление
6+
- [Установка](#установка)
7+
- [Начало работы](#начало-работы-и-авторизация)
8+
- [Поддерживаемые методы и сервисы](#поддерживаемые-методы-и-сервисы)
9+
- [Обработка ошибок](#поддерживаемые-методы-и-сервисы)
10+
- [Фильтры](#Фильтры)
11+
- [Работа с Custom Fields сущностей](#работа-с-дополнительными-полями-сущностей)
12+
- [Работа с тегами сущностей](#работа-с-тегами-сущностей)
13+
- [Константы](#константы)
14+
- [Примеры](#примеры)
15+
516
## Установка
617

7-
Установить можно с помощью composer:
18+
Установить библиотеку можно с помощью composer:
819

920
```
1021
composer require amocrm/amocrm-api-library
1122
```
1223

13-
## Начало работы (авторизация)
24+
## Начало работы и авторизация
1425

1526
Для начала использования вам необходимо создать объект бибилиотеки:
1627
```php
@@ -77,15 +88,15 @@ $accessToken = $apiClient->getOAuthClient()->getAccessTokenByCode($_GET['code'])
7788
Модели и коллекции имеют методы ```toArray()``` и ```toApi()```, методы возвращают представление объекта в виде массива и в виде данных, отправляемых в API.
7889

7990
Также для работы с коллекциями имеют следующие методы:
80-
1. add(BaseApiModel $model): self - добавляет модель в конец коллекции.
81-
2. prepend(BaseApiModel $value): self - добавляет модель в начало коллекции.
82-
3. all(): array - возвращает массив моделей в коллекции.
83-
4. first(): ?BaseApiModel - получение первой модели в коллекции.
84-
5. last(): ?BaseApiModel - получение последней модели в коллекции.
85-
6. count(): int - получение кол-ва элементов в коллекции.
86-
7. isEmpty(): bool - проверяет, что коллекция не пустая.
87-
8. getBy($key, $value): ?BaseApiModel - получение модели по значению ключа.
88-
9. replaceBy($key, $value, BaseApiModel $replacement): void - замена модели по значению ключа.
91+
1. ```add(BaseApiModel $model): self``` - добавляет модель в конец коллекции.
92+
2. ```prepend(BaseApiModel $value): self``` - добавляет модель в начало коллекции.
93+
3. ```all(): array``` - возвращает массив моделей в коллекции.
94+
4. ```first(): ?BaseApiModel``` - получение первой модели в коллекции.
95+
5. ```last(): ?BaseApiModel``` - получение последней модели в коллекции.
96+
6. ```count(): int``` - получение кол-ва элементов в коллекции.
97+
7. ```isEmpty(): bool``` - проверяет, что коллекция не пустая.
98+
8. ```getBy($key, $value): ?BaseApiModel``` - получение модели по значению ключа.
99+
9. ```replaceBy($key, $value, BaseApiModel $replacement): void``` - замена модели по значению ключа.
89100

90101
При работе с библиотекой необходимо не забывать о лимитах API amoCRM.
91102
Для оптимальной работы с данными лучше всего создавать/изменять за раз не более 50 сущностей в методах, где есть пакетная обработка.
@@ -416,13 +427,177 @@ $leadsService = $apiClient->leads();
416427
|```webhooks``` |```\AmoCRM\Filters\WebhooksFilter``` |Фильтр для метода получения хуков |❌ |
417428

418429

419-
## Работа с Custom Fields сущностей
420-
421-
```todo```
430+
## Работа с дополнительными полями сущностей
431+
432+
Дополнительные поля доступны у сущностей следующих сервисов:
433+
1. ```leads```
434+
2. ```contacts```
435+
3. ```companies```
436+
4. ```customers```
437+
5. ```catalogElements```
438+
6. ```segments```
439+
440+
У моделей, который возвращаются у этих сервисов, поля можно получить через метод ```getCustomFieldsValues()```.
441+
На вызов данного метода возвращается объект ```CustomFieldsValuesCollection``` или ```null```,
442+
если значений полей нет.
443+
444+
Внутри коллекции ```CustomFieldsValuesCollection``` находятся модели значений полей,
445+
все модели наследуются от ```BaseCustomFieldValuesModel```, но зависят от типа поля.
446+
447+
У моделей, наследующих ```BaseCustomFieldValuesModel``` доступны следующие методы:
448+
1. ```getFieldId```, ```setFieldId``` - получение/установка id поля
449+
2. ```getFieldType``` - получение типа поля
450+
3. ```getFieldCode```, ```setFieldCode``` - получение/установка кода поля
451+
4. ```getFieldName```, ```setFieldName``` - получение/установка кода поля
452+
5. ```getValues```, ```setValues``` - получение/установка коллекции значений
453+
454+
Так как некоторые поля могут иметь несколько значений,
455+
в свойстве values хранится именно коллекция значений типа ```BaseCustomFieldValueCollection```.
456+
Моделями коллекции являются модели типа ```BaseCustomFieldValueModel```.
457+
458+
#### Схема отношений объектов:
459+
460+
```CustomFieldsValuesCollection 1 <---> n BaseCustomFieldValuesModel```
461+
```BaseCustomFieldValuesModel::getValues() 1 <---> 1 BaseCustomFieldValueCollection```
462+
```BaseCustomFieldValueCollection 1 <---> n BaseCustomFieldValueModel```
463+
464+
#### Для разных типов полей мы уже подготовили разные модели и коллекции:
465+
466+
Namespace, в котором находятся модели значения - ```\AmoCRM\Models\CustomFieldsValues\ValueModels```
467+
468+
Namespace, в котором находятся коллекции моделей значения - ```\AmoCRM\Models\CustomFieldsValues\ValueCollections```
469+
470+
Namespace, в котором находятся модели дополнительных полей - ```\AmoCRM\Models\CustomFieldsValues```
471+
472+
| Тип поля | Модель значения | Коллекция моделей значений | Модель доп поля | Контакт | Сделка | Компания | Покупатель | Каталог | Сегмент |
473+
|---------------------|------------------------------------|-----------------------------------------|-------------------------------------|:-------:|:------:|:--------:|:----------:|:-------:|:-------:|
474+
| Текст | TextCustomFieldValueModel | TextCustomFieldValueCollection | TextCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
475+
| Число | NumericCustomFieldValueModel | NumericCustomFieldValueCollection | NumericCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
476+
| Флаг | CheckboxCustomFieldValueModel | CheckboxCustomFieldValueCollection | CheckboxCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
477+
| Список | SelectCustomFieldValueModel | SelectCustomFieldValueCollection | SelectCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
478+
| Мультисписок | MultiselectCustomFieldValueModel | MultiselectCustomFieldValueCollection | MultiSelectCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
479+
| Мультитекст | MultitextCustomFieldValueModel | MultitextCustomFieldValueCollection | MultitextCustomFieldValuesModel | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
480+
| Дата | DateCustomFieldValueModel | DateCustomFieldValueCollection | DateCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
481+
| Ссылка | UrlCustomFieldValueModel | UrlCustomFieldValueCollection | UrlCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
482+
| Дата и время | DateTimeCustomFieldValueModel | DateTimeCustomFieldValueCollection | DateTimeCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
483+
| Текстовая область | TextareaCustomFieldValueModel | TextareaCustomFieldValueCollection | TextareaCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
484+
| Переключатель | RadiobuttonCustomFieldValueModel | RadiobuttonCustomFieldValueCollection | RadiobuttonCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
485+
| Короткий адрес | StreetAddressCustomFieldValueModel | StreetAddressCustomFieldValueCollection | StreetAddressCustomFieldValuesModel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
486+
| Адрес | SmartAddressCustomFieldValueModel | SmartAddressCustomFieldValueCollection | SmartAddressCustomFieldValuesModel | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
487+
| День рождения | BirthdayCustomFieldValueModel | BirthdayCustomFieldValueCollection | BirthdayCustomFieldValuesModel | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
488+
| Юр. лицо | LegalEntityCustomFieldValueModel | LegalEntityCustomFieldValueCollection | LegalEntityCustomFieldValuesModel | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
489+
| Цена | PriceCustomFieldValueModel | PriceCustomFieldValueCollection | PriceCustomFieldValuesModel | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
490+
| Категория | CategoryCustomFieldValueModel | CategoryCustomFieldValueCollection | CategoryCustomFieldValuesModel | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
491+
| Предметы | ItemsCustomFieldValueModel | ItemsCustomFieldValueCollection | ItemsCustomFieldValuesModel | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
492+
493+
Пример кода, как создать коллекцию значения полей сущности:
494+
```php
495+
//Создадим модель сущности
496+
$lead = new LeadModel();
497+
$lead->setId(1);
498+
//Создадим коллекцию полей сущности
499+
$leadCustomFieldsValues = new CustomFieldsValuesCollection();
500+
//Создадим модель значений поля типа текст
501+
$textCustomFieldValuesModel = new TextCustomFieldValuesModel();
502+
//Укажем ID поля
503+
$textCustomFieldValuesModel->setFieldId(123);
504+
//Добавим значения
505+
$textCustomFieldValuesModel->setValues(
506+
(new TextCustomFieldValueCollection())
507+
->add((new TextCustomFieldValueModel())->setValue('Текст'))
508+
);
509+
//Добавим значение в коллекцию полей сущности
510+
$leadCustomFieldsValues->add($textCustomFieldValuesModel);
511+
//Установим сущности эти поля
512+
$lead->setCustomFieldsValues($leadCustomFieldsValues);
513+
```
514+
515+
Чтобы удалить значения поля доступен специальный объект ```\AmoCRM\Models\CustomFieldsValues\ValueCollections\NullCustomFieldValueCollection```.
516+
517+
Передав этот объект, вы зануляете значение поля.
518+
519+
Пример:
520+
```php
521+
//Создадим модель сущности
522+
$lead = new LeadModel();
523+
$lead->setId(1);
524+
//Создадим коллекцию полей сущности
525+
$leadCustomFieldsValues = new CustomFieldsValuesCollection();
526+
//Создадим модель значений поля типа текст
527+
$textCustomFieldValuesModel = new TextCustomFieldValuesModel();
528+
//Укажем ID поля
529+
$textCustomFieldValuesModel->setFieldId(123);
530+
//Обнулим значения
531+
$textCustomFieldValuesModel->setValues(
532+
(new NullCustomFieldValueCollection())
533+
);
534+
//Добавим значение в коллекцию полей сущности
535+
$leadCustomFieldsValues->add($textCustomFieldValuesModel);
536+
//Установим сущности эти поля
537+
$lead->setCustomFieldsValues($leadCustomFieldsValues);
538+
```
422539

423540
## Работа с тегами сущностей
424541

425-
```todo```
542+
Теги доступны как отдельный сервис ```tags```.
543+
При создании данного сервиса, вы указываете тип сущности, с тегами которой вы будете работать.
544+
В данный момент доступны:
545+
1. EntityTypesInterface::LEADS,
546+
2. EntityTypesInterface::CONTACTS,
547+
3. EntityTypesInterface::COMPANIES,
548+
4. EntityTypesInterface::CUSTOMERS,
549+
550+
Для работы с тегами конкретной сущности, нужно взаимодействовать с конкретной моделью сущности.
551+
С помощью методов ```getTags``` и ```setTags``` вы можете получить коллекцию тегов сущности или установить её.
552+
553+
Для изменения тегов вам необходимо передавать всю коллекцию тегов, иначе теги могут быть потеряны.
554+
555+
Пример добавления/изменения тегов у сущности:
556+
```php
557+
//Создадим модель сущности
558+
$lead = new LeadModel();
559+
$lead->setId(1);
560+
//Создадим коллекцию тегов с тегами и установим их в сущности
561+
$lead->setTags((new TagsCollection())
562+
->add(
563+
(new TagModel())
564+
->setName('тег')
565+
)->add(
566+
(new TagModel())
567+
->setId(123123)
568+
)
569+
);
570+
```
571+
572+
или
573+
574+
```php
575+
//Создадим модель сущности
576+
$lead = new LeadModel();
577+
$lead->setId(1);
578+
//Создадим коллекцию тегов с тегами и установим их в сущности
579+
$lead->setTags(
580+
TagsCollection::fromArray([
581+
[
582+
'name' => 'тег',
583+
],
584+
[
585+
'id' => 123,
586+
],
587+
])
588+
);
589+
```
590+
591+
Для удаления тегов в setTags можно передать в ```setTags``` специальный объект ```\AmoCRM\Collections\NullTagsCollection```.
592+
593+
Пример удаления тегов у сущности:
594+
```php
595+
//Создадим модель сущности
596+
$lead = new LeadModel();
597+
$lead->setId(1);
598+
//Удалим теги
599+
$lead->setTags((new NullTagsCollection()));
600+
```
426601

427602
## Константы
428603

‎src/AmoCRM/Models/TagModel.php

+10-2
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,14 @@ public function getId(): ?int
5656

5757
/**
5858
* @param int $id
59+
*
60+
* @return TagModel
5961
*/
60-
public function setId(int $id): void
62+
public function setId(int $id): self
6163
{
6264
$this->id = $id;
65+
66+
return $this;
6367
}
6468

6569
/**
@@ -72,10 +76,14 @@ public function getName(): string
7276

7377
/**
7478
* @param string $name
79+
*
80+
* @return TagModel
7581
*/
76-
public function setName(string $name): void
82+
public function setName(string $name): self
7783
{
7884
$this->name = $name;
85+
86+
return $this;
7987
}
8088

8189
/**

0 commit comments

Comments
 (0)