Flash Message Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require arturdoruch/flash-message-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       ArturDoruch\FlashMessageBundle\ArturDoruchFlashMessageBundle::class => ['all' => true],
   ];
   

2. First Use Case In a controller, inject the flash service and set a success message:

   use Symfony\Component\HttpFoundation\Request;
   
   public function createAction(Request $request)
   {
       $flash = $this->get('ad_flash_message');
       $flash->setSuccess(); // Auto-generates translation ID based on controller/action
   
       return $this->redirectToRoute('home');
   }
   

3. Display in Twig Add this to your base template (e.g., base.html.twig):

   {{ ad_flash_messages() }}
   

Implementation Patterns

Common Workflows

1. Standard Flash Messages Use setSuccess(), setError(), or setNotice() for common cases:

   $flash->setSuccess('User created successfully');
   $flash->setError('Failed to save user');
   

2. CRUD Operations Leverage auto-generated translations for entities:

   $flash->addCrudSuccess($user); // "User {name} was updated."
   $flash->addCrudError($product, 'Bundle'); // "Failed to create Product Bundle."
   

3. Custom Types Define new types in config/packages/artur_doruch_flash_message.yaml:

   artur_doruch_flash_message:
       classes:
           warning: 'alert-warning'
           info: 'alert-info'
   

   Use in controller:

   $flash->set('warning', 'This is a warning');
   

4. Translation Domains Override default messages domain for specific contexts:

   $flash->setSuccess(null, [], 'validation'); // Uses `validation` translation domain
   

5. API/JSON Responses Return flash messages directly without storing in session:

   return new JsonResponse([
       'message' => $flash->getSuccess('User saved')
   ]);
   

Integration Tips

• Form Handling: Combine with Symfony’s form validation to show errors:

  if ($form->isSubmitted() && !$form->isValid()) {
      $flash->setError('Invalid data');
      return $this->redirectToRoute('edit', ['id' => $id]);
  }
  

• Event Listeners: Trigger flash messages in event subscribers:

  $flash = $this->container->get('ad_flash_message');
  $flash->setNotice('Resource updated');
  

• Twig Extensions: Extend the bundle’s Twig functions in your own bundle to add custom logic.

Gotchas and Tips

Pitfalls

1. Translation IDs

   • If $message is null, the bundle auto-generates IDs like bundle.controller.action.type.
   • Ensure translations exist for these IDs (e.g., app_demo_user.create.success).
   • Fix: Predefine translations in translations/messages.en.yaml or use explicit messages.

2. Session Dependency Flash messages rely on the session. For APIs or CLI commands, use get() instead of set()/add():

   $message = $flash->getSuccess(); // No session storage
   

3. Overwriting Messages

   • set() replaces all messages of a type, while add() appends.
   • Tip: Use add() for multiple messages (e.g., validation errors).

4. Entity Auto-Detection

   • For addCrud(), if $item is null and $entity is an object, it calls $entity->getName().
   • Gotcha: If getName() doesn’t exist, $item will be null in translations.
   • Fix: Pass $item explicitly or implement getName().

5. CSS Classes

   • Default classes (success, error, notice) map to Bootstrap classes.
   • Customization: Override in config or Twig:

     <div class="{{ ad_flash_messages_class_name('custom') }}">{{ message }}</div>
     

Debugging

1. Missing Translations

   • Check translations/messages.en.yaml or crudMessages.en.yaml for missing keys.
   • Debug: Temporarily disable translation to see raw messages:

     $flash->set('error', 'Raw error message', [], null); // $domain = null
     

2. Flash Messages Not Displaying

   • Verify {{ ad_flash_messages() }} is in the template after the redirect.
   • Symfony 4+: Ensure the bundle is enabled in config/bundles.php.

3. CRUD Messages

   • Confirm the translation ID format: crud.{action}.{type} (e.g., crud.update.success).
   • Debug: Log the generated ID:

     $flash->addCrudSuccess($entity);
     error_log($flash->getCrudSuccess($entity)); // Check the output
     

Extension Points

1. Custom Twig Functions Override the default messages.html.twig in templates/bundles/arturdoruchflashmessage/messages.html.twig:

   {% for type, messages in ad_flash_messages() %}
       {% for message in messages %}
           <div class="alert alert-{{ type }} custom-style">
               {{ message }}
           </div>
       {% endfor %}
   {% endfor %}
   

2. Service Extensions Extend the flash service in your bundle’s services.yaml:

   services:
       app.flash_extension:
           class: App\Service\FlashExtension
           arguments: ['@ad_flash_message']
           tags: [kernel.event_subscriber]
   

3. Translation Overrides Override bundle translations in translations/crudMessages.en.yaml:

   crud:
       update:
           success: "The {entity} '{item}' was updated successfully."
   

4. Dynamic Message Types Add logic to the service by extending the class:

   use ArturDoruch\FlashMessageBundle\FlashMessageManager;
   
   class CustomFlashManager extends FlashMessageManager {
       public function setInfo($message) {
           $this->set('info', $message);
       }
   }
   

   Register the service in services.yaml:

   services:
       ad_flash_message:
           class: App\Service\CustomFlashManager
           public: true