ERPLY SDK

1. Структура

Namespace

\ErplySDK точки входа в API
\ErplySDK\DTO объекты данных основного Eply API
\ErplySDK\PIM объекты данных для Erply PIM (🛠️ не завершено)
\ErplySDK\Reports объекты данных для Reports API (🛠️ не завершено)
\ErplySDK\Bulks классы для работы с пакетными действиями основного API
\ErplySDK\Collections классы для работы с коллекциями DTO

2. Использование

Создание соединения:

$api = \ErplyAPI::getInstanceWithCredentials($code, $username, $password);
$api->setThrow(false);
$api->setRecordsOnPage(40);

Основные параметры соединения:

Параметр	По-умолчанию	Описание
`setCode()`		Устанавливает код клиента.
`setUsername()`		Устанавливает имя пользователя клиента.
`setPassword()`		Устанавливает пароль клиента.
`setAttempts()`	`3`	Устанавливает кол-во попыток повторных авторизации в случае завершения сессии во время запроса.
`setSessionLength()`	`3600`	Устанавливает длину сессии в секундах.
`setRecordsOnPage()`	`20`	Устанавливает кол-во записей на страницу.
`setThrow()`	`true`	Устанавливает будет ли при вызове API методов выбрасываться исключение с типом `\ErplySDK\ApiException`, если будет получен ответ с ошибкой от Erply.
`setLogSensitivity()`	`[]`	Устанавливает массив типов сообщений для сбора в журнал. Возможное значения: `LOG_NOTICE`, `LOG_ERROR`, `LOG_DEBUG`
`setLogForward()`		Устанавливает обратный вызов для пересылки логов (последовательность получаемых аргументов: `$message`, `$type`, `$datetime`)
`getLog()`		Получить записи журнала. Можно указать необязательный параметр для получения конкретного типа записей.
`hasLog()`		Проверить, содержится ли в журнале записи определенного типа сообщений.

Как добавлять вложенные элементы в объекты:

use ErplyAPI;

$doc = new DTO\SaleDocument();

$row = $doc->addRow();
$row->rowID = 100;
$row->code = 2048;

$row = $doc->addRow();
$row->rowID = 200;
$row->code = 4096;

Сохранение:

$api->saveSalesDocument($doc);

Получение:

$response = $api->getSalesDocuments(['clientIDs' => '128, 256, 512, 1024']);

Когда объект в ответе реализован от коллекции \ErplySDK\Collections, то такой объект можно итерировать стандартными средствами PHP, соединение само будет запрашивать все последующие страницы, пока не закончится обход всех записей в запросе:

foreach ($response as $record) {
    echo "Client {$record->clientName}, with email: {$record->clientEmail}" . PHP_EOL;
}

3. Пользовательские запросы

У экземпляра соединения есть два метода которые совершают непосредственный запрос к серверу используя текущее соединение. Ответ на такие запросы всегда будет не типизированный, т.е. ассоциативный массив.

// Стандартный запрос
$response = $api->stdRequest($params);  
// Пакетный запрос
$response = $api->bulkRequest($params);

Для стандартных запросов Erply в качестве параметра имени запроса ожидает ключ request, а для пакетных запросов ожидает ключ requestName, для этого у соединения есть две константы, которые следует использовать в качестве ключа имени запроса STD_REQ и BULK_REQ.

Стандартный пользовательский запрос:

На такой запрос будет получен не типизированный ответ, т.е. ассоциативный массив.

$response = $api->stdRequest([$api::STD_REQ => 'getCustomers', 'searchName' => 'John']);

Пакетный пользовательский запрос:

Также можно отправить пакетный запрос. На такой запрос будет получен не типизированный ответ, т.е. ассоциативный массив.

$response = $api->bulkRequest([
    [$api::BULK_REQ => 'getCustomers', 'searchPersonFirstName' => 'John'],
    [$api::BULK_REQ => 'getVatRates'],
    [$api::BULK_REQ => 'getEmployees'],
]);

Пакетный пользовательский запрос (типизированный):

Также можно получить типизированный ответ на пакетный пользовательский запрос. В этом случае все известные вложенные запросы будут инициализированы как коллекции.

$response = $api->getBulkResponse([
    [$api::BULK_REQ => 'getCustomers', 'searchPersonFirstName' => 'John'],
    [$api::BULK_REQ => 'getVatRates'],
    [$api::BULK_REQ => 'getEmployees'],
]);
$collections = $response->getRequests();

⚠️ На данный момент коллекции полученные через пользовательский пакетный запрос не позволяют использовать итерацию записей.

4. Дополнительно

Прямой вызов родительских методов current() и getRecords() у всех наследников от абстракции BaseEntityCollection нужен для того, чтобы у детей определить конкретный возвращаемый тип.

5. Roadmap

Реализовать атрибуты во всех сущностях как отдельные коллекции.
Реализовать итерацию записей полученную через типизированный пользовательский пакетный запрос.

quantum3k / erply-sdk