Laravel Modules Interactions Laravel Package

Getting Started

This is a platform-requirements major: v2.0.0 changes what the package runs on, not what it does. There is no application-facing API change, so treat the upgrade as an environment bump rather than a refactor.

Minimum steps:

1. Confirm the host app is on PHP 8.4 and Laravel 13 (illuminate/* ^13.0). If you are still on Laravel 12 / PHP 8.3, stay on the 1.x line — v2 will not install and there is no compatibility shim.
2. Bump the constraint to ^2.0 and let Composer resolve ozankurt/laravel-modules-core ^2.0. That transitive constraint is the usual source of "why won't it install" — check it resolves before debugging anything else.
3. Publish config and migrations if you have not already, then php artisan migrate.
4. Verify Filament resolves to a major you actually run (3, 4 or 5 — all three are CI-verified against Laravel 13).

First use case: counter deltas. The canonical day-one flow is bumping a counter on a module record (views, downloads, likes) and surfacing it in a Filament resource. Do that first — it exercises the config, the module model and the Filament integration in one pass.

Where to look first, in order: the published config file, the counter API exposed on your module model, then the Filament plugin registration in your PanelServiceProvider.

Implementation Patterns

Always use atomic deltas, never read-modify-write. v2.0.0 internally switched from an interpolated DB::raw('count + (n)') to the query builder's increment()/decrement(). That is the pattern you should mirror in your own code: $model->increment('views') / $model->decrement('stock'), not $model->views = $model->views + 1; $model->save();. The package is telling you it treats counter mutation as a database concern; keep your application code aligned or you will reintroduce lost updates under concurrency.

Treat deltas as non-idempotent and guard at the boundary. Increments are not naturally replay-safe. If a counter bump is triggered from a queued listener or a webhook, back it with an already-processed marker (unique job, processed_events row, or ShouldBeUnique) so a retry does not double-count.

Filament integration is per-panel and per-major. Register the plugin inside the panel you want it on, and pin your Filament major in composer.json rather than floating. The package supports 3, 4 and 5 simultaneously, which means the API surface it targets is the intersection — anything you rely on beyond that intersection is yours to own.

Mirror the CI matrix locally for tests. The package moved to Pest 5 / Testbench 11. If you copied any of its test scaffolding or base TestCase, port it at the same time as the upgrade; Pest 5 syntax drift will otherwise show up as mysterious failures in a suite you thought was unrelated.

Batch hot counters at the application layer. The atomic form is correct but still one round-trip per delta. For counters on a genuinely hot row, accumulate in a request/queue payload and flush a single delta — the package's API takes a delta value, so this composes cleanly.

Keep module concerns in the core package. ozankurt/laravel-modules-core is the domain layer; this package is the Laravel/Filament glue. Resist putting business rules in the glue — it is the part most exposed to framework-major churn.

Gotchas and Tips

• Hard cut on Laravel 12 and PHP 8.3. No deprecation period, no dual-support. Budget the framework upgrade as a prerequisite, not a follow-up. If the app is pinned to Laravel 12 for other dependency reasons, this package is not the blocker to solve first — it is the last.
• Connection::raw() narrowing is the real breaking change for extenders. Laravel 13 restricts the signature to float|int|literal-string. If you subclassed or extended the package's counter logic with your own interpolated DB::raw('count + '.$n), it will now fail — at runtime or under static analysis, and literal-string means a plain string variable will not satisfy it. Switch to increment()/decrement() or move the value into a binding.
• Do not write a data migration. The release notes explicitly state behaviour and generated SQL are unchanged. If you were asserting on generated SQL in tests, those assertions still hold — a differing result means you changed something else.
• Unsigned columns and negative deltas. decrement() on an UNSIGNED column will error rather than go negative. If you decrement anywhere (stock, credits, seats), verify the column type and add a guard or a CHECK-style constraint at the application layer.
• Filament plugin compatibility is not transitive. Filament 5 is verified for this package against Laravel 13 — any third-party Filament plugin you also use is not covered. Upgrade Filament and this package in the same pass, then smoke-test each panel.
• Debugging counter behaviour: attach a DB::listen() in a local service provider and confirm you see update ... set count = count + ? (a single atomic statement) rather than a select followed by an update. The latter means something in your code path bypassed the delta API.
• Extension points to reach for before forking: the published config file first, then the Filament resource/plugin registration, then the module model trait from the core package. Forking the glue package to change counter behaviour is a smell — that logic lives one layer down.
• Pin the transitive version. ozankurt/laravel-modules-core ^2.0 and spatie/laravel-package-tools ^1.93 are both requirements of this release. If a sibling package in your app requires laravel-modules-core ^1.x, Composer will resolve to the old pair and silently keep you on this package's 1.x.