README

简介

此包为 Symfony2 提供邮件操作的底层支持。它支持通过抽象 API 处理邮件的创建、发送和退信消息。

安装

通过以下简单步骤安装此包

1. 将此包添加到您的项目中作为 composer 依赖

   // composer.json
   {
       // ...
       require: {
           // ...
           "instaclick/base-mail-bundle": "dev-master"
       }
   }

2. 将此包添加到您的应用程序内核中

   // application/ApplicationKernel.php
   public function registerBundles()
   {
       // ...
       $bundles[] = new IC\Bundle\Base\MailBundle\ICBaseMailBundle();
   
       return $bundles;
   }

配置包

默认情况下，任何创建的邮件都包含一个发件人名称和地址。这简化了实现时间并使代码更简洁。您可以随时更改这些值，但如果您选择负值，则可以全局配置此支持。

要定义默认的发件人名称和地址，请执行以下操作

ic_base_mail:
    composer:
        default_sender:
            name:    "InstaClick Mail Delivery"
            address: "noreply@instaclick.com"

此包还附带一个退信邮件处理器。由于各种原因，在处理将消息发送到用户邮箱的过程中，您还需要处理用户可能遇到的可能失败的情况。最好的例子是拼写错误的电子邮件地址。要配置退信邮件处理器，请配置包配置中的 mail_bounce 部分。

ic_base_mail:
    mail_bounce:
        mailhost: "imap.gmail.com"
        port:     993
        username: "%mailer_gmail_username%"
        password: "%mailer_gmail_password%"
        service:  "imap"
        option:   "ssl"
        mailbox:  "INBOX"

使用可用服务

此包的目的是简化邮件的创建、发送和处理可能的失败。这三个部分衍生出三个服务，可以被任何消费此包的应用程序使用。

Composer 服务

负责创建消息。配置默认发件人会自动将发件人名称和地址注入由该服务创建的任何消息。方法 setDefaultSenderName 和 setDefaultSenderAddress 提供了在必要时修改值的运行时能力。除了前面提到的方法外，此服务仅包含一个方法：createMessage；它初始化一个新消息，准备发送。

$composerService = $this->getContainer()->get('ic_base_mail.service.composer');
$message         = $composerService->createMessage();

消息实例包含许多可以通过其 API 定义的选项。默认情况下，任何消息都配置为 text/html 消息，而方法 setContentType 提供了修改此行为的能力。

消息 API 的接口如下

interface MessageInterface
{
    /**
     * Get the subject.
     *
     * @return string
     */
    public function getSubject();

    /**
     * Set the subject.
     *
     * @param string $subject
     */
    public function setSubject($subject);

    /**
     * Get the recipient.
     *
     * @return string
     */
    public function getRecipient();

    /**
     * Set the recipient.
     *
     * @param string $recipient
     */
    public function setRecipient($recipient);

    /**
     * Get the senderName.
     *
     * @return string
     */
    public function getSenderName();

    /**
     * Set the senderName.
     *
     * @param string $senderName
     */
    public function setSenderName($senderName);

    /**
     * Get the senderAddress.
     *
     * @return string
     */
    public function getSenderAddress();

    /**
     * Set the senderAddress.
     *
     * @param string $senderAddress
     */
    public function setSenderAddress($senderAddress);

    /**
     * Get the sender (as a composite value of name and address)
     *
     * @return array
     */
    public function getSender();

    /**
     * Get the replyTo address.
     *
     * @return array
     */
    public function getReplyTo();

    /**
     * Set the repylTo address.
     *
     * @param string $replyTo
     */
    public function setReplyTo($replyTo);

    /**
     * Get the returnPath.
     *
     * @return array
     */
    public function getReturnPath();

    /**
     * Set the returnPath.
     *
     * @param string $returnPath
     */
    public function setReturnPath($returnPath);

    /**
     * Get the templateName.
     *
     * @return string
     */
    public function getTemplateName();

    /**
     * Set the templateName.
     *
     * @param string $templateName
     */
    public function setTemplateName($templateName);

    /**
     * Get the parameterList.
     *
     * @return array
     */
    public function getParameterList();

    /**
     * Set the parameterList.
     *
     * @param array $parameterList
     */
    public function setParameterList(array $parameterList = array());

    /**
     * Get the contentType.
     *
     * @return string
     */
    public function getContentType();

    /**
     * Set the contentType.
     *
     * @param string $contentType
     */
    public function setContentType($contentType);

    /**
     * Check if this message is usable.
     *
     * @return boolean
     */
    public function isUsable();
}

发件人服务

在您的消息创建完成后，是时候发送它了。发件人服务通过提供一个名为 send 的公开方法来提供此支持。如果成功交付或失败，此方法返回一个布尔值。它不考虑退信邮件，因为这必须由 BounceMail 服务的消费者实现的一个异步操作。

// ...
$composerService = $this->getContainer()->get('ic_base_mail.service.composer');
$senderService   = $this->getContainer()->get('ic_base_mail.service.sender');

$message = $composerService->createMessage();

$message->setSubject('Email Delivery Service');
$message->setRecipient('user@domain.com');
$message->setTemplateName('ICCoreSiteBundle:EmailTemplates:welcome.html.twig');
$message->setParameterList(array('username' => 'Guilherme Blanco'));

$sentSuccessfully = $senderService->send($message);

退信邮件服务

待定