Filum Laravel Package

Product Decisions This Supports

• Build vs. buy for internal comms inside the admin panel. Filum replaces a scoped, custom build (models, migrations, broadcast wiring, presence, unread state, notification bell integration) with a Composer require plus two artisan commands. For a team whose core product is not chat, this is a clear "buy" — the package is MIT and pulls no paid vendor into require, so the decision is engineering hours, not procurement budget.
• Whether to make the admin panel the system of record for staff conversation. Filum keeps history persistently inside your own database and serves attachments through a membership-checked panel route rather than public URLs. That supports a decision to consolidate operational chatter (approvals, escalations, "who's covering this ticket") into the tool staff already have open, instead of a separate Slack workspace that fragments context.
• Broadcaster investment timing. The package is transport-agnostic and auto-detects: 5s polling with no broadcaster, push plus a 30s reconciliation poll with one. This lets you ship chat now and defer the Reverb/soketi decision until volume justifies it — a roadmap sequencing decision rather than a launch blocker. It also means you can pilot chat with zero infrastructure change.
• Scope control on the feature surface. Groups, replies, attachments, reactions, presence and bell notifications are each individually switchable via env/config, and "disabled means absent" (not half-working UI). That supports a phased rollout: 1:1 only in phase one, groups later, attachments last if data-handling review demands it.
• Notification-strategy decision. Filum deliberately rings the bell once per conversation, only on the caught-up→behind transition, and only for recipients not currently present, using a single shared ttl for both the presence board and the bell. This is a defensible product stance (bell and board can never contradict each other) that you should accept or reject explicitly — the honest trade-off is that someone who closed their laptop 30 seconds ago is still "present" at the 180s default and gets no bell. If that lag matters, you lower ttl and get a twitchier presence indicator too; there is no independent knob.
• Access-governance decision. One gate (Filum::auth(...)) governs the page, the overlay, and the broadcast channels, so authorization cannot drift between the read path and the subscription path. That's a security-review-friendly shape and reduces the review burden of adding an in-panel messaging surface.
• Use cases it credibly unlocks: back-office triage between ops/support/admin staff; approval and escalation side-channels attached to a workflow; small-team coordination where the panel is the workday; support desks needing an audit-friendly, self-hosted alternative to a hosted chat vendor.

When to Consider This Package

Consider it when most of the following hold:

• You already run Filament 4.11.5+/5.6.5+ on Laravel 12/13 and PHP 8.3+. The version floor is a hard security minimum (earlier 4.x/5.x carry published advisories), so this package is only viable on a current stack — if you are mid-upgrade, this is a post-upgrade item, not a parallel one.
• The need is internal staff chat, not customer-facing messaging. The design (colleague sidebar, presence board, admin panel overlay) is aimed squarely at authenticated back-office users.
• You want self-hosted and vendor-free, with no hosted WebSocket dependency and no per-seat chat SaaS cost.
• Your user model is non-default. Filum is schema-agnostic (users.model, name_column, avatar_column, integer/UUID/ULID keys), which is a real strength for admin-guard panels — but note FILUM_USER_MODEL must be set before migrating and must be set in every environment, and getting it wrong errors on every panel page, not just chat.
• You can accept 7 GitHub stars and 0 dependents as an acceptable risk profile. That is the decisive criterion. This is effectively a single-maintainer package with no downstream canary population; you are the canary.

Look elsewhere (or build) when:

• Chat is customer-facing or revenue-critical. Zero dependents plus a lone maintainer is not a defensible dependency for a surface your customers touch.
• You need moderation tooling, retention policy, eDiscovery, DLP, or compliance export. Filum gives you conversation membership and a private-disk attachment route; it does not give you a compliance story. Attachments in particular need a retention and malware-scanning answer that this package does not provide.
• You need federation, external guests, threads with non-panel users, or mobile push. The model is panel-authenticated staff only.
• You need i18n beyond English and Georgian, or a locale set the maintainer does not ship — you would be maintaining translation files yourself.
• You cannot commit to the migration discipline: upgrade migrations are published per-tag, and publishing the wrong tag on an existing install creates a duplicate create_filum_tables migration that aborts migrate and leaves new code querying columns that don't exist — a hard outage, including 1:1 chat, not a degradation. Code and schema must ship in the same release step.
• Your team will configure a broadcaster by hand but not build an Echo client. That combination silently leaves you on the 30s reconciliation poll — slower than the 5s no-broadcaster default. Either run reverb:install (which wires both halves) or explicitly pin transport.driver to polling.
• Bus factor is a blocker for your org. If a single unmaintained dependency violates your policy, stop here — but then note that the alternative is a custom build with the same bus factor, just internal.

Suggested posture if you proceed: treat it as an internal-tool dependency, pin the version, vendor-fork if your policy requires, and run a timeboxed pilot (1:1 chat only, polling transport, no attachments) before enabling groups, files, or reactions.

How to Pitch It (Stakeholders)

To executives: This adds colleague-to-colleague chat directly inside the admin panel staff already use, so operational conversation stays attached to the work instead of scattering into a separate tool. It is MIT-licensed and free, requires no hosted chat vendor or per-seat subscription, and runs on infrastructure we already own. It can launch with no new infrastructure at all — it polls by default and upgrades to real-time only if and when we choose to stand up Reverb. It is fully self-hosted, so message history and shared files stay in our database under our access rules. Scope is controlled: files, groups and reactions are each switchable, so we can start with direct messages only. The principal risk is maturity — the package is new and has a single maintainer — which is why the recommendation is a scoped pilot on the internal admin panel, not a customer-facing surface.

To engineering: Straightforward integration: composer require, filum:install, migrate, then register FilumPlugin::make() in the panel provider. Three things need care before you start. First, set FILUM_USER_MODEL in every environment before migrating and before installing — a wrong value surfaces as an error on every panel page because the current user is resolved while navigation builds. Second, ship the migration in the same release step as the code; new code against an old schema is a hard outage (direct conversations write kind, state, joined_at, and every membership check reads state). Third, on upgrades publish only the release-specific migration tag — never filum-migrations on an existing install, or you get a duplicate create_filum_tables that aborts migrate. Authorization is a single gate (Filum::auth) covering page, overlay and channels, so there is one place to review. Attachments must stay on a private disk (local, not public) — files are served through a membership-checked route that 404s rather than 403s by design. If you configure a broadcaster manually, you must also ship an Echo client in the panel assets, or you will silently land on the 30s reconciliation poll, which is slower than the 5s polling default.

The one-line ask: approve a timeboxed internal pilot — 1:1 chat, polling transport, attachments off — with a written exit plan, and revisit groups and file sharing after the pilot plus a maintenance-health check on the upstream repo.