Filament Intercom Laravel Package

Getting Started

This release is a compatibility milestone: v2.0.0 targets Filament 4. If you are still on Filament 3, stay on the package's 1.x line — do not upgrade this package independently of Filament.

1. Confirm your Filament major version first. Run composer show filament/filament and check for v4.x. This determines which package major you install.
2. Install the matching pair:

   composer require <vendor>/<package>:^2.0   # Filament 4
   composer require <vendor>/<package>:^1.0   # Filament 3
   

3. Register the plugin on your panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(YourPackagePlugin::make());
   }
   

4. Publish config/assets only if you need to override defaults. In Filament 4 the asset pipeline changed, so re-run php artisan filament:assets (or the package's own install command) rather than copying published assets from a v1 install.
5. First use case: open the panel and exercise the package's primary surface — usually a resource table, a form/schema component, or a widget. That single screen will surface 90% of upgrade breakage.

Look first at the package's README "Requirements" table and its CHANGELOG for the v1 → v2 diff, then at the plugin class itself (src/*Plugin.php) to see what it registers — that tells you what it touches in your panel.

Implementation Patterns

Pin the version matrix in CI. The most important pattern for a package whose releases are tied to a host framework major is a test matrix that pairs package v2 with Filament 4 and package v1 with Filament 3. Do the same in your app's composer.json constraints so a composer update cannot silently cross the boundary:

"require": {
    "filament/filament": "^4.0",
    "<vendor>/<package>": "^2.0"
}

Register the plugin per panel, not globally. Filament plugins are panel-scoped. If you run an AdminPanelProvider and a separate AppPanelProvider, decide deliberately which one gets the plugin — most plugins only make sense in one.

Compose with Filament 4 schemas. In Filament 4 the form/schema layer lives under Filament\Schemas. Typical day-to-day usage looks like:

use Filament\Schemas\Schema;

public static function configure(Schema $schema): Schema
{
    return $schema->components([
        YourPackageField::make('settings')
            ->required(),
    ]);
}

Reach for the package's field/column classes as schema components rather than wrapping them in custom Blade where possible — you inherit validation, reactivity, and dark-mode styling for free.

Table and action integration. If the package ships table columns or actions, attach them in table() / configure() and keep the package's fluent configuration chain last, after your own modifiers, so package-level defaults do not clobber your intent.

Configuration over forking. Publish the config file (php artisan vendor:publish --tag=<package>-config) and keep every override there. When v3 eventually lands, your diff is a config file, not a patched vendor tree.

Feature-flag the rollout. For a major-version bump, ship behind a branch deploy to staging, run your panel's smoke tests, and only then merge. Filament 4's schema refactor is broad enough that "it installs" is not evidence it works.

Gotchas and Tips

• The version pairing is the whole release. "Filament 4 support" almost certainly means v2.0.0 is not backwards compatible with Filament 3. Expect class-name and namespace changes in anything you've extended or overridden — the Filament 4 move from Filament\Forms to Filament\Schemas, Form → Schema, and ->form() → ->schema() is the usual culprit. Grep your app/ for the old namespaces before assuming your overrides still load.
• Semver trap: a package that jumps majors to track a host framework major will also bump majors for its own breaking changes. Read the changelog for package-level changes, not just the Filament compatibility line — the release note here is one sentence and may not enumerate them.
• Stale published assets and cached views. After upgrading, clear aggressively: php artisan filament:assets, php artisan view:clear, php artisan config:clear, and rebuild any custom theme CSS (npm run build). Half of "the upgrade broke my panel" reports are stale compiled assets.
• Custom theme CSS needs a rebuild against Filament 4's classes. If you published a theme in v1, do not assume the Tailwind config and layer names still match.
• Extending package classes is the fragile path. Subclassing a package resource/page/field couples you to internals that v2 likely reshaped. Prefer plugin configuration, macros, and view overrides; if you must extend, add a test that instantiates your subclass so a future bump fails loudly rather than at runtime.
• Debugging tip: when a component renders blank or throws a container-resolution error, dump the resolved schema with ->getComponents() (or dd($schema) inside configure()) to see whether the package component actually registered on the panel — a plugin added to the wrong provider is a common silent failure.
• Extension points to check before writing custom code: the plugin class's register()/boot() methods, published config keys, view namespace (<package>::), and any registered macros. A config flag is cheaper than a fork.
• Watch the package's test suite and issue tracker for Filament 4 patch releases. Filament 4 is young; expect several patch releases where the plugin needs to follow. Pin to a caret constraint and update deliberately rather than floating on dev-main.