README

安装

要将库连接到您的项目，请使用以下命令

composer require "vitaly-alexandrovich/afeg-client"

使用客户端

首先需要初始化客户端

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

其中，YOUR_API_KEY 需要指定您用于访问 API 服务的有效密钥。

要生成新的电子邮件地址，请使用方法 create

$email = $client->create(); 

该方法将在随机可用的服务域上生成随机电子邮件地址，并返回用于访问刚刚创建的邮箱的 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();

这些方法返回包含邮件列表的响应，其中包含邮件实例的数组，用于访问这些邮件。以下示例展示了如何列出邮件。

$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 类的实例，但可能需要在一段时间后再次访问该邮箱。为此，可以初始化该类的实例，将电子邮件地址（要访问的邮箱地址）和通过 API 密钥初始化的客户端实例传递给构造函数。

可以这样操作

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

等待新消息

要接收临时邮箱的新消息，需要定期使用 fetch 方法检查新邮件的存在。

为了简化此过程，添加了特殊的方法 waitNewMessage，其使用方式如下

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

此方法还有一个可选参数，指定检查的时间间隔（秒）。默认间隔为 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交互中可能出现的错误和异常情况的有效处理（这部分在实现时所依赖的文档中描述得不够详细）。希望我能找到时间自行研究可能的错误，并为该库编写测试。

只有满足上述要求，我才能保证该库的正确运行。