Вспомогательные функции и константы
Что ещё определяет пакет помимо методов клиента.
Статические методы
| Метод | Что это |
|---|---|
| OpenEmail::init(), OpenEmail::getClient() | Настройте общий клиент один раз и обращайтесь к нему откуда угодно. Если init так и не был вызван, getClient() соберёт клиент из окружения. |
| OpenEmail::resetClient() | Сбрасывает общий клиент, так что следующий getClient() соберёт новый. Именно это нужно тесту между отдельными случаями. |
| new OpenEmail(), OpenEmail::createClient() | Отдельный клиент. Оба берут из окружения всё, что вы не указали. |
| OpenEmail::createTempMail() | Клиент одноразовых ящиков без API-ключа. |
| OpenEmail::verifyWebhookSignature() | Проверяет подпись доставки за постоянное время, с пятиминутным окном защиты от повторов, которое меняет toleranceSeconds:. Возвращает декодированное событие и при любом сбое выбрасывает WebhookSignatureException. |
| OpenEmail::toBase64() | Base64 для байтов вложения из строки, ресурса потока, SplFileInfo или потока PSR-7. |
| OpenEmail::isApiKey() | Имеет ли значение форму oe_live_ или oe_test_. Это проверка формы, а не доказательство того, что ключ ещё работает. |
| OpenEmail::isAccessToken() | Имеет ли значение форму токена доступа OAuth: от 1 до 512 символов, не начинается с oe_. |
| OpenEmail::isSealed() | Является ли тело сообщения шифротекстом. Равно false для двух подписанных форматов, тела которых пришли открытыми. |
| OpenEmail::resolveLanguage(), OpenEmail::languageByCode(), OpenEmail::isRtlLanguage() | Поиск, который нужен списку выбора языка, по встроенной таблице Languages::ALL. |
| $client->close() | Освобождает дескриптор cURL клиента и стоящее за ним соединение. Клиент, на который больше нет ссылок, делает то же самое, когда PHP его освобождает. |
Константы
Каждый набор значений, который экспортирует TypeScript SDK, является final-классом в OpenEmail\Constants с одной константой на каждый член под теми же именами, поэтому WebhookEvents::EMAIL_DELIVERED равно email.delivered. values() возвращает весь набор, и так же проверяется значение, пришедшее извне.
use OpenEmail\Constants\ApiScopes;use OpenEmail\Constants\PageLimits;use OpenEmail\Constants\WebhookEvents; $events = WebhookEvents::values(); $scopes = [ApiScopes::EMAILS_SEND, ApiScopes::THREADS_READ]; $known = in_array('email.delivered', $events, true); echo count($events), ' ', implode(',', $scopes), ' ', PageLimits::MAX_LIMIT, ' ', $known ? 'known' : 'unknown', PHP_EOL;| Константа | Что в нём |
|---|---|
| OpenEmail::VERSION | Версия пакета. |
| ApiScopes | Словарь областей для экрана создания ключа. |
| WebhookEvents, WebhookSignatureHeaders | События, на которые может подписаться эндпоинт, и имена заголовков, которые несёт доставка. |
| ErrorTypes | Словарь ошибок, значения из которого принимает ApiException::$type. |
| PageLimits | Наибольшее значение и значение по умолчанию для limit: в большинстве постраничных списков, MAX_LIMIT и DEFAULT_LIMIT: 100 и 25. Несколько списков принимают больше, и справочник каждого метода об этом говорит. |
| RuleFields, RuleOperators, RuleActions | Словарь, из которого строятся условия и действия правила. |
| MessageEncryptionFormats | Пять конвертов, которые может назвать приём почты. Три из них запечатаны. |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | Какие учётные данные описывают me->get и me->ping, как проверяется код подтверждения и с какими кодами может не пройти подтверждение. |
| ThreadSorts, PeopleSorts, FileSorts и другие *Sorts | Порядки, в которых можно сортировать список. |
| FormStatuses, BroadcastStatuses, SuppressionReasons и другие наборы | Значения, которые может принимать поле ресурса. Каждый набор назван по тому, что в нём содержится. |
| Languages::ALL | Все языки, которые принимает отправка или предпросмотр с переводом, с их кодом, названиями и направлением письма. |
Объекты
Ответ представляет собой декодированный JSON в виде ассоциативного массива. Пакет строит собственный объект только там, где он придаёт ответу форму, и каждый такой объект находится в OpenEmail\Result, неизменяем и является IteratorAggregate и Countable по своим строкам.
| Класс | Что несёт |
|---|---|
| Page | items, hasMore и nextCursor из каждого постраничного list. |
| PeoplePage | То же плюс seen, из contacts->listPeople. |
| TempMessagesPage | То же плюс expiresAt, из tempMail->listMessages. |
| AddressBookPage, AddressBook | unrestricted, addresses и domains из addresses->list (с hasMore и nextCursor) и addresses->listAll. |
| BatchResult | items, sent и failed из emails->sendBatch. |
| TemplateSends | items, total, page и pageSize из templates->listSends. |
| OpenEmail\Http\HttpRequest, OpenEmail\Http\HttpResponse | Что получает и возвращает httpClient:. var_dump(), print_r() и json_encode() показывают заголовок Authorization запроса как [redacted], а var_export() и dump() из Symfony показывают его как есть. |
Каждое исключение, которое выбрасывает пакет, реализует OpenEmail\Exception\OpenEmailException: ApiException и его подклассы, NetworkException, WebhookSignatureException и InvalidArgumentException, которое выбрасывается из-за ошибки в самом вызове, а не из-за ответа API.
Эндпоинт, который пока не обёрнут
Выпуск пакета никогда не должен стоять между вами и эндпоинтом, который уже работает. $client->raw->request() принимает путь и именованные аргументы и возвращает декодированное тело, применяя учётные данные клиента, базовый URL, таймаут и политику повторов.
$result = $client->raw->request( '/labels', method: 'POST', query: ['dryRun' => true], body: ['name' => 'Invoices'], repeatable: true,); var_dump($result);GET повторяется, как любое другое чтение. Любой другой метод отправляется один раз, если вы не передадите repeatable: true, то есть не заявите, что его можно отправить дважды. query: пропускает значения null и пустые, а apiKey: работает так же, как в любом другом методе.
Чего он намеренно не делает
- Он не проверяет тело запроса. Схема сервера является единственной копией правил, а вторая копия здесь рано или поздно отклонила бы адрес, который принимает более новый сервер, в версии, которую кто-то закрепил два года назад.
- У него нет зависимостей во время выполнения, кроме расширений curl и json. Клиент PSR-18 остаётся возможностью, а не требованием.
- Он меняет форму ответа только одним способом: массив
dataколлекции извлекается из конверта в один из объектов выше. Любой другой ответ возвращается так, как его прислал API, с ключами API в camelCase.
Проверка соответствия пакета следит за этим. Она роняет сборку, когда у метода TypeScript нет двойника на PHP, когда он принимает другие аргументы или отправляет другой запрос.