Laravel Support Bubble Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-support-bubble
   php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag="config"
   php artisan migrate
   

   Publish the config and run migrations to set up the database table for support requests.

2. Configuration: Edit config/support-bubble.php to customize:

   • chat_bubble (enabled/disabled, position, styling)
   • support_form (fields, validation, honeypot settings)
   • notifications (webhook or email settings for new requests)

3. First Use Case: Add the chat bubble to your layout (e.g., resources/views/layouts/app.blade.php):

   @supportBubble
   

   This renders the default bubble with TailwindCSS styling. Test by visiting any page—logged-out users will see the bubble.

Implementation Patterns

Core Workflows

1. Customizing the Bubble:

   • Override the default view (resources/views/vendor/support-bubble/chat-bubble.blade.php) to modify appearance.
   • Extend the bubble’s JavaScript behavior by publishing assets:

     php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag="public"
     

     Then override resources/js/support-bubble.js.

2. Handling Support Requests:

   • Listen for SupportBubble\Events\SupportRequestReceived to process submissions:

     use Spatie\SupportBubble\Events\SupportRequestReceived;
     
     SupportRequestReceived::listen(function (SupportRequest $request) {
         // Send to CRM, Slack, or queue for review
     });
     

   • Use the SupportRequest model to query or update submissions:

     use Spatie\SupportBubble\Models\SupportRequest;
     
     $recentRequests = SupportRequest::latest()->take(10)->get();
     

3. Conditional Display:

   • Disable the bubble for specific routes or user roles in the config:

     'chat_bubble' => [
         'enabled' => true,
         'except' => ['admin.*', 'support.*'],
         'for_guests_only' => true, // Hide for logged-in users
     ],
     

   • Dynamically toggle visibility in Blade:

     @if(!auth()->check())
         @supportBubble
     @endif
     

4. Localization:

   • Publish language files and translate labels:

     php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag="lang"
     

     Override resources/lang/en/support-bubble.php for custom text.

5. Integration with Frontend Frameworks:

   • For Vue/React, use the @supportBubble directive in your root component and manage state locally if needed.
   • Example (Vue):

     <template>
       <div>
         @supportBubble
         <button @click="toggleBubble">Toggle Support</button>
       </div>
     </template>
     
     <script>
     export default {
       methods: {
         toggleBubble() {
           // Dispatch custom event to hide/show bubble
           document.dispatchEvent(new CustomEvent('supportBubble:toggle'));
         }
       }
     };
     </script>
     

Gotchas and Tips

Pitfalls

1. Honeypot Misconfiguration:

   • If spam submissions persist, verify the honeypot field name in config/support-bubble.php matches the form:

     'honeypot' => [
         'field_name' => 'website', // Default; ensure this matches your form
     ],
     

   • Test with a hidden field in your form:

     <input type="text" name="website" style="display: none;">
     

2. CSRF Token Issues:

   • Ensure the support form includes {!! csrf_field() !!} or the meta tag in your layout:

     @csrf
     

   • If using AJAX submissions, include the token in headers:

     headers: {
       'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content
     }
     

3. Database Schema Conflicts:

   • If extending the SupportRequest model, run php artisan migrate after adding new fields to avoid schema errors.
   • Backup the support_requests table before customizing migrations.

4. TailwindCSS Conflicts:

   • If the bubble’s styling clashes with your app, override Tailwind classes in your published CSS or use !important sparingly:

     .support-bubble {
       @apply !important your-custom-classes;
     }
     

5. Performance with Heavy Forms:

   • Disable the bubble for high-traffic pages (e.g., checkout) via except in config to reduce render time.
   • Lazy-load the bubble with JavaScript if critical:

     if (window.location.pathname !== '/checkout') {
       // Load @supportBubble dynamically
     }
     

Debugging Tips

1. Log Support Requests: Add a listener to debug submissions:

   SupportRequestReceived::listen(function ($request) {
       \Log::info('Support Request', ['data' => $request->toArray()]);
   });
   

2. Check JavaScript Errors: Inspect the browser console for errors like Uncaught ReferenceError: SupportBubble is not defined. Ensure:

   • The @supportBubble directive is placed after jQuery (if used) and before </body>.
   • No ad-blockers are interfering with the bubble’s script.

3. Verify Webhook Notifications: If using webhooks, test with curl or Postman to ensure the endpoint is reachable:

   curl -X POST -H "Content-Type: application/json" -d '{}' http://your-app.test/api/support-bubble/webhook
   

Extension Points

1. Custom Validation: Extend the SupportRequest model’s $fillable and add validation rules in AppServiceProvider:

   use Spatie\SupportBubble\Models\SupportRequest;
   
   SupportRequest::observe(SupportRequestObserver::class);
   
   class SupportRequestObserver {
       public function saving(SupportRequest $request) {
           $request->validate([
               'custom_field' => 'required|string',
           ]);
       }
   }
   

2. Add Attachments: Extend the form to include file uploads:

   <input type="file" name="screenshot">
   

   Update the SupportRequest model to handle files:

   use Illuminate\Http\UploadedFile;
   
   public function setScreenshotAttribute(UploadedFile $file) {
       $this->attributes['screenshot'] = $file->store('support-bubble');
   }
   

3. Multi-Language Support: Dynamically set the language based on user locale:

   // In AppServiceProvider
   SupportBubble::setLocale(app()->getLocale());
   

4. Analytics Integration: Track bubble interactions with Google Analytics or Mixpanel:

   document.addEventListener('supportBubble:open', () => {
       gtag('event', 'support_bubble_opened', { page_path: window.location.pathname });
   });
   

5. Dark Mode Support: Add a data-theme attribute to the bubble and toggle via JavaScript:

   <div class="support-bubble" data-theme="light">
   

   const bubble = document.querySelector('.support-bubble');
   bubble.dataset.theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';