Boardbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require atm/boardbundle
   

   Register the bundle in config/app.php under providers:

   Atm\BoardBundle\AtmBoardBundle::class,
   

2. Publish Assets & Config Run:

   php artisan vendor:publish --provider="Atm\BoardBundle\AtmBoardBundle" --tag=config
   php artisan vendor:publish --provider="Atm\BoardBundle\AtmBoardBundle" --tag=assets
   

   This generates:

   • config/atm_board.php (default config)
   • Assets (JS/CSS) in public/vendor/atm_board/

3. First Use Case: Display a Board Define a board in your config (config/atm_board.php):

   'boards' => [
       'default' => [
           'title' => 'My Board',
           'columns' => [
               'todo' => ['title' => 'To-Do'],
               'in_progress' => ['title' => 'In Progress'],
               'done' => ['title' => 'Done'],
           ],
       ],
   ],
   

   Render the board in a Blade template:

   @board('default')
   

Implementation Patterns

1. Dynamic Board Configuration

• Runtime Overrides: Use dependency injection to pass custom board data:

  $boardData = [
      'title' => 'Dynamic Board',
      'columns' => [...],
  ];
  return view('my_view')->withBoard($boardData);
  

  Render with:

  @board($boardData)
  

• Database-Driven Boards: Fetch board data from a DB table (e.g., boards) and pass it to the view:

  $board = Board::find($id);
  return view('board')->with('board', $board);
  

2. Customizing Cards

• Card Templates: Extend the default card rendering by publishing the view:

  php artisan vendor:publish --provider="Atm\BoardBundle\AtmBoardBundle" --tag=views
  

  Override resources/views/vendor/atm_board/card.blade.php.

• Card Data: Pass additional data to cards via the board config:

  'columns' => [
      'todo' => [
          'title' => 'To-Do',
          'cards' => [
              ['title' => 'Task 1', 'description' => 'Details...', 'status' => 'pending'],
          ],
      ],
  ],
  

3. Integration with Laravel Features

• Authorization: Use Laravel’s gates/policies to restrict board access:

  Gate::define('view-board', function ($user, $board) {
      return $user->canAccessBoard($board);
  });
  

  Check in Blade:

  @can('view-board', $board)
      @board($board)
  @endcan
  

• Events: Listen for board/card updates:

  event(new \Atm\BoardBundle\Events\BoardUpdated($boardId));
  

4. API Endpoints

• Expose Board Data via API:

  Route::get('/api/boards/{id}', [BoardController::class, 'show']);
  

  Return JSON:

  return response()->json($boardData);
  

Gotchas and Tips

Pitfalls

1. Asset Paths

   • If assets fail to load, verify the public/vendor/atm_board/ directory exists and permissions are correct.
   • Clear cached views:

     php artisan view:clear
     

2. Config Merging

   • Custom config values in config/atm_board.php must merge with defaults. Use:

     'boards' => array_merge($defaultBoards, [
         'custom_board' => [...],
     ]),
     

3. Blade Directive Scope

   • The @board directive requires the AtmBoardBundle service provider to be registered before the view is rendered. Place it early in config/app.php.

4. Nested Data Issues

   • Ensure columns and cards arrays are properly structured. Validate with:

     $this->validate($request, [
         'columns.*' => 'array',
         'columns.*.cards' => 'array',
     ]);
     

Debugging Tips

• Log Board Data: Dump the board config before rendering:

  \Log::debug('Board config:', ['config' => config('atm_board.boards')]);
  

• Check Published Views: If customizations aren’t applied, verify the override path (resources/views/vendor/atm_board/).

Extension Points

1. Custom Directives Extend the @board directive by binding a new one in AppServiceProvider:

   Blade::directive('customBoard', function ($expression) {
       return "<?php echo \Atm\BoardBundle\Board::renderCustom($expression); ?>";
   });
   

2. Service Container Binding Bind a custom board resolver:

   $this->app->bind(\Atm\BoardBundle\Contracts\BoardResolver::class, function () {
       return new CustomBoardResolver();
   });
   

3. Event Listeners Subscribe to board events in EventServiceProvider:

   protected $listen = [
       \Atm\BoardBundle\Events\BoardUpdated::class => [
           \App\Listeners\LogBoardUpdate::class,
       ],
   ];
   

Performance

• Cache Board Config: If boards are static, cache the config:

  Cache::remember('atm_board_config', now()->addHours(1), function () {
      return config('atm_board.boards');
  });