Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ruvents/runet-id-php-client
Официальный API-клиент RUNET-ID для PHP
https://github.com/ruvents/runet-id-php-client
api-client httplug php psr-7 runet-id
Last synced: about 2 months ago
JSON representation
Официальный API-клиент RUNET-ID для PHP
- Host: GitHub
- URL: https://github.com/ruvents/runet-id-php-client
- Owner: ruvents
- License: mit
- Created: 2017-10-04T14:30:05.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-09-08T07:18:22.000Z (over 2 years ago)
- Last Synced: 2024-09-15T12:28:08.296Z (5 months ago)
- Topics: api-client, httplug, php, psr-7, runet-id
- Language: PHP
- Homepage: https://runet-id.com/apidoc/
- Size: 418 KB
- Stars: 0
- Watchers: 7
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Официальный API-клиент RUNET-ID для PHP
[](https://github.com/ruvents/runet-id-php-client/blob/master/LICENSE)
[](https://travis-ci.org/ruvents/runet-id-php-client)
[](https://codecov.io/gh/ruvents/runet-id-php-client)
[](https://packagist.org/packages/runet-id/api-client)
[](https://packagist.org/packages/runet-id/api-client)
[Документация по API RUNET-ID.](https://runet-id.com/apidoc/)
## Установка
Выполните установку пакетов.
`$ composer require runet-id/api-client:^3.0@beta php-http/discovery guzzlehttp/psr7 php-http/guzzle6-adapter`
Пакет `php-http/discovery` необходим для быстрого старта. Позднее Discovery можно заменить явными инъекциями HTTP-клиента и PSR-7 фабрик. Подробнее в разделе __Удаление библиотеки Discovery__.
Вместо `guzzlehttp/psr7` вы можете использовать [любую имплементацию PSR-7 сообщений](https://packagist.org/providers/psr/http-message-implementation), например, [zendframework/zend-diactoros](https://packagist.org/packages/zendframework/zend-diactoros).
Вместо `php-http/guzzle6-adapter` вы можете использовать [любую имплементацию HTTP-клиента](https://packagist.org/providers/php-http/client-implementation), например, [cURL client](https://packagist.org/packages/php-http/curl-client) или [Socket client](https://packagist.org/packages/php-http/socket-client).
## Использование
```php
create('key', 'secret');
// Запрос с использованием встроенных подсказок по endpoint-ам RUNET-ID.
$user = $client->userGet()
// метод setLanguage доступен во всех endpoint-ах
->setLanguage('en')
->setRunetId(1)
->getResult();
// Метод getResult возвращает размеченный phpDoc-свойствами класс.
$runetId = $user->RunetId;
$company = $user->Work->Company->Name;
// Чтобы получить исходный массив, используйте метод getRawResult.
$arrayUser = $client->userGet()
->setRunetId(1)
->getRawResult();
// Endpoint-ы можно использовать повторно.
$roleChanger = $client
->eventChangeRole()
->setRoleId(1);
$success1 = $roleChanger
->setRunetId(1)
->getResult()
->Success;
$success2 = $roleChanger
->setRunetId(2)
->getResult()
->Success;
// Данные можно передавать в свободной форме.
$company = $client
->companyGet()
// Метод setQueryData() перезаписывает все параметры.
->setQueryData([
'CompanyId' => 1,
])
// Метод addQueryData() добавляет параметры, используя array_merge().
->addQueryData([
'Language' => 'en',
])
// Метод setQueryValue() устанавливает значение конкретного параметра,
// перезаписывая предыдущее значение.
->setQueryValue('EventId', 123)
->getResult();
// Для POST запросов также доступны аналогичные методы (add|set)FormData() и setFormValue().
$client
->userEdit()
->setFormData([
'RunetId' => 1,
'Email' => '[email protected]',
])
->addFormData([
'FirstName' => 'Имя',
])
->setFormValue('LastName', 'Фамилия')
->getResult();
// Чтобы сконструировать запрос от начала до конца,
// можно воспользоваться методом custom().
/** @var SuccessResult $result */
$result = $client
->custom()
->setMethod('PUT')
->setEndpoint('/some/put/endpoint')
->setLanguage('en')
->setQueryValue('param', 'value')
->setFormData([
'FormParam' => 'FormParamValue',
])
->setClass(SuccessResult::class)
->getResult();
// Отправка свободного Psr\Http\Message\RequestInterface осуществляется через метод request().
// Schema, host и заголовки аутентификации будут подставлены автоматически.
$request = MessageFactoryDiscovery::find()
->createRequest('GET', '/user/get?RunetId=1');
$resultArray = $client->request($request);
```
### Получение постраничных данных
Поставляемые с библиотекой endpoint-ы автоматически получают постраничные данные.
```php
eventUsers();
iterator_count($endpoint->getResult()->Users); // 900 (5 запросов),
iterator_count($endpoint->setMaxResults(340)->getResult()->Users); // 340 (2 запроса).
```
Для запроса постраничных данных используеся метод `RunetIdClient::requestPaginated(RequestInterface $request, string $itemsKey)`.
Аргумент `$itemsKey` принимает ключ, по которому можно найти массив постраничных данных. Например, для метода `/event/users` `$itemsKey = 'Users''`.
В результирующем массиве по ключу `$itemsKey` будет содержаться генератор, обеспечивающий lazy-loading.
### Выбрасываемые исключения
1. `Http\Client\Exception` будет выброшено при ошибке выполнения запроса. [Подробнее о классах исключений HTTPLUG](http://docs.php-http.org/en/latest/httplug/exceptions.html). В частности,
- `Http\Client\Common\Exception\ClientErrorException` будет выброшено при коде ответа 4xx,
- `Http\Client\Common\Exception\ServerErrorException` будет выброшено при коде ответа 5xx.
```php
userGet()
->setRunetId(1)
->getResult();
} catch (Http\Client\Common\Exception\ServerErrorException $exception) {
$statusCode = $exception->getResponse()->getStatusCode();
}
```
1. `RunetId\Client\Exception\JsonDecodeException` будет выброшено при ошибке парсинга JSON.
```php
userGet()
->setRunetId(1)
->getResult();
} catch (RunetId\Client\Exception\JsonDecodeException $exception) {
$jsonErrorMsg = $exception->getMessage();
$jsonErrorCode = $exception->getCode();
$invalidString = $exception->getInvalidString();
}
```
1. `RunetId\Client\Exception\RunetIdException` будет выброшено при ошибке API RUNET-ID.
```php
userGet()
->setRunetId(1)
->getResult();
} catch (RunetId\Client\Exception\RunetIdException $exception) {
$errorMessage = $exception->getMessage();
$errorCode = $exception->getCode();
// Метод getData() возвращает полный массив данных из ответа API.
$data = $exception->getData();
}
```
1. `RunetId\Client\Exception\ResultFactoryException` будет выброшено при ошибке создания объекта результата.
1. `RunetId\Client\Exception\UnexpectedPaginatedDataException` будет выброшено при неверном формате ответа в методе `RunetIdClient::requestPaginated()`.
### Подробнее об объектах Result
```php
userGet()
->setRunetId(1)
->getResult();
// Вы можете обращаться к неразмеченным свойствам.
$result->SomeNewProperty;
// Для простоты при запросе несуществующих в исходном массиве данных
// объект не будет генерировать исключения. Вместо этого будет возвращен null.
// Это может быть полезно при обращении к свойствам,
// которые могут быть не включены в выдачу вследствие недостаточных прав.
$result->SomeLimitedAccessProperty; // null
// Чтобы проверить существование свойства в исходном массиве, используйте exists().
$hasStatus = $result->exists('Status');
// Результат является обходимым.
foreach ($result as $key => $value) {
printf("%s: %s\n", $key, $value);
}
```
### Конфигурация
```php
create(
'key',
'secret',
RunetIdClientFactory::API_URI.'?Language=en&EventId=123'
);
// Использование другого базового url.
$factory = new RunetIdClientFactory();
$client = $factory->create(
'key',
'secret',
'http://localhost:8000/endpoint-prefix/?Language=en'
);
```
Поставляемая с библиотекой фабрика также позволяет использовать [любые плагины проекта PHP-HTTP](http://docs.php-http.org/en/latest/plugins/index.html). Для этого передайте массив плагинов 4-ым аргументом.
Например, для логгирования запросов при помощи PSR-3 логгера, установите пакет `php-http/logger-plugin` и подключите плагин к клиенту RUNET-ID ([подробнее в документации PHP-HTTP](http://docs.php-http.org/en/latest/plugins/logger.html)).
```php
create(
'key',
'secret',
null,
null,
// Http\Client\Common\Plugin[]
[$loggerPlugin]
);
```
5-ым аргументом можно передать специально сконфигурированный для создаваемого клиента экземпляр `Http\Client\HttpClient`, который будет декорирован фабрикой для работы с RUNET-ID. По умолчанию используется HTTP-клиент, переданный в конструктор фабрики или клиент, найденный Discovery.
### Удаление библиотеки Discovery
Библиотека [php-http/discovery](http://php-http.readthedocs.io/en/latest/discovery.html) позволяет находить установленные имплементации HTTP-клиента и PSR-7 фабрик и, например, использовать их в качестве инъекций по умолчанию.
Зависимость от `php-http/discovery` мягкая. Чтобы удалить данный пакет из сборки, необходимо явно передать в конструктор фабрики имплементации HTTP-клиента и PSR-7 фабрик.
Например, если в проекте используется Guzzle 6, инициализация фабрики будет выглядеть следующим образом:
```php