Support Answer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require baks-dev/support-answer
   

   Publish the package config and migrations:

   php artisan vendor:publish --provider="BaksDev\SupportAnswer\SupportAnswerServiceProvider" --tag="config"
   php artisan vendor:publish --provider="BaksDev\SupportAnswer\SupportAnswerServiceProvider" --tag="migrations"
   php artisan migrate
   

2. First Use Case:

   • Define a quick answer: Create a template in config/support-answer.php under the templates key:

     'templates' => [
         'password_reset' => [
             'subject' => 'Password Reset Instructions',
             'body' => 'Hello {name}, here is your reset link: {link}',
         ],
     ],
     

   • Trigger via CLI/Controller:

     use BaksDev\SupportAnswer\Facades\SupportAnswer;
     
     $response = SupportAnswer::send('password_reset', [
         'name' => 'John Doe',
         'link' => url('reset-password?token=abc123'),
     ]);
     

3. Where to Look First:

   • Config File: config/support-answer.php (templates, default settings).
   • Facade: SupportAnswer (main entry point for sending answers).
   • Migrations: database/migrations/*support_answer* (check table structure for custom fields).
   • Tests: tests/Feature/SupportAnswerTest.php (real-world usage examples).

Implementation Patterns

Core Workflows

1. Template-Based Responses:

   • Use predefined templates (from config) for common support scenarios (password resets, order confirmations, etc.).
   • Dynamic Data Binding:

     SupportAnswer::send('invoice_confirmation', [
         'order_id' => $order->id,
         'amount' => $order->total,
     ]);
     

   • Fallback Logic: Define a default template in config for uncaught cases.

2. Integration with Laravel Mail:

   • The package extends Laravel’s Mailable system. Override the default mail driver in config:

     'mail_driver' => 'smtp', // or 'log', 'array', etc.
     

   • Custom Mailables: Extend the package’s SupportAnswerMailable class for complex logic:

     namespace App\Mail;
     
     use BaksDev\SupportAnswer\Mail\SupportAnswerMailable;
     
     class CustomSupportAnswer extends SupportAnswerMailable {
         public function build() {
             return $this->subject('Custom Subject');
         }
     }
     

     Register in config/support-answer.php:

     'custom_mailables' => [
         'custom_template' => \App\Mail\CustomSupportAnswer::class,
     ],
     

3. Queueing and Events:

   • Dispatch answers to queues for async processing:

     SupportAnswer::sendQueued('password_reset', $data);
     

   • Listen for events (SupportAnswerSent) to log or notify:

     use BaksDev\SupportAnswer\Events\SupportAnswerSent;
     
     event(new SupportAnswerSent($template, $data));
     

4. API Responses:

   • Return structured responses for APIs:

     $response = SupportAnswer::sendJson('api_error', [
         'error' => 'Invalid request',
     ]);
     // Returns: { "status": "sent", "template": "api_error", "data": {...} }
     

Advanced Patterns

• Dynamic Template Loading: Load templates from a database or external API by implementing BaksDev\SupportAnswer\Contracts\TemplateLoader:

  class DatabaseTemplateLoader implements TemplateLoader {
      public function get(string $name): array {
          return DB::table('support_templates')->where('name', $name)->first();
      }
  }
  

  Bind in AppServiceProvider:

  $this->app->bind(
      TemplateLoader::class,
      DatabaseTemplateLoader::class
  );
  

• Localization: Support multiple languages by extending the SupportAnswer facade:

  SupportAnswer::setLocale('ru');
  SupportAnswer::send('welcome', $data);
  

Gotchas and Tips

Pitfalls

1. Template Syntax Conflicts:

   • Avoid { and } in template bodies unless escaped (e.g., {{ and }} for literal braces).
   • Fix: Use {{variable}} for literal output or escape with \{/\}.

2. Queue Stuck Jobs:

   • If using queues, ensure the support_answer:work queue worker is running:

     php artisan queue:work --queue=support_answer
     

   • Debug: Check failed_jobs table for errors; log SupportAnswerFailed events.

3. Missing Config:

   • Forgetting to publish migrations/config will break template storage or mail settings.
   • Fix: Run php artisan vendor:publish again and php artisan migrate.

4. Caching Issues:

   • Templates are cached by default. Clear cache after changes:

     php artisan cache:clear
     php artisan config:clear
     

5. Character Encoding:

   • Non-ASCII characters (e.g., Cyrillic) may break in emails. Ensure your mail driver supports UTF-8 (e.g., smtp with charset=utf-8).

Debugging Tips

• Log Templates: Enable debug mode in config:

  'debug' => true,
  

  Logs will appear in storage/logs/laravel.log.

• Test with log Driver: Temporarily set mail_driver to log to verify templates:

  'mail_driver' => 'log',
  

  Check storage/logs/laravel.log for rendered emails.

• Validate Data: Use the validate method to ensure data matches template placeholders:

  SupportAnswer::send('template', $data)->validate();
  // Throws \InvalidArgumentException if placeholders are missing.
  

Extension Points

1. Custom Storage: Override template storage by binding BaksDev\SupportAnswer\Contracts\TemplateRepository:

   $this->app->bind(TemplateRepository::class, CustomTemplateRepository::class);
   

2. Pre/Post-Send Hooks: Use events to modify behavior:

   // Before sending
   SupportAnswer::beforeSend(function ($template, $data) {
       $data['timestamp'] = now()->toDateTimeString();
   });
   
   // After sending
   SupportAnswer::afterSend(function ($response) {
       Analytics::log('support_answer_sent', $response->template);
   });
   

3. API Rate Limiting: Protect the sendJson endpoint with Laravel’s throttle middleware:

   Route::middleware(['throttle:10,1'])->post('/api/support', [SupportAnswerController::class, 'send']);
   

4. Multi-Channel Support: Extend to SMS or push notifications by implementing BaksDev\SupportAnswer\Contracts\Channel:

   class SmsChannel implements Channel {
       public function send(string $template, array $data): bool {
           // Logic to send SMS via Twilio/other
       }
   }
   

   Register in config:

   'channels' => [
       'sms' => \App\Channels\SmsChannel::class,
   ],
   

   Use:

   SupportAnswer::send('sms_template', $data, 'sms');
   

5. Template Versioning: Add a version field to templates in the database to handle updates without breaking existing data:

   'templates' => [
       'password_reset_v2' => [
           'version' => 2,
           'subject' => 'Updated Reset Instructions',
           // ...
       ],
   ],
   

   Implement logic in TemplateLoader to fetch the latest version.