README

A lightweight, production-ready Laravel package that provides support conversations and messaging features (conversations, messages, agents, guests, assignments, reads and broadcasting support channels).

Table of Contents

• Highlights
• Requirements
• Installation
• Configuration
• Usage
  • Routes / API
  • Broadcast Channels
  • Events
• Testing & Development
• Contributing
• License

Highlights ✅

• Conversation lifecycle: create, reply, assign, close
• Message read tracking and assignment history
• Guest support with configurable guards and rate-limits
• Built-in Broadcast channels and events for real-time UIs
• Policy-based authorization for agents and supervisors
• Auto-registers as a Laravel provider (PSR-4: Anwar\\Support\\)

Requirements 🔧

• PHP >= 8.1
• Laravel 10.x (or compatible 10.x series)
• Illuminate components: database, broadcasting, queue, support

Installation 📦

For a published package on Packagist:

composer require anwar/laravel-support

For local development in a monorepo, add to your root composer.json:

"repositories": [
  {
    "type": "path",
    "url": "packages/support"
  }
]

Then require the package (example for local dev):

composer require anwar/laravel-support:dev-main --prefer-source

The package supports Laravel's package auto-discovery. To register manually, add this to config/app.php providers:

Anwar\Support\SupportServiceProvider::class,

Publish config

php artisan vendor:publish --provider="Anwar\Support\SupportServiceProvider" --tag=support-config

Migrate database

The package loads its own migrations automatically. Run:

php artisan migrate

Configuration ⚙️

Configuration file: config/support.php

Key configuration options include:

• table_prefix — prefix for package tables (default support_)
• user_model — your User model class
• guards — customer and agent guard settings
• middleware — middleware groups for customer/agent APIs
• roles — agent and supervisor role names
• permissions — permission names view_inbox and view_all
• guest.enabled — allow guest conversations
• rate_limits — customer/guest per-minute messaging throttles

Adjust these with your application environment variables (see SUPPORT_*).

Usage 🧭

Routes / API

Routes are registered under the /support prefix (see src/Routes/api.php).

Customer-facing routes (middleware support.middleware.customer):

• POST /support/conversations — Create a conversation
• GET /support/conversations/{conversation} — Show conversation
• POST /support/conversations/{conversation}/messages — Add a message (throttled)
• POST /support/conversations/{conversation}/read — Mark as read
• POST /support/conversations/{conversation}/typing — Typing indicator

Agent routes (middleware support.middleware.agent):

• GET /support/agent/inbox — Agent inbox
• GET /support/agent/conversations/{conversation} — Show conversation
• POST /support/agent/conversations/{conversation}/assign — Assign conversation
• POST /support/agent/conversations/{conversation}/close — Close conversation
• POST /support/agent/conversations/{conversation}/note — Add internal note

Broadcast channels

Defined in src/Routes/channels.php:

• support.conversation.{conversationId} — conversation updates
• support.user.{userId} — direct user notifications
• support.agents — agent/supervisor notifications

Authorization is delegated to Anwar\Support\Services\SupportAccess.

Events

The package emits events for your real-time frontend:

• SupportConversationCreated — new conversation
• SupportMessageCreated — new message
• SupportMessageRead — message read update
• SupportConversationAssigned — conversation assignment
• SupportConversationUpdated — conversation metadata/status update
• SupportTyping — typing on/off

Each event is broadcasted to relevant channels—subscribe on the client to update conversation lists and messages in real-time.

Models

• Anwar\Support\Models\Conversation
• Anwar\Support\Models\Message
• Anwar\Support\Models\Participant
• Anwar\Support\Models\Read
• Anwar\Support\Models\Assignment
• Anwar\Support\Models\Guest

Use the models directly or rely on the provided API controllers.

Testing & Development 🧪

• Run your application test suite from the project root (phpunit)
• For local development, you may want to configure the package as a path repository (see installation) and run composer dump-autoload after changes

Good checks:

composer dump-autoload
php artisan migrate --seed
php artisan test

Contributing 🤝

Contributions are welcome.

• Fork the repo
• Create a feature branch
• Add tests for new behavior
• Send a pull request with a clear description

Please follow PSR-12 coding style and add unit/integration tests for new features.

License

MIT — see the LICENSE file.

Maintainers & Support

• Maintainer: ringkubd (repository owner)
• For issues and feature requests, please open an issue on the repository.

Base color for package branding: #CE4631

If you'd like, I can also add examples for a JavaScript/Livewire front-end to consume the package's broadcasted events and realtime channels. 🔧