README

FlashMessageBundle 允许非常方便地设置或添加 Flash 消息。当我们需要向用户提供关于控制器操作状态的一些响应信息时，这非常有用。Flash 消息管理器与 Symfony\Component\HttpFoundation\Session\Flash\FlashBag 合作，并且每个消息设置都自动通过 Symfony\Component\Translation\Translation 进行翻译。

安装

使用 composer 安装包

composer require arturdoruch/flash-message-bundle

将包添加到应用程序内核。

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new ArturDoruch\FlashMessageBundle\ArturDoruchFlashMessageBundle(),
    );
}

配置

该包在您的应用程序配置中的 artur_doruch_flash_message 键下进行配置。

####classes

类型: 数组 默认

    success: success
    error: danger
    notice: warning

一个键值对数组，其中键是消息类型，值是 CSS 类名称。此参数允许定义在模板中用作 CSS 类名称的字符串，用于样式化显示消息。

// app/config/config.yml
artur_doruch_flash_message:
    classes:
        error: fail
        notice: notice
        custom: custom-class-name

要在模板中使用此参数，请调用 ad_flash_messages_class_name(type) 函数，并将消息类型作为参数。请参阅 Resources/views/messages.html.twig 文件。

控制器

通过服务 ad_flash_message 设置的每个消息都自动通过 Symfony\Component\Translation\Translation 进行翻译。

获取 flash 消息服务。

public function indexAction()
{
    $flash = $this->get('ad_flash_message');
    ...
}

设置、添加消息

默认情况下，Flash 消息使用 "messages" 域进行翻译。以 "add" 或 "set" 开头的方法将消息添加或设置到 Symfony\Component\HttpFoundation\Session\Flash\FlashBag，然后我们可以在视图模板中显示。

/**
 * Translates custom type message and sets it into session flash bag. Overrides previous message if was set.
 *
 * @param string      $type        Can be any string describing action status. For types: "success", "error", "notice"
 *                                 use dedicated methods "setSuccess", "setError", "setNotice".
 *
 * @param string|null $message     Message text. Given text is always translated by "Symfony\Component\Translation\Translation"
 *                                 with "message" domain as default (of course if exists any translations for given string).
 *                                 If $message is null then will be dynamically creates as "translationId" based
 *                                 on called controller action name in convention: "company_bundle_controller.action.$type".
 *                                 For example, if we call this method (and $message is null) in controller
 *                                 "App\DemoBundle\Controller\ProductController::createAction"
 *                                 then will be generated this "translationId" value: "app_demo_project.create.$type".
 *
 * @param array       $parameters  Parameters for translation message.
 * @param string|null $domain      Translation domain. As default is "messages".
 */
public function set($type, $message = null, array $parameters = array(), $domain = null) {}

/**
 * Adds and translates custom type flash message.
 */
public function add($type, $message = null, array $parameters = array(), $domain = null) {}

"set" 和 "add" 方法之间的区别很明显。"add" 将新消息添加到 flashBag 数组集合中，而 "set" 则用新集合覆盖现有的数组消息集合。

获取消息

以 "get" 开头的方法仅准备消息并返回它，而不会将其添加到 Symfony\Component\HttpFoundation\Session\Flash\FlashBag。如果您想返回翻译后的消息，这很有用。例如，如果您正在处理 REST API 或 Ajax 请求。

/**
 * Gets custom type translated flash message.
 * This method not adds message into session flash bug.
 * Just creates, translates and returns it.
 */
public function get($type, $message = null, array $parameters = array(), $domain = null) {}

您可以使用这些方便的方法而不是手动设置 $type。

/**
 * Available methods sets, adds or gets messages with concrete types: "Success", "Error", "Notice".
 */
public function setSuccess($message = null, array $parameters = array(), $domain = null) {}
public function setError($message = null, array $parameters = array(), $domain = null) {}
public function setNotice($message = null, array $parameters = array(), $domain = null) {}

public function addSuccess($message = null, array $parameters = array(), $domain = null) {}
public function adsError($message = null, array $parameters = array(), $domain = null) {}
public function addNotice($message = null, array $parameters = array(), $domain = null) {}

public function getSuccess($message = null, array $parameters = array(), $domain = null) {}
public function getError($message = null, array $parameters = array(), $domain = null) {}
public function getNotice($message = null, array $parameters = array(), $domain = null) {}

为 CRUD 操作添加或获取消息。

FlashMessageBundle 提供了在执行重复的 CRUD 操作时轻松设置 Flash 消息的方法。CRUD 操作的消息使用 "crudMessages" 域进行翻译。请参阅此包中的 Resources/translations/crudMessages.en.yml 文件。

/**
 * Adds and translates flash message for CRUD action.
 * Generates "translationId" based on given parameters values and/or
 * dynamically generated based on $entity value and called controller name.
 * Generated "translationId" has format "crud.action.type".
 * All CRUD messages are translated with "crudMessages" domain.
 * See 'Resources/translations/crudMessages.en.yml'.
 *
 * @param string $type         Can be any string describing action status. For types: "success", "error", "notice"
 *                             use dedicated methods "addCrudSuccess", "addCrudError", "addCrudNotice".
 *
 * @param string $entity       Persistence entity object or entity name. Is used as parameter %entity%
 *                             in translation files.
 *                             For more clarify see "Resources/translations/crudMessages.en.yml" file.
 *
 * @param null|string $item    Single entity object name. Is used as parameter %item% in translation files.
 *                             For more clarify see "Resources/translations/crudMessages.en.yml" file.
 *
 *                             If $item is null and $entity is object then
 *                             will attempt to call methods getName() on $entity object "$entity->getName()".
 *                             If method exists then $item will be filled by the returned value.
 *
 * @param null|string $action  This parameter is used for generate "translationId".
 *                             If null then $action is generated based on called controller action name.
 *                             For example if called controller is     "App\DemoBundle\Controller\ProductController::createAction"
 *                             $action will be "create".
 */
public function addCrud($type, $entity, $item = null, $action = null) {}

/**
 * Gets custom type translated flash message for CRUD action.
 * This method not adds message into session flash bug.
 * Just creates, translates and returns it.
 */
public function getCrud($type, $entity, $item = null, $action = null) {}

/**
 * Other available methods adds or gets CRUD messages with concrete types: "Success", "Error", "Notice".
 */
public function addCrudSuccess($entity, $item = null, $action = null) {}
public function addCrudNotice($entity, $item = null, $action = null) {}
public function addCrudError($entity, $item = null, $action = null) {}

public function getCrudSuccess($entity, $item = null, $action = null) {}
public function getCrudNotice($entity, $item = null, $action = null) {}
public function getCrudError($entity, $item = null, $action = null) {}

示例用法

public function indexAction()
{
    ...
    $flash = $this->get('ad_flash_message');

    // Set flash messages
    $flash->setSuccess();
    $flash->setError();
    $flash->set('customType', 'Some flash message');

    // Add another message for "success" type array collection.
    $flash->addSuccess('Another success message');
}

public function sendEmailAction()
{
    ...
    $flash = $this->get('ad_flash_message');

    // Set flash messages with custom domain
    // Email was successfully send.
    $parameters = array(
        '%user%' => 'John Doe'
    );
    $flash->setSuccess(null, $parameters, 'emailMessages');
    
    // Failure email sending.
    $flash->setError(null, array(), 'emailMessages');

    // Get flash message
    return new Response($flash->getSuccess(null, $parameters, 'emailMessages'));
}

#####CRUD 示例。

public function updateAction(Product $product, Request $request)
{
    ...
    $product->setName('Framework');
    
    // Create and valid form. If form is valid save entity and set flash message.
    
    $flash = $this->get('ad_flash_message');
    // Message will be "Product Framework has been updated."
    $flash->addCrudSuccess($product);
    
    // For this message in translation file "crudMessages" must be defined
    // new key 'crud.customaction.success'.
    $flash->addCrudSuccess('Product2', 'Bundle', 'customAction');
    // Add Crud message with custom type.
    $flash->add('customType', 'Product', 'Github');
    
    // Get message
    $updateSuccessMsg = $flash->getCrudSuccess($product);
}

##视图

###使用

要显示 Flash 消息，只需将此行代码写入您的基模板文件或任何您想放置的地方。

    {{ ad_flash_messages() }}

#####可选

    {{ ad_flash_messages_class_name(type) }}

此函数返回与给定消息类型参数相关的CSS类名。通过CSS样式自定义显示消息。查看如何配置CSS类名。

当然，您可以通过覆盖Resources/views/messages.html.twig文件来自定义整个消息模板。为此，将模板文件放入您的Symfony应用中的app/Resources/ArturDoruchFlashMessageBundle/views/messages.html.twig位置。