Boardbundle Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require xlabs/boardbundle
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Xlabs\BoardBundle\BoardBundle" --tag=config
   

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

   Xlabs\BoardBundle\BoardBundle::class,
   

3. First Use Case: Displaying a Board Inject the BoardManager service into a controller or service:

   use Xlabs\BoardBundle\Services\BoardManager;
   
   class BoardController extends Controller
   {
       protected $boardManager;
   
       public function __construct(BoardManager $boardManager)
       {
           $this->boardManager = $boardManager;
       }
   
       public function showBoard()
       {
           $board = $this->boardManager->getBoard('default');
           return view('board.show', compact('board'));
       }
   }
   

4. Configuration Check config/board.php for default settings (e.g., board storage, caching, or API endpoints).

Implementation Patterns

Common Workflows

1. Board Creation & Management Dynamically create boards via the BoardManager:

   $board = $this->boardManager->createBoard([
       'name' => 'Project Backlog',
       'columns' => ['To Do', 'In Progress', 'Done'],
   ]);
   

2. Card Operations Add cards to a board column:

   $card = $this->boardManager->addCardToColumn('board_id', 'column_id', [
       'title' => 'Fix Login Bug',
       'description' => 'User cannot log in...',
   ]);
   

3. Integration with Eloquent If the bundle uses Eloquent models, extend them for custom logic:

   namespace App\Models;
   
   use Xlabs\BoardBundle\Models\Board;
   
   class CustomBoard extends Board
   {
       protected static function boot()
       {
           parent::boot();
           static::addGlobalScope(new CustomBoardScope());
       }
   }
   

4. API-Driven Boards Fetch boards via API (if supported):

   $boards = $this->boardManager->fetchBoardsFromApi('https://api.example.com/boards');
   

5. Event Listeners Listen for board/card updates:

   // In EventServiceProvider
   protected $listen = [
       'Xlabs\BoardBundle\Events\BoardUpdated' => [
           'App\Listeners\LogBoardUpdate',
       ],
   ];
   

Integration Tips

• Frontend Integration: Use the bundle’s Blade directives (if available) or pass data to Vue/React for dynamic rendering.
• Middleware: Protect board routes with middleware (e.g., auth or custom BoardAccess).
• Testing: Mock BoardManager in unit tests:

  $this->mock(BoardManager::class)->shouldReceive('getBoard')->andReturn($mockBoard);
  

Gotchas and Tips

Pitfalls

1. Missing Configuration

   • Ensure config/board.php is published and updated if the bundle requires custom paths (e.g., storage for boards).
   • Default values may not match your needs (e.g., caching drivers).

2. Database Migrations

   • Run migrations after installation:

     php artisan migrate
     

   • If extending models, create custom migrations for additional fields.

3. API Rate Limits

   • If using external APIs, handle rate limits gracefully (e.g., retry logic or caching).

4. Namespace Collisions

   • The bundle may use Board, Card, or similar names. Prefix custom models/classes to avoid conflicts.

5. Caching Quirks

   • Clear caches after manual board updates:

     php artisan cache:clear
     php artisan view:clear
     

Debugging Tips

1. Log Board Operations Enable debug mode and log actions:

   \Log::debug('Board created:', ['data' => $board->toArray()]);
   

2. Check for Exceptions Wrap bundle calls in try-catch:

   try {
       $board = $this->boardManager->getBoard('invalid_id');
   } catch (\Xlabs\BoardBundle\Exceptions\BoardNotFoundException $e) {
       abort(404, 'Board not found');
   }
   

3. Inspect Raw Data Dump board/card data to verify structure:

   dd($this->boardManager->getBoard('default')->toArray());
   

Extension Points

1. Custom Board Storage Override storage logic by binding a custom repository:

   $this->app->bind(
       \Xlabs\BoardBundle\Repositories\BoardRepository::class,
       \App\Repositories\CustomBoardRepository::class
   );
   

2. Add Fields to Cards/Boards Extend Eloquent models and migrations:

   // app/Models/Card.php
   class Card extends \Xlabs\BoardBundle\Models\Card
   {
       protected $casts = [
           'priority' => 'integer',
       ];
   }
   

3. Custom Board Views Override Blade templates by publishing views:

   php artisan vendor:publish --tag=board-views
   

   Then modify resources/views/vendor/board/....

4. WebSocket Updates If real-time updates are needed, integrate with Laravel Echo/Pusher for live card/board changes.

5. API Extensions Add custom endpoints by extending the bundle’s routes:

   // routes/board.php
   Route::post('/boards/{board}/export', [BoardController::class, 'export']);