Notice Board Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bkstg/notice-board-bundle
   

   Add to config/app.php under ExtraBundles:

   'bkstg\NoticeBoardBundle\NoticeBoardBundle' => ['all' => true],
   

2. Publish Assets

   php artisan vendor:publish --provider="Bkstg\NoticeBoardBundle\NoticeBoardBundle" --tag=public
   

   This creates a public/vendor/notice-board/ directory with JS/CSS.

3. First Use Case Display a simple notice in a Blade template:

   @noticeBoard
       @include('notice-board::default', [
           'title' => 'System Update',
           'message' => 'Maintenance scheduled for 2024-05-15',
           'type' => 'info'
       ])
   @endnoticeBoard
   

   Verify the notice appears in your layout (default: top-right corner).

Implementation Patterns

Core Workflows

1. Notice Types Use predefined types (info, success, warning, error) or extend via:

   // config/notice-board.php
   'types' => [
       'custom' => ['class' => 'bg-purple-500', 'icon' => 'bell'],
   ],
   

2. Dynamic Notices Trigger notices from controllers:

   use Bkstg\NoticeBoardBundle\NoticeBoard;
   
   public function store(Request $request)
   {
       $notice = new NoticeBoard();
       $notice->add('Success!', 'Data saved.', 'success');
   
       return redirect()->back();
   }
   

3. Conditional Rendering

   @if(noticeBoard()->has('warning'))
       @noticeBoard
           @include('notice-board::default', [
               'title' => 'Warning',
               'message' => noticeBoard()->get('warning')->message,
           ])
       @endnoticeBoard
   @endif
   

4. Stacking Notices

   $notice->add('Notice 1', 'Content 1', 'info')
          ->add('Notice 2', 'Content 2', 'warning');
   

Integration Tips

• Frontend Customization: Override default templates in resources/views/vendor/notice-board/.
• API Responses: Use noticeBoard()->toJson() for API responses:

  return response()->json(['data' => $data, 'notices' => noticeBoard()->toJson()]);
  

• Middleware: Inject notices globally via middleware:

  public function handle($request, Closure $next)
  {
      noticeBoard()->add('Global Notice', 'You have 3 unread messages.', 'info');
      return $next($request);
  }
  

Gotchas and Tips

Common Pitfalls

1. Asset Loading

   • Ensure public/vendor/notice-board/ is symlinked or copied to public/:

     php artisan notice-board:assets
     

   • If JS/CSS fails, check config/notice-board.php for asset_path override.

2. Notice Persistence

   • Notices are session-based by default. For persistent notices (e.g., admin panels), use:

     noticeBoard()->persist('warning', 'This is a persistent notice.');
     

3. Blade Directive Scope

   • @noticeBoard directives must be closed with @endnoticeBoard. Unclosed tags will break rendering.

4. Type Validation

   • Undefined types default to info. Validate in config/notice-board.php:

     'strict_types' => true, // Throws exception on invalid types
     

Debugging Tips

• Clear Notices: Use noticeBoard()->clear() to reset all notices.
• Log Notices: Enable debug mode in config/notice-board.php:

  'debug' => true, // Logs notices to Laravel logs
  

• Inspect Storage: Notices are stored in session('notice_board'). Dump with:

  dd(session('notice_board'));
  

Extension Points

1. Custom Templates Extend the default template by copying vendor/bkstg/notice-board-bundle/resources/views/default.blade.php to resources/views/vendor/notice-board/.

2. Notice Storage Override storage engine (e.g., database) by implementing Bkstg\NoticeBoardBundle\Contracts\NoticeStorageInterface.

3. Event Listeners Listen for notice events:

   // Event: NoticeBoard\Events\NoticeAdded
   NoticeBoard::add('Custom Event', 'Triggered!', 'info');
   

4. Translation Override translations in resources/lang/en/notice-board.php:

   return [
       'types' => [
           'info' => 'Information',
           'custom' => 'Custom Alert',
       ],
   ];