Laravel Support Form Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   Publish the config, assets, and views to customize defaults.

2. 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 minimal configuration.

3. Configuration: Update .env with your support email:

   SUPPORT_BUBBLE_EMAIL=support@example.com
   

   Customize further in config/support-bubble.php (e.g., bubble position, colors, or form fields).

Implementation Patterns

Core Workflows

1. Integration with Layouts: Use the @supportBubble directive in your base template to ensure the bubble appears on all pages. For selective pages, conditionally render it:

   @if(request()->is('/contact') || request()->is('/pricing'))
       @supportBubble
   @endif
   

2. Customizing the Form: Extend the default form by publishing views:

   php artisan vendor:publish --tag="support-bubble-views"
   

   Modify resources/views/vendor/support-bubble/form.blade.php to add/remove fields (e.g., custom dropdowns or file uploads).

3. Handling Submissions: Listen for form submissions via the SupportBubbleSubmitted event:

   use Spatie\SupportBubble\Events\SupportBubbleSubmitted;
   
   SupportBubbleSubmitted::listen(function (SupportBubbleSubmitted $event) {
       // Log, notify Slack, or process the submission
       Log::info('Support bubble submission', $event->supportBubbleData);
   });
   

4. Dynamic Bubble Visibility: Toggle the bubble based on user segments (e.g., logged-out users only):

   // config/support-bubble.php
   'visible' => function () {
       return !auth()->check();
   },
   

5. Localization: Translate the bubble and form using Laravel’s localization:

   php artisan vendor:publish --tag="support-bubble-lang"
   

   Update resources/lang/en/support-bubble.php and add translations for other locales.

Advanced Patterns

1. Custom Styling: Override TailwindCSS classes in the published views or use inline styles:

   <div class="support-bubble custom-class" x-data="supportBubble()">
       <!-- Custom content -->
   </div>
   

   Extend the supportBubble() Alpine.js component in a custom JS file.

2. API-Based Submissions: Replace the default email logic to store submissions in a database or send via API:

   // app/Providers/SupportBubbleServiceProvider.php
   public function boot()
   {
       SupportBubbleSubmitted::listen(function ($event) {
           SupportBubble::create($event->supportBubbleData);
           // Or send to a third-party API
       });
   }
   

3. Multi-Tenant Support: Scope submissions to tenants using a trait or middleware:

   // app/Models/SupportBubble.php
   use Spatie\Multitenancy\Tenancy;
   
   class SupportBubble extends Model
   {
       public static function boot()
       {
           parent::boot();
           static::creating(function ($model) {
               $model->tenant_id = Tenancy::tenant()->id;
           });
       }
   }
   

4. A/B Testing: Randomize bubble visibility or styling for experiments:

   'visible' => function () {
       return request()->has('ab_test') && request()->ab_test === 'show_bubble';
   },
   

Gotchas and Tips

Pitfalls

1. Honeypot Misconfiguration:

   • If spam submissions persist, verify the honeypot field (support-bubble::form) is hidden but included in the form. Example:

     <div class="hidden">
         <input type="text" name="honeypot" />
     </div>
     

   • Ensure the field name matches the config (honeypot_field in config/support-bubble.php).

2. Alpine.js Conflicts:

   • If the bubble doesn’t toggle, check for Alpine.js version conflicts. Use ^3.0 in package.json:

     "alpinejs": "^3.10.2"
     

   • Clear cached views if Alpine.js behavior is inconsistent:

     php artisan view:clear
     

3. CSRF Token Issues:

   • If the form submission fails with a CSRF error, ensure the form includes the token:

     @csrf
     

   • For API routes, exclude the form route from CSRF verification in VerifyCsrfToken middleware.

4. Database Schema Mismatches:

   • After updating the package, run migrations to avoid SupportBubble model errors:

     php artisan migrate
     

5. TailwindCSS Conflicts:

   • If styles don’t apply, ensure Tailwind is configured to scan the published views:

     // tailwind.config.js
     content: [
         './resources/**/*.blade.php',
         './vendor/spatie/laravel-support-bubble/**/*.blade.php',
     ],
     

Debugging Tips

1. Log Submissions: Temporarily log all submissions to debug data:

   SupportBubbleSubmitted::listen(function ($event) {
       \Log::debug('Support Bubble Data', $event->supportBubbleData->toArray());
   });
   

2. Check Published Assets: Verify published views and config files exist in resources/views/vendor/support-bubble and config/support-bubble.php.

3. Disable JavaScript: Test the bubble with JS disabled to ensure fallback functionality works (e.g., direct form submission).

4. Inspect Network Requests: Use browser dev tools to verify form submissions reach the expected endpoint (/support-bubble).

Extension Points

1. Custom Validation: Extend validation rules in app/Providers/SupportBubbleServiceProvider:

   use Illuminate\Support\Facades\Validator;
   
   SupportBubbleSubmitted::listen(function ($event) {
       $validator = Validator::make($event->supportBubbleData->toArray(), [
           'message' => 'required|max:1000',
           'custom_field' => 'sometimes|string',
       ]);
       if ($validator->fails()) {
           // Handle validation errors
       }
   });
   

2. Webhook Notifications: Send submissions to a webhook (e.g., Slack, Zapier):

   SupportBubbleSubmitted::listen(function ($event) {
       Http::post('https://hooks.slack.com/services/...', [
           'text' => 'New support request: ' . $event->supportBubbleData->message,
       ]);
   });
   

3. Dynamic Form Fields: Use Laravel Collective’s Form facade or Alpine.js to conditionally render fields:

   @if($showCustomField)
       <div x-data="{ open: false }">
           <button @click="open = !open">Toggle Field</button>
           <input x-show="open" type="text" name="custom_field">
       </div>
   @endif
   

4. Rate Limiting: Prevent abuse by rate-limiting submissions:

   use Illuminate\Support\Facades\RateLimiter;
   
   SupportBubbleSubmitted::listen(function ($event) {
       $key = 'support_bubble|' . request()->ip();
       if (!RateLimiter::tooManyAttempts($key, 5)) {
           // Process submission
       } else {
           abort(429, 'Too many submissions');
       }
   });
   

5. Local Testing: Use Laravel’s fake() to test submissions without sending emails:

   Mail::fake();
   $event->supportBubbleData->send(); // Will not send in tests