Addchat Laravel Laravel Package

Getting Started

Minimal Setup Steps

1. Installation

   composer require classiebit/addchat-laravel
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="Classiebit\Addchat\AddchatServiceProvider"
   

2. Database Migration Run the migrations to create the required tables:

   php artisan migrate
   

3. Configuration Update .env with your database settings (already configured in config/addchat.php). Ensure users table has id and email columns (or adjust config to match your user model).

4. First Integration Add the chat widget to your Blade template:

   @addchat
   

   Or manually include the JS/CSS:

   <script src="{{ asset('vendor/addchat/js/addchat.js') }}"></script>
   <link href="{{ asset('vendor/addchat/css/addchat.css') }}" rel="stylesheet">
   

5. Initial User Setup Assign a role to your first user (e.g., admin or customer) via the users table or a seed:

   $user->addchat_role = 'admin'; // or 'customer'
   $user->save();
   

First Use Case: Basic Chat

• Log in as two users (e.g., via Laravel’s built-in auth).
• Open the chat widget (@addchat) on both users’ browsers.
• Send a message from one user to another—real-time updates appear instantly.

Implementation Patterns

Core Workflows

1. User Authentication & Role Assignment

• Pattern: Use Laravel’s built-in auth system. Extend the users table with addchat_role (e.g., admin, customer, support).
• Example:

  // In a User model observer or registration controller
  event(new Registered($user));
  $user->addchat_role = 'customer';
  $user->save();
  

• Integration Tip: Sync roles with your existing permission system (e.g., Spatie Laravel-Permission) for granular control.

2. Real-Time Messaging

• Pattern: Uses Laravel Echo + Laravel Notifications under the hood (no Pusher dependency).
• Workflow:
  1. Messages are stored in the addchat_messages table.
  2. Notifications trigger via Laravel’s database channel (polling-based).
  3. Frontend JS listens for AddchatMessageSent events.
• Customization:

  // Override default event handling in your app.js
  window.Addchat = window.Addchat || {};
  window.Addchat.onMessage = function(message) {
      console.log('Custom logic:', message);
      // Extend with your own UI updates
  };
  

3. Group/Department Chats

• Pattern: Use the addchat_groups table to create departments (e.g., "Support", "Sales").
• Implementation:

  // Create a group via a controller
  $group = \Classiebit\Addchat\Models\Group::create([
      'name' => 'Customer Support',
      'description' => 'Dedicated support team',
  ]);
  // Assign users to the group
  $group->users()->attach([1, 2, 3]); // User IDs
  

• Frontend: Users see group chats in the widget if assigned via addchat_group_user pivot table.

4. Customer Support Features

• Pattern: Leverage addchat_role to restrict access:
  • support role can see all users.
  • customer role only sees other customers or support agents.
• Example:

  // In a middleware or policy
  public function authorizeSupport($user) {
      return $user->addchat_role === 'support';
  }
  

5. Customizing UI/Theming

• Pattern: Override default assets via public_path() or Laravel Mix.
• Steps:
  1. Copy vendor assets to public/vendor/addchat/:

     cp -r vendor/classiebit/addchat/resources/views public/vendor/addchat/
     

  2. Extend the Blade template (resources/views/vendor/addchat/widget.blade.php).
  3. Publish and compile custom CSS/JS:

     // resources/js/addchat.js
     window.Addchat = {
          theme: {
              primary: '#3498db',
              secondary: '#2ecc71'
          }
      };
     

6. API Integration (Optional)

• Pattern: Use the package’s controllers or build a custom API.
• Example Endpoint:

  // routes/api.php
  Route::middleware('auth:api')->get('/addchat/messages', [\Classiebit\Addchat\Http\Controllers\MessageController::class, 'index']);
  

• Frontend Fetch:

  fetch('/api/addchat/messages')
      .then(response => response.json())
      .then(messages => console.log(messages));
  

Gotchas and Tips

Pitfalls

1. Database Polling Lag

   • Issue: Real-time updates rely on Laravel Notifications polling (not WebSockets). High traffic may cause delays.
   • Fix: Increase config/addchat.php polling_interval (default: 3000ms) or implement a queue worker for notifications:

     // app/Providers/AppServiceProvider.php
     public function boot() {
         \Classiebit\Addchat\Events\AddchatMessageSent::class,
             \Classiebit\Addchat\Events\AddchatTyping::class,
         ];
     }
     

2. User Model Mismatch

   • Issue: Package assumes users table has id and email. Custom user models may break auth.
   • Fix: Override config:

     'user_model' => App\Models\CustomUser::class,
     'user_id_field' => 'uuid', // If using UUIDs
     

3. CSRF Token Conflicts

   • Issue: Widget JS may fail if CSRF token is missing or mismatched.
   • Fix: Ensure @csrf is in your Blade layout or pass the token manually:

     window.Addchat.csrfToken = '{{ csrf_token() }}';
     

4. Group Permissions Overlap

   • Issue: Users may appear in multiple groups, causing duplicate messages.
   • Fix: Use addchat_group_user pivot table to enforce one-to-many relationships explicitly.

5. Asset Loading Order

   • Issue: CSS/JS may not load if included after jQuery or Bootstrap.
   • Fix: Place @addchat at the end of your <body> or ensure dependencies are loaded first.

Debugging Tips

1. Check Events Listen for broadcast events in Tinker:

   php artisan tinker
   >>> \Classiebit\Addchat\Events\AddchatMessageSent::dispatch(new \Classiebit\Addchat\Events\AddchatMessageSent($message));
   

   Verify the event fires and notifications are queued.

2. Log Database Queries Enable Laravel debugging:

   DB_DEBUG=true
   

   Check for missing or malformed queries in storage/logs/laravel.log.

3. Widget Visibility Hide the widget conditionally:

   @auth
       @addchat
   @endauth
   

   Or via JS:

   document.addEventListener('DOMContentLoaded', function() {
       if (!window.user) {
           document.querySelector('.addchat-widget').style.display = 'none';
       }
   });
   

Extension Points

1. Custom Message Types Extend the addchat_messages table and override the Message model:

   namespace App\Models;
   use Classiebit\Addchat\Models\Message as BaseMessage;
   
   class Message extends BaseMessage {
       protected $casts = [
           'is_read' => 'boolean',
           'custom_field' => 'string', // Add your own fields
       ];
   }
   

   Update config/addchat.php:

   'message_model' => App\Models\Message::class,
   

2. Webhook Integration Trigger external actions on message events:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Classiebit\Addchat\Events\AddchatMessageSent::class => [
           \App\Listeners\SendSlackNotification::class,
       ],
   ];
   

3. Rate Limiting Prevent spam via middleware:

   // app/Http/Middleware/AddchatRateLimit.php
   public function handle($request, Closure $next) {
       $key = $request->ip().'|'.$request->user()->id;
       if (cache()->has($key)) {
           abort(429, 'Too many messages!');
       }
       cache()->put($key, true, now()->addMinutes(1