Download the PHP package andrey-tech/sendpulse-api-php without Composer

SendPulse API PHP Wrapper

Простая обертка на PHP7+ для работы с REST API сервиса SendPulse с троттлингом запросов, выводом отладочной информации в STDOUT и логированием в файл.

Содержание

• Требования
• Установка
• Класс SendPulseAPI
  • Авторизация пользователя
    • Хранение токена
      • Интерфейс TokenStorageInterface
      • Класс TokenStorage
      • Использование собственного класса для сохранения токенов
  • Методы для работы с адресными книгами
  • Методы для работы с кампаниями
  • Методы для работы с шаблонами
  • Методы для работы с SMTP сервисом
  • Вспомогательные методы класса
• Вспомогательные классы
  • Класс HTTP
    • Дополнительные параметры
    • Пример использования класса
    • Примеры отладочных сообщений
  • Класс DebugLogger
    • Методы класса
    • Дополнительные параметры
    • Пример использования класса
    • Пример результатов логирования
    • Формат заголовков лога
• Автор
• Лицензия

Требования

• PHP >= 7.0;
• класс HTTP >= 3.0 - НТТР(S) клиент с троттлингом запросов, поддержкой маркера BOM в теле сообщения формата JSON и выводом отладочной информации о запросах и ответах в STDOUT;
• класс DebugLogger >= 2.0 - логгер, сохраняющий отладочную информацию в файл вместе с данными об объеме используемой оперативной памяти и прошедшем времени;
• произвольный автозагрузчик классов, реализующий стандарт PSR-4.

Установка

Установка через composer:

или добавить

в секцию require файла composer.json.

Класс SendPulseAPI

Для работы с REST API SendPulse используется класс \App\SendPulse\SendPulseAPI.
При возникновении ошибок выбрасывается исключение класса \App\SendPulse\SendPulseAPIException.
В настоящее в классе частично реализованы методы для работы со следующими сервисами SendPulse:

• Email сервис
• SMTP сервис

Авторизация пользователя

Методы для авторизации пользователя находится в трейте \App\SendPulse\Auth:

• auth(string $clientId, string $clientSecret) :string Выполняет авторизацию клиента и возвращает персональный ключ (токен), который также сохраняется в хранилище токенов.
  • $clientId - ID клиента (пользователя);
  • $clientSecret - секрет клиента (пользователя).

Получение нового токена, по истечении его срока действия, происходит автоматически, когда в ответ на запрос к API SendPulse возвращается ответ с HTTP-статусом 401 Unauthorized.

Хранение токена

Сохранение и загрузка токена выполняется с помощью классов, реализующих интерфейс \App\SendPulse\TokenStorage\TokenStorageInterface.

Интерфейс TokenStorageInterface

Интерфейс \App\SendPulse\TokenStorage\TokenStorageInterface определяет два метода:

• save(string $token, string $clientId, string $clientSecret) :void Сохраняет токен.
  • $token - токен;
  • $clientId - ID клиента;
  • $clientSecret - секрет клиента.
• load(string $clientId, string $clientSecret) :?string Загружает токен и возвращает его. Метод должен возвращать null, когда сохраненный токен отсутствует.
  • $clientId - ID клиента;
  • $clientSecret - секрет клиента.
• hasToken(string $clientId, string $clientSecret) :bool Проверяет существование токена для заданного сочетания $clientId и $clientSecret.
  • $clientId - ID клиента;
  • $clientSecret - секрет клиента.

Класс TokenStorage

По умолчанию для сохранения и загрузки токенов используется класс \App\SendPulse\TokenStorage\TokenStorage, который хранит токены в отдельных файлах для каждого сочетания $clientId и $clientSecret, использованного при авторизации в методе auth(). Класс реализует интерфейс \App\SendPulse\TokenStorage\TokenStorageInterface и содержит собственные методы:

• __construct(string $storageFolder = 'tokens/') Конструктор класса.
  • $storageFolder - каталог для хранения файлов токенов.

Дополнительные параметры устанавливаются через публичные свойства класса \App\SendPulse\TokenStorage\TokenStorage:

При возникновении ошибок выбрасыватся исключение класса \App\SendPulse\TokenStorage\TokenStorageException.

Использование собственного класса для сохранения токенов

Пример использования собственного класса для сохранения токенов в базе данных:

Структура собственного класса \App\SendPulse\TokenStorage\DatabaseStorage:

Методы для работы с адресными книгами

Методы для работы с адресными книгами находятся в трейте \App\SendPulse\Addressbooks:

• getAddressbook(int $id) :array Возвращает информацию об адресной книге.
  • $id - ID адресной книги.
• getAddressbooks(int $limit = null, int $offset = null) :array Возвращает список адресных книг (не более 100).
  • $limit - количество записей;
  • $offset - смещение выдачи (начиная с какой записи показывать).
• getAllAddressbooks() :\Generator Позволяет получить список всех адресных книг, возвращая генератор.
• addAddressbook(array $params) :int Добавляет адресную книгу и возвращает ID адресной книги.
  • $params - параметры адресной книги.
• updateAddressbook(int $id, array $params) :array Обновляет адресную книгу.
  • $id - ID адресной книги;
  • $params - параметры адресной книги.
• deleteAddressbook(int $id) :array Удаляет адресную книгу.
  • $id - ID адресной книги.
• addAddressbookEmails(int $id, array $emails) :array Добавляет email адреса в адресную книгу.
  • $id - ID адресной книги;
  • $emails - список email адресов или параметры контактов.
• deleteAddressbookEmails(int $id, array $emails) :array Удаляет email адреса из адресной книги
  • $id - ID адресной книги;
  • $emails - список email адресов.
• getAddressbookEmails(int $id, int $limit = null, int $offset = null) :array Возвращает список email адресов в адресной книге (не более 100).
  • $id - ID адресной книги;
  • $limit - количество записей;
  • $offset - смещение выдачи (начиная с какой записи показывать).
• getAllAddressbookEmails(int $id) :\Generator Позволяет получить список всех email адресов в адресной книге, возвращая генератор.
  • $id - ID адресной книги.
• getAddressbookEmailsTotal(int $id) :int Возвращает общее количество email адресов в адресной книге.
  • $id - ID адресной книги.
• getAddresbookVariables(int $id) :array Возвращает список переменных для адресной книги.
  • $id - ID адресной книги.

Примеры работы с адресными книгами:

Методы для работы с кампаниями

Методы для работы с кампаниями находятся в трейте \App\SendPulse\Campaigns:

• getCampaign(int $id) :array Возвращает информацию о кампании.
  • $id - ID кампании;
• getCampaigns(int $limit = null, int $offset = null) :array Возвращает список кампаний (не более 100).
  • $limit - количество записей;
  • $offset - смещение выдачи (начиная с какой записи показывать).
• getAllCampaigns() :\Generator Позволяет получить список всех кампаний, возвращая генератор.
• addCampaign(array $params) :int Добавляет кампанию и возвращает ID кампании.
  • $params - параметры кампании.
• updateCampaign(int $id, array $params) :array Обновляет запланированную кампанию.
  • $id - ID кампании;
  • $params - параметры кампании.
• deleteCampaign(int $id) :array Отменяет отправку запланированной кампании.
  • $id - ID кампании.
• getAddressbookCampaigns(int $id, int $limit = null, int $offset = null) :array Возвращает список кампаний, которые создавались по данной адресной книге (не более 100).
  • $id - ID адресной книги;
  • $limit - количество записей;
  • $offset - смещение выдачи (начиная с какой записи показывать).
• getAllAddressbookCampaigns(int $id) :\Generator Позволяет получить список всех кампаний, которые создавались по данной адресной книге, возвращая генератор.
  • $id - ID адресной книги.

Примеры работы с кампаниями:

Методы для работы с шаблонами

Методы для работы с шаблонами находятся в трейте \App\SendPulse\Templates:

• getTemplate(int $id) :array Возвращает информацию о шаблоне.
  • $id - ID шаблона.
• getTemplates(string $owner = null, string $lang = null) :array Возвращает список шаблонов с возможностью фильтрации.
  • $owner - фильтр по владельцу шаблона (me - пользовательские шаблоны, sendpulse - системные шаблоны);
  • $lang - фильтр по языку шаблона (ru, en).
• addTemplate(array $params) :int Добавляет шаблон и возвращает real ID шаблона.
  • $params - параметры шаблона.
• updateTemplate(int $id, array $params) :array Обновляет шаблон.
  • $id - ID шаблона;
  • $params - параметры шаблона.

Примеры работы с шаблонами:

Методы для работы с SMTP сервисом

Методы для работы с SMTP сервисом находятся в трейте \App\SendPulse\Smtp:

• sendEmails(array $params) :array Отправляет письмо.
  • $params - параметры письма.

Примеры работы с SMTP сервисом:

Вспомогательные методы класса

• getLastResponse() Возвращает последний ответ API SendPulse.
• request(string $method, string $path, array $params = []) ?array Отправляет запрос в API SendPulse и возвращает ответ.
  • $method - метод запроса (GET, POST, PATCH, PUT, DELETE);
  • $path - путь в URL запроса;
  • $params - параметры запроса.
• getAll(Closure $closure) :\Generator Позволяет загрузить все сущности заданного типа, возвращая генератор.
  • $closure - анонимная функция-замыкание для загрузки сущностей: $closure(int $offset), где $offset - смещение выдачи.

Примеры использования вспомогательных методов:

Вспомогательные классы

Класс HTTP

Класс \App\HTTP\HTTP обеспечивает:

• формирование POST запросов к API SendPulse по протоколу HTTPS;
• троттлинг запросов к API на требуемом уровне - не более 10-и запросов в секунду;
• вывод отладочной информации о запросах к API в STDOUT.

При возникновении ошибок выбрасывается исключение с объектом класса \App\HTTP\HTTPException.

Дополнительные параметры

Дополнительные параметры устанавливаются через публичные свойства объекта класса \App\HTTP\HTTP:

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

Примеры отладочных сообщений

Класс DebugLogger

Класс \App\DebugLogger\DebugLogger обеспечивает логирование запросов и ответов к API SendPulse в файл.
При возникновении ошибок выбрасывается исключение с объектом класса \App\DebugLogger\DebugLoggerException.

Методы класса

• static instance(string $logFileName = 'debug.log') :self
  Возвращает единственный объект данного класса для заданного лог-файла $logFileName.
  • $logFileName - имя лог-файла.
• save(mixed $info, object $object = null, string $header = null) :void Сохраняет подлежащую логированию информацию в файл.
  • $info - строка, массив или объект для логирования;
  • $object - ссылка на объект класса в котором выполняется логирование;
  • $header - строка заголовка для сохраняемой в лог файл информации.

Дополнительные параметры

Дополнительные параметры устанавливаются через публичные свойства класса \App\DebugLogger\DebugLogger:

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

Пример результатов логирования

Формат заголовков лога

• cb8lim0 - уникальный буквенно-цифровой [a-z0-9]+ идентификатор объекта класса DebugLogger, позволяющий находить в лог файле записи, созданные одним и тем же процессом;
• 2021-02-08 06:30:06.920716 +00:00 - дата и время сохранения информации с точностью до микросекунд;
• Δ0.219036 s - время, прошедшее с момента предыдущего сохранения информации в секундах и микросекундах;
• 0.65/2.00 MiB - данные об используемой оперативной памяти в единицах количества информации с двоичными приставками:
  • 0.65 - максимальный объем памяти, который был выделен PHP-скрипту системой;
  • 2.00 - реальный объем памяти, выделенный PHP-скрипту системой;
• 'Class: App\SendPulse\SendPulseAPI' - полное имя класса из которого сделано сохранение в лог файл.

Автор

© 2020-2021 andrey-tech

Лицензия

Данный код распространяется на условиях лицензии MIT.