Livewire Comments Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package Run:

   composer require vigstudio/livewire-comments
   

2. Publish Assets and Config Publish the required assets and configuration:

   php artisan vendor:publish --tag=vgcomment-assets-livewire
   php artisan vendor:publish --tag=vgcomment-config
   

3. Configure the Package Edit config/vgcomment.php to customize:

   • Route prefix (e.g., vgcomment).
   • Database connection (e.g., mysql).
   • Table names (e.g., vgcomments, vgcomment_files).
   • User model column mappings (e.g., name, email).
   • Moderation users (e.g., web => [1] for admin IDs).

4. Run Migrations Create the necessary database tables:

   php artisan migrate
   

5. Enable Comments on a Model Use the HasComments trait in your Eloquent model (e.g., Post.php):

   use Vigstudio\LivewireComments\Traits\HasComments;
   
   class Post extends Model
   {
       use HasComments;
   }
   

6. Add the Livewire Component Include the comment component in your Blade view:

   @livewire('vgcomment::comments', ['model' => $post], key($post->id))
   

7. Clear Caches Ensure changes take effect:

   php artisan optimize:clear
   

First Use Case: Adding Comments to a Blog Post

1. Model Setup Extend your Post model with HasComments:

   class Post extends Model
   {
       use HasComments;
   }
   

2. View Integration Add the Livewire component to your post view (e.g., resources/views/posts/show.blade.php):

   <div class="mt-8">
       @livewire('vgcomment::comments', ['model' => $post], key($post->id))
   </div>
   

3. Test the Flow

   • Visit a post page.
   • Submit a comment (with optional files, emojis, or markdown).
   • Verify the comment appears in real-time (Livewire updates the UI without a page reload).

Implementation Patterns

Core Workflows

1. Model Integration

• Pattern: Use the HasComments trait on any Eloquent model to enable comments.
• Example:

  class Article extends Model
  {
      use HasComments;
  }
  

• Key Methods:
  • $model->comments(): Access comments for the model.
  • $model->addComment($content, $userId): Programmatically add a comment.
  • $model->deleteComment($commentId): Delete a comment (if moderator).

2. Component Customization

• Pattern: Override the default Livewire component or its views.
• Steps:
  1. Publish the component views:

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

  2. Modify views in resources/views/vendor/vgcomment/.
  3. Extend the Livewire class (if needed) by creating a custom component:

     namespace App\Http\Livewire;
     
     use Vigstudio\LivewireComments\Http\Livewire\Comments;
     
     class CustomComments extends Comments
     {
         public function mount($model)
         {
             parent::mount($model);
             // Custom logic (e.g., pre-fill comment text)
         }
     }
     

  4. Use your custom component in Blade:

     @livewire('custom-comments', ['model' => $post], key($post->id))
     

3. Multi-Guard Authentication

• Pattern: Configure moderation users per guard in config/vgcomment.php:

  'moderation_users' => [
      'web' => [1, 2],    // Admin IDs for web guard
      'api' => [3, 4],    // Admin IDs for API guard
  ],
  

• Usage: The package automatically restricts moderation actions (e.g., deletion) to configured users.

4. File Uploads

• Pattern: Users can upload files (images, documents) via drag-and-drop or paste.
• Configuration:
  • Ensure FILESYSTEM_DISK in .env points to a writable disk (e.g., public or s3).
  • Customize allowed file types in config/vgcomment.php (if needed; defaults are provided).
• Frontend Handling: The component uses Alpine.js for interactive uploads. No additional JS required unless extending functionality.

5. Real-Time Updates

• Pattern: Comments update in real-time using Livewire’s reactivity.
• Requirements:
  • Ensure Laravel Echo is configured for broadcasting (if using notifications or real-time features).
  • No additional setup for basic comment rendering.
• Extending: Trigger custom events (e.g., CommentAdded) in the Comments Livewire class:

  public function addComment()
  {
      $this->validate([...]);
      $comment = $this->model->comments()->create([...]);
      $this->emit('commentAdded', $comment);
  }
  

6. Markdown and Emojis

• Pattern: Users can write comments in markdown or insert emojis via a picker.
• Customization:
  • Override the toolbar or editor views in resources/views/vendor/vgcomment/.
  • Disable markdown by modifying the Livewire component’s useMarkdown property.

Integration Tips

1. Database Schema

• The package creates tables for:
  • comments (main comments data).
  • files (attachments).
  • reactions (likes/reactions).
  • reports (user-reported comments).
  • settings (package configurations).
• Tip: Use php artisan vendor:publish --tag=vgcomment-migrations to inspect migrations before running migrate.

2. Asset Pipeline

• The package publishes Tailwind CSS and JS assets. If using Vite/Laravel Mix:
  • Ensure no conflicts with existing Tailwind configurations.
  • Customize the published CSS/JS in public/vendor/vgcomment/.

3. Localization

• Pattern: The package uses Blade translations. Override them by publishing the lang files:

  php artisan vendor:publish --tag=vgcomment-lang
  

• Modify resources/lang/vendor/vgcomment/ to add translations.

4. NSFW Filtering

• Pattern: The package includes NSFW image detection for uploads.
• Customization: Adjust the sensitivity threshold in config/vgcomment.php or disable it by setting 'nsfw_check' => false.

5. Guest Comments

• Note: Guest comments are partially supported (as of v1.0.11) but require additional setup:
  • Ensure anonymous users are handled in your auth system.
  • Customize the GuestComment model if needed.

6. Testing

• Pattern: Test comment flows with Livewire’s testing utilities:

  use Livewire\Livewire;
  
  public function test_comment_submission()
  {
      Livewire::test('vgcomment::comments', ['model' => $post])
          ->set('content', 'Test comment')
          ->call('addComment')
          ->assertSee('Test comment');
  }
  

• Tip: Use Livewire::test() to simulate user interactions (e.g., file uploads, emoji insertion).

Gotchas and Tips

Pitfalls

1. Key Collisions in Livewire Components

• Issue: Using the same key() for multiple comment components on a page can cause Livewire to reuse state unexpectedly.
• Fix: Ensure unique keys for each component:

  @livewire('vgcomment::comments', ['model' => $post], key('post-'.$post->id))
  

2. File Upload Paths

• Issue: If FILESYSTEM_DISK in .env is misconfigured, uploads will fail silently.
• Debug: Check storage/logs/laravel.log for FileNotFoundException or PermissionDeniedException.
• Fix: Verify the disk exists and is writable:

  php artisan storage:link
  

3. Recaptcha Configuration

• Issue: If recaptcha is enabled but not configured, the package will throw validation errors.
• Fix: Add your Recaptcha v3 site key and secret to .env:

  VGCOMMENT_RECAPTCHA_SITE_KEY=your_site_key
  VGCOMMENT_RECAPTCHA_SECRET_KEY=your_secret_key
  

4. **Tailwind CSS