README

Установка

Для подключения библиотеки к Вашему проекту используете следующую команду

composer require "vitaly-alexandrovich/afeg-client"

Использование клиента

Сперва необходимо инициировать клиент

$client = new \Afeg\Client('YOUR_API_KEY');

Где вместо YOUR_API_KEY необходимо указать Ваш действующий ключ для доступа к API сервиса.

Что бы сгенерировать новый Email ящик необходимо воспользоваться методом create

$email = $client->create();

Данный метод сгенерирует случайный email на случайном доступном на сервисе домене и вернет экземпляр класса Email для доступа к только что сгенерированному почтовому ящику.

Так же метод принимает 2 необязательных аргумента для указания точного домена (из доступных) и логина. Если какой-либо из данных параметров не указан используется случайный доступный как было показано выше.

Список доступных для использования доменов можно посмотреть используя статичный метод getAvailableDomain класс Client

// Получаем список досутпных для использования доменов
$availableDomains = \Afeg\Client::getAvailableDomains();

// Выбираем случайный домен
$randomDomain = $availableDomains[array_rand($availableDomains)];

// Генерируем случайный логин
$randomLogin = 'email' . rand(1111, 9999);

// Генерируем временную почту 
$email = (new \Afeg\Client('YOUR_API_KEY'))->create($randomDomain, $randomLogin);

Использование почты

Что бы узнать адрес только что сгенерированной почты можно воспользоваться методом getAdress экземпляра класса Email

$email->getAddress();

Что бы получить список новых сообщений на почте воспользуйтесь методом fetch

$response = $email->fetch();

либо fetchAll для получения всех писем (в т.ч. просмотренных ранее)

$response = $email->fetchAll();

Данные методы возвращают ответ содержащий список писем (массив с экземплярами класса Message для доступа к даным письма). В примере ниже показан пример листинга писем

$response = $email->fetchAll();

foreach ($response->getItems() as $id => $message) {
    print $message->getSenderName()    . PHP_EOL; // Имя отправителя
    print $message->getSenderEmail()   . PHP_EOL; // Email отправителя
    print $message->getSubject()       . PHP_EOL; // Заголовок письма
    print $message->getShortTime()     . PHP_EOL; // Коротка запись времени получения
    print $message->getTime()          . PHP_EOL; // Полная запись даты и времени получения письма
    print $message->getText()          . PHP_EOL; // Текстовое представление содержимого письма
    print $message->getHtml()          . PHP_EOL; // HTML представления содержимого письма
    print $message->getAttachments()   . PHP_EOL; // Закрепленные к пиьсму файлы

    // Для удобства получения отметки времени для дальнейшей работы с ней реализованы 2 доп. метода
    // getTime для получения отметки в виде Unix timestamp 
    print $message->getTime() . PHP_EOL; 

    // И getFormattedTime для форматирования отметки сразу в нужный для дальнейшей работы формат
    print $message->getFormattedTime('Y-m-d H:i:s') . PHP_EOL; 
}

Восстановление работы с email ящиком через время

Экземпляр класса Email возвращается из клиента при создании ящика, однако может потребоваться обратится к данному ящику через какое-то время. Для этого можно инициировать экземпляр данного класса, передав в констрктор email (адрес ящика к которому необходимо обратится) и инициированный с API ключем экземпляр клиента.

Сделать это можно следующим образом:

$email = new Email('login@example.com', Client('YOUR_API_KEY'));
$response = $email->fetchAll();

Ожидание нового сообщения

Для того чтобы получать новые сообщения из Ваших временных почт потребуется с некоторым интервалом проверять наличие новых писем с помощью метода fetch.

Что бы упростить данный процесс был добавлен специальный метод waitNewMessage, его использование выглядит следующим образом:

foreach ($email->waitNewMessage() as $id => $message) {
    // Здесь код Вашего приложения при получении нового сообщения
}

Так же данный метод имеет 1 необязательный аргумент задающий интервал времени (в секундах) с которым будет осуществлятся проверка. По умолчанию данный интервал равен 60 секундам.

Обработка ошибок

При взаимодействии с API сервиса могут возникнуть исключения следующих типов IncorrectResponseException и ServerErrorException.

Первый IncorrectResponseException возникает в случае если полученный от сервиса ответ не соответствует ожидаемому формату, второй ServerErrorException возникает в случае если на сервере API произошла ошибка (код ответа не соответсвует успешному).

Если необходимо обработать ошибку API вне зависимости от ее типа, можно использовать универсальный ApiException т.к. первые два унаследованы от него.

Пример обработки исключения выглядит следующим образом

$client = new \Afeg\Client('YOUR_API_KEY');

try {
    foreach($client->create()->waitNewMessage() as $message) {
        // Полученно новое сообщение
    }
} catch (\Afeg\Exceptions\ServerErrorException $exception) { 
    // Запрос к API не был выполнен
} catch (\Afeg\Exceptions\IncorrectResponseException $exception) { 
    // Полученные от API ответ имеет не корректный формат
}

Планы и готовность к production среде

Использование библиотеки в production среде только на Ваш страх и риск (хоть она и используется в работающих проектах).

В данный момент в библиотеки отсутствует корректная обработка ошибок и исключительных ситуаций которые могут возникнуть при взаимодействии с API (данная часть плохо описана в документации на которую я опирался при реализации). Надеюсь я найду время для того что бы разобраться с возможными ошибками самостоятельно, а так же для покрытия данной библиотеки тестами.

Только при соблюдении вышеописанных требований я смогу гарантировать корректную работу данной библиотеки.

vitaly-alexandrovich / afeg-client

Maintainers

Details