{"id":22650064,"url":"https://github.com/ruvents/runet-id-php-client","last_synced_at":"2025-04-12T02:52:39.731Z","repository":{"id":62538343,"uuid":"105778557","full_name":"ruvents/runet-id-php-client","owner":"ruvents","description":"Официальный API-клиент RUNET-ID для PHP","archived":false,"fork":false,"pushed_at":"2022-09-08T07:18:22.000Z","size":428,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-04T17:49:06.941Z","etag":null,"topics":["api-client","httplug","php","psr-7","runet-id"],"latest_commit_sha":null,"homepage":"https://runet-id.com/apidoc/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruvents.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-04T14:30:05.000Z","updated_at":"2022-08-24T11:44:25.000Z","dependencies_parsed_at":"2022-11-02T15:30:22.731Z","dependency_job_id":null,"html_url":"https://github.com/ruvents/runet-id-php-client","commit_stats":null,"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvents%2Frunet-id-php-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvents%2Frunet-id-php-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvents%2Frunet-id-php-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvents%2Frunet-id-php-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruvents","download_url":"https://codeload.github.com/ruvents/runet-id-php-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501859,"owners_count":21114684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","httplug","php","psr-7","runet-id"],"created_at":"2024-12-09T08:30:34.557Z","updated_at":"2025-04-12T02:52:39.700Z","avatar_url":"https://github.com/ruvents.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Официальный API-клиент RUNET-ID для PHP\n\n[![GitHub license](https://img.shields.io/github/license/ruvents/runet-id-php-client.svg?style=flat-square)](https://github.com/ruvents/runet-id-php-client/blob/master/LICENSE)\n[![Travis branch](https://img.shields.io/travis/ruvents/runet-id-php-client/master.svg?style=flat-square)](https://travis-ci.org/ruvents/runet-id-php-client)\n[![Codecov branch](https://img.shields.io/codecov/c/github/ruvents/runet-id-php-client/master.svg?style=flat-square)](https://codecov.io/gh/ruvents/runet-id-php-client)\n[![Packagist](https://img.shields.io/packagist/v/runet-id/api-client.svg?style=flat-square)](https://packagist.org/packages/runet-id/api-client)\n[![Packagist Pre Release](https://img.shields.io/packagist/vpre/runet-id/api-client.svg?style=flat-square)](https://packagist.org/packages/runet-id/api-client)\n\n[Документация по API RUNET-ID.](https://runet-id.com/apidoc/)\n\n## Установка\n\nВыполните установку пакетов.\n\n`$ composer require runet-id/api-client:^3.0@beta php-http/discovery guzzlehttp/psr7 php-http/guzzle6-adapter`\n\nПакет `php-http/discovery` необходим для быстрого старта. Позднее Discovery можно заменить явными инъекциями HTTP-клиента и PSR-7 фабрик. Подробнее в разделе __Удаление библиотеки Discovery__.\n\nВместо `guzzlehttp/psr7` вы можете использовать [любую имплементацию PSR-7 сообщений](https://packagist.org/providers/psr/http-message-implementation), например, [zendframework/zend-diactoros](https://packagist.org/packages/zendframework/zend-diactoros).\n\nВместо `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).\n\n## Использование\n\n```php\n\u003c?php\n\nuse Http\\Discovery\\MessageFactoryDiscovery;\nuse RunetId\\Client\\RunetIdClientFactory;\nuse RunetId\\Client\\Result\\SuccessResult;\n\n$factory = new RunetIdClientFactory();\n$client = $factory-\u003ecreate('key', 'secret');\n\n// Запрос с использованием встроенных подсказок по endpoint-ам RUNET-ID.\n$user = $client-\u003euserGet()\n    // метод setLanguage доступен во всех endpoint-ах\n    -\u003esetLanguage('en')\n    -\u003esetRunetId(1)\n    -\u003egetResult();\n\n// Метод getResult возвращает размеченный phpDoc-свойствами класс.\n$runetId = $user-\u003eRunetId;\n$company = $user-\u003eWork-\u003eCompany-\u003eName;\n\n// Чтобы получить исходный массив, используйте метод getRawResult.\n$arrayUser = $client-\u003euserGet()\n    -\u003esetRunetId(1)\n    -\u003egetRawResult();\n\n// Endpoint-ы можно использовать повторно.\n$roleChanger = $client\n    -\u003eeventChangeRole()\n    -\u003esetRoleId(1);\n\n$success1 = $roleChanger\n    -\u003esetRunetId(1)\n    -\u003egetResult()\n    -\u003eSuccess;\n\n$success2 = $roleChanger\n    -\u003esetRunetId(2)\n    -\u003egetResult()\n    -\u003eSuccess;\n\n// Данные можно передавать в свободной форме.\n$company = $client\n    -\u003ecompanyGet()\n    // Метод setQueryData() перезаписывает все параметры.\n    -\u003esetQueryData([\n        'CompanyId' =\u003e 1,\n    ])\n    // Метод addQueryData() добавляет параметры, используя array_merge().\n    -\u003eaddQueryData([\n        'Language' =\u003e 'en',\n    ])\n    // Метод setQueryValue() устанавливает значение конкретного параметра,\n    // перезаписывая предыдущее значение.\n    -\u003esetQueryValue('EventId', 123)\n    -\u003egetResult();\n\n// Для POST запросов также доступны аналогичные методы (add|set)FormData() и setFormValue().\n$client\n    -\u003euserEdit()\n    -\u003esetFormData([\n        'RunetId' =\u003e 1,\n        'Email' =\u003e '1@mail.ru',\n    ])\n    -\u003eaddFormData([\n        'FirstName' =\u003e 'Имя',\n    ])\n    -\u003esetFormValue('LastName', 'Фамилия')\n    -\u003egetResult();\n\n// Чтобы сконструировать запрос от начала до конца,\n// можно воспользоваться методом custom().\n\n/** @var SuccessResult $result */\n$result = $client\n    -\u003ecustom()\n    -\u003esetMethod('PUT')\n    -\u003esetEndpoint('/some/put/endpoint')\n    -\u003esetLanguage('en')\n    -\u003esetQueryValue('param', 'value')\n    -\u003esetFormData([\n        'FormParam' =\u003e 'FormParamValue',\n    ])\n    -\u003esetClass(SuccessResult::class)\n    -\u003egetResult();\n\n// Отправка свободного Psr\\Http\\Message\\RequestInterface осуществляется через метод request().\n// Schema, host и заголовки аутентификации будут подставлены автоматически.\n$request = MessageFactoryDiscovery::find()\n    -\u003ecreateRequest('GET', '/user/get?RunetId=1');\n$resultArray = $client-\u003erequest($request);\n```\n\n### Получение постраничных данных\n\nПоставляемые с библиотекой endpoint-ы автоматически получают постраничные данные.\n\n```php\n\u003c?php\n\n// При условии наличия 900 регистраций на мероприятии и серверном ограничении в 200 сущностей:\n\n$endpoint = $client-\u003eeventUsers();\n\niterator_count($endpoint-\u003egetResult()-\u003eUsers); // 900 (5 запросов),\niterator_count($endpoint-\u003esetMaxResults(340)-\u003egetResult()-\u003eUsers); // 340 (2 запроса).\n```\n\nДля запроса постраничных данных используеся метод `RunetIdClient::requestPaginated(RequestInterface $request, string $itemsKey)`.\n\nАргумент `$itemsKey` принимает ключ, по которому можно найти массив постраничных данных. Например, для метода `/event/users` `$itemsKey = 'Users''`.\n\nВ результирующем массиве по ключу `$itemsKey` будет содержаться генератор, обеспечивающий lazy-loading.\n\n### Выбрасываемые исключения\n\n1. `Http\\Client\\Exception` будет выброшено при ошибке выполнения запроса. [Подробнее о классах исключений HTTPLUG](http://docs.php-http.org/en/latest/httplug/exceptions.html). В частности, \n    \n    - `Http\\Client\\Common\\Exception\\ClientErrorException` будет выброшено при коде ответа 4xx,\n    - `Http\\Client\\Common\\Exception\\ServerErrorException` будет выброшено при коде ответа 5xx.\n    \n    ```php\n    \u003c?php\n \n    try {\n        $client-\u003euserGet()\n            -\u003esetRunetId(1)\n            -\u003egetResult();\n    } catch (Http\\Client\\Common\\Exception\\ServerErrorException $exception) {\n        $statusCode = $exception-\u003egetResponse()-\u003egetStatusCode();\n    }\n    ```\n\n1. `RunetId\\Client\\Exception\\JsonDecodeException` будет выброшено при ошибке парсинга JSON.\n    \n    ```php\n    \u003c?php\n \n    try {\n        $client-\u003euserGet()\n            -\u003esetRunetId(1)\n            -\u003egetResult();\n    } catch (RunetId\\Client\\Exception\\JsonDecodeException $exception) {\n        $jsonErrorMsg = $exception-\u003egetMessage();\n        $jsonErrorCode = $exception-\u003egetCode();\n        $invalidString = $exception-\u003egetInvalidString();\n    }\n    ```\n\n1. `RunetId\\Client\\Exception\\RunetIdException` будет выброшено при ошибке API RUNET-ID.\n    \n    ```php\n    \u003c?php\n \n    try {\n        $client-\u003euserGet()\n            -\u003esetRunetId(1)\n            -\u003egetResult();\n    } catch (RunetId\\Client\\Exception\\RunetIdException $exception) {\n        $errorMessage = $exception-\u003egetMessage();\n        $errorCode = $exception-\u003egetCode();\n        // Метод getData() возвращает полный массив данных из ответа API.\n        $data = $exception-\u003egetData();\n    }\n    ```\n\n1. `RunetId\\Client\\Exception\\ResultFactoryException` будет выброшено при ошибке создания объекта результата.\n\n1. `RunetId\\Client\\Exception\\UnexpectedPaginatedDataException` будет выброшено при неверном формате ответа в методе `RunetIdClient::requestPaginated()`.\n\n### Подробнее об объектах Result\n\n```php\n\u003c?php\n\n$result = $client\n    -\u003euserGet()\n    -\u003esetRunetId(1)\n    -\u003egetResult();\n\n// Вы можете обращаться к неразмеченным свойствам.\n$result-\u003eSomeNewProperty;\n\n// Для простоты при запросе несуществующих в исходном массиве данных\n// объект не будет генерировать исключения. Вместо этого будет возвращен null.\n// Это может быть полезно при обращении к свойствам,\n// которые могут быть не включены в выдачу вследствие недостаточных прав.\n$result-\u003eSomeLimitedAccessProperty; // null\n\n// Чтобы проверить существование свойства в исходном массиве, используйте exists().\n$hasStatus = $result-\u003eexists('Status');\n\n// Результат является обходимым.\nforeach ($result as $key =\u003e $value) {\n    printf(\"%s: %s\\n\", $key, $value);\n}\n```\n\n### Конфигурация\n\n```php\n\u003c?php\n\nuse RunetId\\Client\\RunetIdClientFactory;\n\n// Установка параметров query по умолчанию.\n$factory = new RunetIdClientFactory();\n$client = $factory-\u003ecreate(\n    'key',\n    'secret',\n    RunetIdClientFactory::API_URI.'?Language=en\u0026EventId=123'\n);\n\n// Использование другого базового url.\n$factory = new RunetIdClientFactory();\n$client = $factory-\u003ecreate(\n    'key',\n    'secret',\n    'http://localhost:8000/endpoint-prefix/?Language=en'\n);\n```\n\nПоставляемая с библиотекой фабрика также позволяет использовать [любые плагины проекта PHP-HTTP](http://docs.php-http.org/en/latest/plugins/index.html). Для этого передайте массив плагинов 4-ым аргументом.\n\nНапример, для логгирования запросов при помощи PSR-3 логгера, установите пакет `php-http/logger-plugin` и подключите плагин к клиенту RUNET-ID ([подробнее в документации PHP-HTTP](http://docs.php-http.org/en/latest/plugins/logger.html)).\n\n```php\n\u003c?php\n\nuse Http\\Client\\Common\\Plugin\\LoggerPlugin;\nuse RunetId\\Client\\RunetIdClientFactory;\n\n$loggerPlugin = new LoggerPlugin(\n    // Здесь может быть любая имплементация Psr\\Log\\LoggerInterface.\n    new Monolog\\Logger('http')\n);\n\n$factory = new RunetIdClientFactory();\n$client = $factory-\u003ecreate(\n    'key',\n    'secret',\n    null,\n    null,\n    // Http\\Client\\Common\\Plugin[]\n    [$loggerPlugin]\n);\n```\n\n5-ым аргументом можно передать специально сконфигурированный для создаваемого клиента экземпляр `Http\\Client\\HttpClient`, который будет декорирован фабрикой для работы с RUNET-ID. По умолчанию используется HTTP-клиент, переданный в конструктор фабрики или клиент, найденный Discovery.\n\n### Удаление библиотеки Discovery\n\nБиблиотека [php-http/discovery](http://php-http.readthedocs.io/en/latest/discovery.html) позволяет находить установленные имплементации HTTP-клиента и PSR-7 фабрик и, например, использовать их в качестве инъекций по умолчанию.\n\nЗависимость от `php-http/discovery` мягкая. Чтобы удалить данный пакет из сборки, необходимо явно передать в конструктор фабрики имплементации HTTP-клиента и PSR-7 фабрик.\n\nНапример, если в проекте используется Guzzle 6, инициализация фабрики будет выглядеть следующим образом:\n\n```php\n\u003c?php\n\n$httpClient = new Http\\Adapter\\Guzzle6\\Client();\n$uriFactory = new Http\\Message\\UriFactory\\GuzzleUriFactory();\n$requestFactory = new Http\\Message\\MessageFactory\\GuzzleMessageFactory();\n$streamFactory = new Http\\Message\\StreamFactory\\GuzzleStreamFactory();\n\n$runetIdFactory = new RunetId\\Client\\RunetIdClientFactory($httpClient, $uriFactory, $requestFactory, $streamFactory);\n```\n\nПосле этого можно удалить пакет Discovery `composer remove php-http/discovery`.\n\n## Тестирование\n\n`vendor/bin/simple-phpunit  --coverage-text`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvents%2Frunet-id-php-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruvents%2Frunet-id-php-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvents%2Frunet-id-php-client/lists"}