Laraboard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require christhompsontldr/laraboard
   

   Run migrations:

   php artisan migrate
   

   Publish assets/config:

   php artisan vendor:publish --provider="Laraboard\LaraboardServiceProvider"
   

2. First Use Case

   • Register a new user via php artisan laraboard:install (creates admin user).
   • Access /forum to see the default forum structure (categories, threads, posts).
   • Use Livewire components (e.g., create-thread) to interact with the UI.

3. Key Files to Review

   • config/laraboard.php (core settings like permissions, default categories).
   • resources/views/forum/ (Livewire component templates).
   • app/Providers/LaraboardServiceProvider.php (service binding).

Implementation Patterns

Core Workflows

1. Thread Management

   • Create: Use CreateThread Livewire component (triggered via /forum/create).
   • Edit: Extend EditThread component or override ThreadController@update.
   • Soft Delete: Leverage venturecraft/revisionable for rollback via Thread::withRevision($id)->restore().

2. Permissions

   • Use Laratrust for role-based access:

     // Assign a user to a role (e.g., 'moderator')
     $user->attachRole('moderator');
     
     // Check permissions in policies
     public function update(User $user, Thread $thread) {
         return $user->hasRole('moderator') || $thread->user_id === $user->id;
     }
     

3. Search & Scouting

   • Scout integration for search:

     // Add to Thread model
     public function toSearchableArray() {
         return [
             'title' => $this->title,
             'body' => $this->body,
             'slug' => $this->slug,
         ];
     }
     

   • Search via:

     $threads = Thread::search('laravel')->get();
     

4. Markdown Support

   • Use artisanry/parsedown for post content:

     use Artisanry\Parsedown\Parsedown;
     $parsedown = new Parsedown();
     $html = $parsedown->text($post->body);
     

5. Livewire Integration

   • Extend components by publishing views:

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

   • Example: Override resources/views/vendor/laraboard/thread.blade.php.

Integration Tips

• Custom Categories: Add via seeder or Tinker:

  use Laraboard\Models\Category;
  Category::create(['name' => 'Dev', 'slug' => 'dev']);
  

• Notifications: Extend EventServiceProvider to listen to ThreadCreated events.
• API Endpoints: Use Laravel’s API resources to expose threads:

  Route::apiResource('threads', 'ThreadController')->middleware('auth:api');
  

Gotchas and Tips

Pitfalls

1. Laravel Version Lock

   • Issue: Package targets Laravel 5.4 (2017). May conflict with modern Laravel (e.g., scout v8 vs. v9+).
   • Fix: Override Scout driver in config/laraboard.php or use a compatibility layer.

2. Livewire Version Mismatch

   • Issue: Livewire v1.x is outdated. UI components may break with newer Livewire.
   • Fix: Fork the package or patch Livewire calls (e.g., wire:model → v-model in Blade).

3. Permission Overrides

   • Issue: Laratrust v5.x may not integrate smoothly with Laravel’s newer auth.
   • Fix: Extend Laraboard\Policies\ThreadPolicy or use Gates:

     Gate::define('delete-thread', function (User $user, Thread $thread) {
         return $user->isAdmin();
     });
     

4. Asset Paths

   • Issue: Published assets (CSS/JS) may not resolve post-install.
   • Fix: Run php artisan optimize:clear or manually link assets in web.php:

     Vite::asset('resources/css/laraboard.css');
     

Debugging Tips

• Query Logging: Enable Scout logging for search issues:

  'scout' => [
      'driver' => 'database',
      'log' => env('SCOUT_LOG', true),
  ],
  

• Livewire Debugging: Use php artisan livewire:discover to regenerate components.
• Revisionable Conflicts: Disable if not needed:

  // In AppServiceProvider boot()
  \VentureCraft\Revisionable\Revisionable::ignoreModels(['Thread']);
  

Extension Points

1. Custom Fields

   • Extend Thread model with morph maps:

     public function morphTo() {
         return 'thread';
     }
     

   • Store extra data in a pivot table (e.g., thread_extra_attributes).

2. Email Notifications

   • Override ThreadCreated event listener in EventServiceProvider:

     ThreadCreated::class => [
         \App\Listeners\SendThreadNotification::class,
     ],
     

3. Theming

   • Override Blade partials (e.g., _partials/thread-card.blade.php) in resources/views/vendor/laraboard/.
   • Use CSS variables for dynamic theming:

     :root {
         --laraboard-primary: #{$config['colors']['primary']};
     }
     

4. API Extensions

   • Add custom API routes in routes/api.php:

     Route::get('/threads/{thread}/stats', [ThreadController::class, 'stats']);