KnockKnock

KnockKnock - это простая библиотека, реализующая Фасад и предоставляющая удобный интерфейс для выполнения запросов в PHP, используя расширение cURL. Она упрощает работу, предоставляя более высокоуровневый API и быстрый доступ к настройкам.

Цель: сделать простой и лёгкий в настройке компонента и запроса пакет.

P.S. я знаю про существование таких библиотек как: Guzzle, Client (в моём любимом Yii2), но хотелось попробовать создать свою реализацию.
Без "лишних" данных, вызовов и настроек, nullWarningStyle - только то, что нужно: сухо, лаконично, минималистично.
Разумеется, это не конкурент, а просто попытка создать что-то своё

Содержание:

• Установка
• Объект - Базовый класс
• Объект - Запрос
• Объект - Ответ
• Дополнительные возможности
• Расширение на основе базового класса
• Пример Custom реализации
• Тесты

---

Установка

Требования

- php 8.0 - ext cURL - ext JSON

Composer

## Добавление пакета в проект

Используя: консольные команды. (Предпочтительней)

- при composer, установленном локально: ` - при использовании composer.phar: **Далее:** обновление зависимостей `composer update`

Используя: файл `composer.json`

Открыть файл `composer.json` В раздел, ключ `require` добавить строку `"andy87/knockknock": "*"` **Далее:** обновление зависимостей `composer update`

Используя: подключение авто загрузчика

В месте, где необходимо использовать библиотеку, подключите авто загрузчик: **Примечания:** - Убедитесь, что путь к autoload.php правильный и соответствует структуре вашего проекта.

- - - - -

___

Логика работы библиотеки (блок-схема)

### Простой пример работы.

- - - - -

___

Базовый класс

_use [andy87\knock_knock\core\Operator](src/core/Operator.php);_ PHP Фасад\Адаптер для отправки запросов через ext cURL

ReadOnly свойства:

- **commonRequest** - _Объект содержащий параметры, назначаемые всем исходящим запросам_ - **realRequest** - _Используемый запрос_ - **eventHandlers** - _Список обработчиков событий_ - **host** - _Хост, на который будет отправляться запросы_ - **logs** - _Список логов_ Возможности/фичи: - Настройки параметров запросов - Защита данных от перезаписи - Обработчики событий - Инкапсуляция - Singleton - логирование #### ВАЖНЫЙ МОМЕНТ! - В классах применяется инкапсуляция, поэтому для доступа к свойствам компонентов используются ReadOnly свойства. - `CURL_OPTIONS` по умолчанию пустые! В большинстве случаев, для получения валидных ответов, требуется задать необходимые настройки.

"Получение" объекта/экземпляра класса

Передавая параметры напрямую в конструктор: Применяя, паттерн Singleton: Методы возвращают объект(экземпляр класса `Operator`), принимая на вход два аргумента: - `string $host` - хост - `array $operatorConfig` - массив с настройками для всех исходящих запросов. При создании объекта `Operator` будет вызван метод `init()`, который запускает пользовательские инструкции. После выполнения `init()` запускается обработчик события привязанный к ключу `EVENT_AFTER_CONSTRUCT`

Общие настройки запросов

Что бы указать настройки применяемые ко всем исходящим запросам, при создании объекта `Operator` передаётся массив (ключ - значение), с необходимыми настройками. Пример настройки: Доступные ключи для настройки(константы класса `Request`): - `SETUP_PROTOCOL` - `SETUP_HOST` - `SETUP_METHOD` - `SETUP_HEADERS` - `SETUP_CONTENT_TYPE` - `SETUP_DATA` - `SETUP_CURL_OPTIONS` - `SETUP_CURL_INFO`

Обработчики событий

Список событий

- `EVENT_AFTER_CONSTRUCT` после создания объекта knockKnock - `EVENT_CREATE_REQUEST` после создания объекта запроса - `EVENT_BEFORE_SEND` перед отправкой запроса - `EVENT_CURL_Operator` перед отправкой curl запроса - `EVENT_CREATE_RESPONSE` после создания объекта ответа - `EVENT_AFTER_SEND` после получения ответа

Пример установки обработчиков событий

Первый аргумент - ключ события, второй - callback функция. Все callback функции принимают первым аргументом объект/экземпляр класса `Operaotr`. Вторым аргументом передаётся объект/экземпляр класса в зависимости от события: - `Request` - для событий `EVENT_CREATE_REQUEST`, `EVENT_BEFORE_SEND` - `Response` - для событий `EVENT_CREATE_RESPONSE`, `EVENT_AFTER_SEND`

- - - - -

___

Запрос

_use [andy87\knock_knock\core\Request](src/core/Request.php);_ Объект запроса, содержащий данные для отправки запроса.

ReadOnly свойства:

- **protocol** - _протокол_ - **host** - _хост_ - **endpoint** - _конечная точка_ - **method** - _метод_ - **headers** - _заголовки_ - **contentType** - _тип контента_ - **data** - _данные_ - **curlOptions** - _опции cURL_ - **curlInfo** - _информация cURL_ - **params** - _параметры запроса_ - **url** - _полный URL_ - **params** - _все свойства в виде массива_ - **fakeResponse** - _установленные фэйковые данные ответа_ - **errors** - _лог ошибок_

Создание объекта запроса

Передавая параметры напрямую в конструктор: Методом, который вызывает _callback_ функцию, привязанную к ключу `EVENT_CREATE_REQUEST` Клонируя существующий объект запроса:

Назначение/Изменение/Получение отдельных параметров запроса (set/get)

Таблица set/get методов для взаимодействия с отдельными свойствами запроса | Параметр | Сеттер | Геттер | Информация | |-----------------|---------------------------------------|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Протокол | setProtocol( string $protocol ) | getProtocol(): string | протоколы | | Хост | setHost( string $host ) | getHost(): string | --- | | Endpoint | setEndpoint( string $url ) | getEndpoint(): string | --- | | Метод | setMethod( string $method ) | getMethod(): string | методы | | Заголовки | setHeaders( array $headers ) | getHeaders(): array | заголовки | | Тип контента | setContentType( string $contentType ) | getContentType(): string | Тип контента | | Данные | setData( mixed $data ) | getData(): mixed | --- | | Опции cURL | setCurlOptions( array $curlOptions ) | getCurlOptions(): array | Опции cURL | | Информация cURL | setCurlInfo( array $curlInfo ) | getCurlInfo(): array | Информация cURL | | Фэйковый ответ | setFakeResponse( array $response ) | getFakeResponse(): array | |

Назначение запроса с переназначением свойств

`setupRequest( Request $request, array $options = [] ): self` ##### addError( string $error ) Добавление ошибки в лог ошибок

- - - - -

___

Ответ

_use [andy87\knock_knock\core\Response](src/core/Response.php);_ Объект ответа, содержащий данные ответа на запрос.

ReadOnly свойства

- **content** - _данные ответа_ - **httpCode** - _код ответа_ - **request** - _объект запроса, содержащий данные о запросе_ - **curlOptions** - _быстрый доступ к request->curlOptions_ - **curlInfo** - _быстрый доступ к request->curlInfo_

Создание объекта ответа

Передавая параметры напрямую в конструктор: Методом, который вызывает _callback_ функцию, привязанную к ключу `EVENT_CREATE_RESPONSE` `constructResponse( array $responseParams, ?Request $request = null ): Response`

Отправка запроса

`send( ?Request $request = null ): Response` Вызов возвращает объект/экземпляр класса `Response`. Срабатывают callback функции, привязанные к ключам: - `EVENT_AFTER_SEND` - `EVENT_CREATE_RESPONSE` - `EVENT_BEFORE_SEND` - `EVENT_CURL_HANDLER` Нельзя повторно отправить запрос, выбрасывается исключение `RequestCompleteException`. Для повторной отправки запроса, необходимо создать новый объект запроса и использовать его:

Отправка запроса с фэйковым ответом

объект `$response` будет содержать в свойствах `content`, `httpCode` данные переданные в аргументе `$fakeResponse`

Данные в ответе

В созданный объект `Response`, чей запрос не был отправлен, разрешено задавать данные, используя методы группы `set`. **Внимание!** Если данные в объекте уже существуют, повторно задать их нельзя выбрасывается `ParamUpdateException`. В случае необходимости заменить данные, используется вызов метода `replace( string $key, mixed $value )` см. далее

Подмена данных

Это сделано для явного действия, когда необходимо заменить данные в объекте `Response`.

Данные запроса из ответа

Для получения из объекта `Response` данных запроса, необходимо обратиться к ReadOnly свойству `request` и далее взаимодействовать с ним аналогично объекту `Request` Получения свойств cURL запроса

asArray()

Преобразование в массив. - преобразование данных ответа на запрос `asArray()` - преобразование всего объекта в массив `asArray(true)` ##### addError( string $error ) Добавление ошибки в лог ошибок

- - - - -

___

- - - - -

Дополнительные возможности

SSL

Функционал включения/отключения SSL верификации в объектах `Operaotr` & `Request`. В `curlOptions` добавляется ключ `CURLOPT_SSL_VERIFYPEER` и `CURLOPT_SSL_VERIFYHOST`. `->disableSSL( bool $verifyPeer = false, int $verifyHost = 0 );` `->enableSSL( bool $verifyPeer = true, int $verifyHost = 2 );` `Operaotr` - для всех запросов `Request` - для конкретного запроса

Cookie

В объекте `Operaotr` имеется функционал использования cookie. `Operaotr` - для всех запросов `$operator->useCookie( string $cookie, string $jar, ?string $file = null )` по умолчанию `$file = null` и `$file` приравнивается к `$jar`

Логирование

Добавление сообщений во внутренний массив `logs` `$operator->addLog( string $message )`

- - - - -

___

- - - - -

Расширения на основе базового класса

KnockKnockOctopus

Класс с функционалом простой реализации отправки запросов и минимальными настройками

Доступные методы.

| get() | post() | put() | patch() | delete() | head() | options() | trace() | |-------|--------|-------|---------|----------|--------|-----------|---------|

Каждый метод принимает два аргумента:

| Аргумент | Тип | Обязательный | Описание | |:----------|:-------:|:-------------:|:-------------------------------| | $endpoint | string | Да | URL запроса (без хоста) | | $params | array | Нет | Данные запроса в виде массива | _P.S. host задаётся в конструкторе_

Простой пример использования

- - - - -

KnockKnockSecurity

Расширяет класс [KnockKnockOctopus](docs/KnockKnock/KnockKnockOctopus.md), предоставляя доступ к функционалу для простой и быстрой реализации авторизации, и настройки запросов.

- - - - -

___

- - - - -

Custom реализация

Custom реализация Базового класса, к примеру с добавлением логирования работающим "под капотом"

Пример использования custom реализации

- - - - -

___

- - - - -

Тесты

- tests: 100+ - assertions: 350+

Запуск тестов:

Нативный Информационный С логированием

Лицензия

https://github.com/andy87/KnockKnock под лицензией CC BY-SA 4.0 Для получения дополнительной информации смотрите http://creativecommons.org/licenses/by-sa/4.0/ Свободно для не коммерческого использования С указанием авторства для коммерческого использования [Packagist](https://packagist.org/packages/andy87/knockknock)