Chat Laravel Package

Product Decisions This Supports

What it unlocks (and what it doesn't). musonza/chat gives you the messaging domain — conversations, participants, messages, read/unread state, events — not the chat product. PM framing: it buys back the data-modeling and CRUD phase (roughly days, not weeks to a first working thread → send → list flow), and leaves you the expensive, differentiating work: presence, typing indicators, attachments, moderation, notification fan-out, and the UI. Treat it as a "make vs. adopt the plumbing" decision, not a "build chat vs. buy chat" decision.

Feature decisions it informs:

• 1:1 DMs and group threads — in scope from day one. Private and group conversations plus polymorphic participants mean the same primitive can serve DMs, team channels, or per-entity threads (e.g., a conversation attached to an order, ticket, or project) without a separate identity system. That flexibility is a roadmap multiplier; scope the first release to one thread type and prove the pattern.
• Read state is table stakes, read receipts are not. Per-participant read/unread tracking is native. Anything resembling "seen by 3 of 5, at 4:12pm" is application work. Decide explicitly whether that's v1 or v2 — it's a common expectation mismatch.
• Metadata and message types give you a cheap extension path. Typed messages (system notices, events, structured payloads) mean some "custom feature" requests — status changes in-thread, inline notifications — can ship as message metadata rather than schema changes. This is a strong lever for deferring work without saying no.

Roadmap and sequencing decisions:

• Greenfield: adopt the schema as the target and build against package models behind a thin adapter; fastest path.
• Brownfield (existing message tables): this becomes a migration/backfill project, not a feature. Budget it as such, and do not dual-write to two message tables — ordering and unread-count divergence is expensive to unwind.
• Adapter layer as an explicit, funded decision. Wrapping package models in an application-level service is a small upfront cost that converts a future "exit or fork" from a rewrite into a one-layer change. PMs should insist on this even when it looks like over-engineering, because it buys optionality.

Build vs. buy:

• Build on this package when chat is a supporting capability inside a Laravel monolith, your requirements are conversational (threads, messages, unread), and your team is Eloquent-fluent. You own the schema, the data, and the cost profile — no per-MAU chat vendor bill, no external credential or SDK surface.
• Buy a hosted provider when chat is the product (or a headline feature) and realtime presence, delivery guarantees, moderation, and scale are on the near roadmap. At that point this package's gaps become a second product you're inadvertently building.
• Fork it only with eyes open: you inherit upstream merge work forever.

Use cases worth mapping before committing: internal team/ops messaging, in-app customer↔support threads, per-entity comment threads, community or cohort messaging, notification-center-with-conversations. Each has different needs on moderation, retention, attachments, and multi-tenancy — and those differences, not the message CRUD, drive the real cost.

Risks that are product decisions, not engineering ones:

• Schema ownership. The package owns tables and column semantics. If retention policy, audit logging, or per-tenant isolation diverge from its model, you're choosing between a fork and a sync layer. Decide the retention and tenancy story before production data lands — retrofitting either is a data migration with a compliance flavor.
• Multi-tenancy is not free. Per-tenant conversation isolation will likely be layered on via global scopes. That's a cross-cutting correctness concern that must be designed up front, not discovered.
• Conversation access control is the top incident risk. Membership checks live in your application code. That's a user-facing data-exposure surface and deserves explicit authorization test coverage and a review gate — a release-blocking requirement, not a nice-to-have.
• Single-maintainer concentration. Community-supported, no SLA, no commercial guarantee. For anything customer-facing, plan to own the source: at least one engineer who can read and patch it, and a documented patch set if you fork.

Upgrade cadence as a standing roadmap item. Laravel majors have historically required package majors. Put one compatibility cycle per Laravel major into planning rather than discovering it mid-upgrade. Pin the package alongside the framework and treat the pin as intentional. (The current v6.15.2 release is CI/test-hygiene only — no runtime, API, schema, or config change, and no migration required. Risk from that release specifically is effectively nil.)

Honest adoption questions for the team:

1. Which Laravel/PHP versions are officially supported, and what's the stated policy for a new Laravel major?
2. Is per-tenant isolation supported, or do we layer it via global scopes?
3. Do our retention, audit, and moderation requirements fit the package schema, or force a fork?
4. What's the realistic exit path if maintenance stalls — how coupled would our code be to its models and events?
5. Do we verify unread counts, attachments, and moderation against the tagged source rather than README claims? (These are commonly over-estimated.)

When to Consider This Package

Adopt when:

• You're on a Laravel monolith or modular monolith using Eloquent, with MySQL or PostgreSQL, standard queue workers, and a broadcast stack you already run (Pusher, Ably, or Reverb). The package composes with existing auth and notifications instead of replacing them.
• Chat is a supporting capability, not the headline product — threads, messages, and unread state are enough to satisfy the requirement.
• You already have user, team, or tenant models that polymorphic participants can attach to. No parallel identity system is required, which removes the single largest integration cost.
• You want a first working flow in days, with no external service, no credential provisioning, and no SDK versioning.
• You're comfortable owning the domain layer internally, including occasional patching.

Look elsewhere when:

• Chat is the product. Presence at scale, typing indicators, edit history, rich attachments, moderation workflows, and delivery guarantees all become custom work on top of package-owned tables — at which point a dedicated service or hosted provider is cheaper than the second product you're building.
• Your architecture is multi-service with chat as a separate bounded context. A domain package wired to your monolith's Eloquent models is the wrong boundary; a dedicated messaging service is the right call.
• You have hard multi-tenancy, retention, audit, or moderation requirements that the schema can't express. Divergence forces a fork or a parallel table plus sync layer — both are ongoing costs, and you should price them now rather than after launch.
• You need a vendor SLA or support contract, or you can't staff an engineer who can read and patch the source. There is no commercial guarantee here.
• You'd be migrating existing message tables and can't commit to a one-time backfill plus adapter. Brownfield adoption is a migration project; if it's being scoped as a feature, defer.

Decision heuristic: if the roadmap for the next 12 months stays inside "threads, messages, unread," this is a strong fit and a good buy-vs-build trade. If it points at "realtime, rich, moderated, multi-tenant, at scale," adopt it as a prototype or scoped internal tool — and plan the exit.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: This is an open-source (MIT) Laravel package that provides the messaging engine our app would otherwise spend weeks building: conversations, participants, messages, and read/unread state, backed by our existing database. There's no third-party service, no per-user vendor fee, and no new vendor contract — we own the data. It's the right call if chat is a supporting feature rather than the product. If chat becomes a flagship, realtime and moderation features would need to be built by us either way — and at that point we should revisit whether to buy a hosted platform. Recommended next step: a short spike to validate the two core flows, then a schema and tenant-isolation review before any production data lands. We should also decide now to wrap it behind a thin internal layer so we retain the option to replace it later.

For engineering — what we're buying and what we're on the hook for:

• Day-one value: Eloquent models and migrations for conversations, messages, and polymorphic participants, plus lifecycle events. First thread → send → list flow is days, not weeks. Integration is Composer + publish config/migrations + implement the participant contract on User/Team; broadcasting rides our existing driver.
• What stays ours: presence, typing indicators, attachments, moderation, notification fan-out, unread-count performance at scale, and every access-control check. Membership authorization in application code is our most likely data-exposure incident — explicit tests and a review gate are required, not optional.
• Non-negotiables before production data:
  1. Adapter layer isolating package models behind an application repository/service — this is our exit ramp and we should build it on day one, not later.
  2. Schema and tenancy review — column semantics, indexes, global-scope strategy, retention. Composite index on (conversation_id, created_at); plan archival/partitioning as message volume approaches tens of millions.
  3. Integrity and failure handling — clean up participant rows on model deletion (polymorphic drift creates orphaned threads), alert on queue depth, and add a polling fallback so stalled workers don't produce silent non-delivery.
• Ongoing cost: low in steady state — no service to operate, and patches require only a Composer update plus regression run. The recurring item is upgrade alignment: budget one package-compatibility cycle per Laravel major and pin the package alongside the framework. Track the repo's release cadence as a health signal.
• Support reality: community-only, best-effort issues, single maintainer. Assume internal ownership of the source; if chat becomes business-critical, a vendored fork with a documented patch set is reasonable insurance — but record every local patch, because upstream upgrades become manual merges once you diverge.
• Current release: v6.15.2 is CI/test-hygiene only (checkout action bump, dropping legacy-factories from the vendor's own test suite). No runtime, API, schema, or config changes — safe from any 6.15.x pin, no migration needed.

Ask: approve a timeboxed spike (validate a 1:1 DM and a group thread against real use cases) plus a schema/tenancy review gate, and confirm ownership of the adapter layer and authorization tests as part of the initial estimate rather than follow-on work.