Skip to content

Commit 2d844e1

Browse files
author
andrey-tech
committed
Update README.md
1 parent eae8e4b commit 2d844e1

1 file changed

Lines changed: 77 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 77 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
![Bitrix24 logo](./assets/bitrix24-logo.png)
44

5-
Обертка на PHP7+ для работы с REST API [Битрикс24](https://dev.1c-bitrix.ru/rest_help/) с использованием механизма входящих вебхуков,
6-
троттлингом запросов к серверу и логированием.
5+
Обертка на PHP7+ для работы с [REST API Битрикс24](https://dev.1c-bitrix.ru/rest_help/) с использованием механизма [входящих вебхуков](https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=99&LESSON_ID=8581),
6+
троттлингом запросов к API и логированием в файл.
77

88
**Документация находится в процессе разработки.**
99

@@ -12,13 +12,14 @@
1212
<!-- MarkdownTOC levels="1,2,3,4,5,6" autoanchor="true" autolink="true" -->
1313

1414
- [Требования](#%D0%A2%D1%80%D0%B5%D0%B1%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F)
15-
- [Класс `Bitrix24API`](#%D0%9A%D0%BB%D0%B0%D1%81%D1%81-bitrix24api)
15+
- [Класс `\App\Bitrix24\Bitrix24API`](#%D0%9A%D0%BB%D0%B0%D1%81%D1%81-appbitrix24bitrix24api)
1616
- [Базовые методы класса](#%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D0%B0)
1717
- [Дополнительные параметры](#%D0%94%D0%BE%D0%BF%D0%BE%D0%BB%D0%BD%D0%B8%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5-%D0%BF%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80%D1%8B)
1818
- [Методы работы с сущностями Битрикс24](#%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B-%D1%81-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D1%8F%D0%BC%D0%B8-%D0%91%D0%B8%D1%82%D1%80%D0%B8%D0%BA%D1%8124)
1919
- [Методы работы со сделками](#%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B-%D1%81%D0%BE-%D1%81%D0%B4%D0%B5%D0%BB%D0%BA%D0%B0%D0%BC%D0%B8)
20-
- [Обработка ошибок](#%D0%9E%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0-%D0%BE%D1%88%D0%B8%D0%B1%D0%BE%D0%BA)
21-
- [Класс `\App\HTTP`](#%D0%9A%D0%BB%D0%B0%D1%81%D1%81-apphttp)
20+
- [Вспомогательные классы](#%D0%92%D1%81%D0%BF%D0%BE%D0%BC%D0%BE%D0%B3%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5-%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D1%8B)
21+
- [Класс `\App\HTTP`](#%D0%9A%D0%BB%D0%B0%D1%81%D1%81-apphttp)
22+
- [Класс `\App\DebugLogger`](#%D0%9A%D0%BB%D0%B0%D1%81%D1%81-appdebuglogger)
2223
- [Примеры](#%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D1%8B)
2324
- [Работа со сделками](#%D0%A0%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81%D0%BE-%D1%81%D0%B4%D0%B5%D0%BB%D0%BA%D0%B0%D0%BC%D0%B8)
2425
- [Автор](#%D0%90%D0%B2%D1%82%D0%BE%D1%80)
@@ -32,16 +33,17 @@
3233
- PHP >= 7.0.
3334
- Произвольный автозагрузчик классов, реализующий стандарт [PSR-4](https://www.php-fig.org/psr/psr-4/).
3435

35-
<a id="%D0%9A%D0%BB%D0%B0%D1%81%D1%81-bitrix24api"></a>
36-
## Класс `Bitrix24API`
36+
<a id="%D0%9A%D0%BB%D0%B0%D1%81%D1%81-appbitrix24bitrix24api"></a>
37+
## Класс `\App\Bitrix24\Bitrix24API`
3738

38-
Для работы с REST API Битрикс24 используется класс `\App\Bitrix24\Bitrix24API`.
39+
Для работы с REST API Битрикс24 используется класс `\App\Bitrix24\Bitrix24API`.
40+
При возникновении ошибок выбрасывается исключение с объектом класса `\App\Bitrix24\Bitrix24APIException`.
3941

4042
<a id="%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D0%B0"></a>
4143
### Базовые методы класса
4244

4345
- `__construct(string $webhookURL)` Конструктор класса.
44-
+ `$webhookURL` - URL входящего вебхука Битрикс24.
46+
+ `$webhookURL` - URL входящего вебхука.
4547
- `request(string $function, array $params = []) :?array` Отправляет запрос в API.
4648
+ `$function` - имя метода (функции) запроса;
4749
+ `$params` - параметры запроса.
@@ -70,7 +72,7 @@
7072
Свойство | По умолчанию | Описание
7173
----------------------- | ------------------ | --------
7274
`$batchSize` | 50 | Устанавливает количество команд в одном пакете запросов (batch)
73-
`$logger` | null | Хранит объект класса, выполняющего логирование запросов и ответов API. Например, `\App\DebugLogger`
75+
`$logger` | null | Хранит объект класса `\App\DebugLogger`, выполняющего логирование запросов и ответов к API в файл.
7476
`$http` | `object \App\HTTP` | Хранит объект класса `\App\HTTP`, отправляющего запросы к API
7577

7678
<a id="%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B-%D1%81-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D1%8F%D0%BC%D0%B8-%D0%91%D0%B8%D1%82%D1%80%D0%B8%D0%BA%D1%8124"></a>
@@ -110,7 +112,7 @@
110112
- `$deals` - массив наборов полей сделок со связанными товарными позициями `PRODUCTS`;
111113
- `$params` - набор параметров сделки.
112114
- `deleteDeals(array $dealIds = []) :array` Пакетно удаляет сделки и возвращает массив ID сделок.
113-
- `$dealIds` - набор ID сделок.
115+
- `$dealIds` - массив ID сделок.
114116
- `setDealFile($dealId, $userFieldId, string $fileName, string $fileContent, bool $isBase64FileData = true) :int` Устанавливает файл в НЕ множественное пользовательское поле типа файл (файл нельзя удалить) и возвращает ID сделки.
115117
- `$dealId` - ID cделки;
116118
- `$userFieldId` ID НЕ множественного пользовательского поля в сделке ('UF_CRM_XXXXXXXXXX');
@@ -135,20 +137,19 @@
135137
- `getDealProductRowFields() :array` Возвращает описание полей товарных позиций.
136138
- `getDealFields() :array` Возвращает описание полей cделки, в том числе пользовательских.
137139

138-
<a id="%D0%9E%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0-%D0%BE%D1%88%D0%B8%D0%B1%D0%BE%D0%BA"></a>
139-
### Обработка ошибок
140-
141-
При возникновении ошибок при запросах к API выбрасывается исключение с объектом типа `\App\Bitrix24\Bitrix24APIException`.
140+
<a id="%D0%92%D1%81%D0%BF%D0%BE%D0%BC%D0%BE%D0%B3%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5-%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D1%8B"></a>
141+
## Вспомогательные классы
142142

143143
<a id="%D0%9A%D0%BB%D0%B0%D1%81%D1%81-apphttp"></a>
144-
## Класс `\App\HTTP`
144+
### Класс `\App\HTTP`
145145

146-
Вспомогательный класс `\App\HTTP` обеспечивает:
146+
Класс `\App\HTTP` обеспечивает:
147147

148-
- формирование запросов к API Битрикс 24;
149-
- троттлинг запросов к API на требуемом уровне [не более 2-х запросов в секунду](https://dev.1c-bitrix.ru/rest_help/rest_sum/index.php);
148+
- формирование POST запросов к API Битрикс 24 по протоколу HTTPS;
149+
- троттлинг запросов к API на требуемом уровне - [не более 2-х запросов в секунду](https://dev.1c-bitrix.ru/rest_help/rest_sum/index.php);
150150
- вывод отладочной информации о запросах к API в STDOUT.
151151

152+
При возникновении ошибок выбрасывается исключение с объектом класса `\App\AppException`.
152153
Дополнительные параметры доступны через публичные свойства класса `\App\HTTP`.
153154

154155
Свойство | По умолчанию | Описание
@@ -164,6 +165,63 @@
164165
`$curlTimeout` | 60 | Устанавливает таймаут установения соединения, секунды
165166
`$successStatusCodes` | [ 200 ] | Коды статуса НТТР, которые считаются успешными
166167

168+
```php
169+
use \App\Bitrix24\Bitrix24API;
170+
use \App\HTTP;
171+
172+
$webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
173+
$bx24 = new Bitrix24API($webhookURL);
174+
175+
// Устанавливаем максимальный уровень вывода отладочных сообщений в STDOUT
176+
$bx24->http->debugLevel = HTTP::DEBUG_URL | HTTP::DEBUG_HEADERS | HTTP::DEBUG_CONTENT;
177+
178+
// Устанавливаем троттлинг запросов на уровне не более 1 запроса в 2 секунды
179+
$bx24->http->throttle = 0.5;
180+
181+
// Устанавливаем таймаут соединения в 30 секунд
182+
$bx24->http->curlTimeout = 30;
183+
```
184+
185+
<a id="%D0%9A%D0%BB%D0%B0%D1%81%D1%81-appdebuglogger"></a>
186+
### Класс `\App\DebugLogger`
187+
188+
Класс `\App\DebugLogger` обеспечивает логирование запросов и ответов к API в файл.
189+
При возникновении ошибок выбрасывается исключение с объектом класса `\App\AppException`.
190+
191+
Список методов класса:
192+
193+
- `static instance(string $logFileName = 'debug.log') :\App\DebugLogger` Возвращает объект класса.
194+
+ `$logFileName` - имя лог файла.
195+
- `save(mixed $info, $object = null) :void` Сохраняет подлежащую логированию информацию в файл.
196+
+ $info - строка, массив или объект для логирования;
197+
+ $object - ссылка на объект класса в котором выполняется логирование.
198+
199+
Дополнительные параметры логирования доступы через публичные свойства класса `\App\DebugLogger`.
200+
201+
Свойство | По умолчанию | Описание
202+
----------------------- | ------------- | --------
203+
`$isActive` | false | Включает или выключает логирование
204+
`$logFileDir` | `temp/` | Устанавливает каталог в котором сохраняются лог файлы
205+
206+
207+
208+
```php
209+
use \App\Bitrix24\Bitrix24API;
210+
use \App\DebugLogger;
211+
212+
$webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
213+
$bx24 = new Bitrix24API($webhookURL);
214+
215+
$logFileName = 'debug_bitrix24api.log'
216+
$bx24->logger = DebugLogger::instance($logFileName);
217+
218+
// Устанавливаем каталог для сохранения лог файлов
219+
$bx24->logger->logFileDir = 'logs/';
220+
221+
// Включаем логирование
222+
$bx24->logger->isActive = true;
223+
224+
```
167225

168226
<a id="%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D1%8B"></a>
169227
## Примеры

0 commit comments

Comments
 (0)