README

简介

本扩展包为 Symfony2 提供了邮件操作的底层支持。它支持通过抽象 API 处理邮件的编写、发送和退信处理。

安装

安装此扩展包可以通过以下简单步骤完成

将此扩展包添加到项目中的 composer 依赖项

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

在应用程序内核中添加此扩展包

// 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);

instaclick / base-mail-bundle

维护者

详细信息

README

简介

安装

配置扩展包

使用可用的服务

Composer 服务

发送服务