Laravel Modules Forum Laravel Package

Getting Started

• Baseline first: this release requires PHP 8.4+ and Laravel 13.x. If your app is still on Laravel 12 or PHP 8.3, plan the framework/runtime upgrade before adopting v2. Filament 3, 4, and 5 remain supported.
• Install and wire up: require the package with Composer; it pulls ozankurt/laravel-modules-core and ozankurt/laravel-modules-interactions. Publish the package config and migrations, then run php artisan migrate.
• Where to look first: the published config, the board/thread/post migrations, ThreadObserver, Thread::scopeSearch(), and the Filament resources. These are the main day-to-day surfaces.
• First use case: create a Board, create a Thread under it, add a reply, then verify board.post_count reflects the post. Soft-delete and restore the thread and confirm the counter returns to the correct value. This exercises the observer, soft-delete path, and counter contract in one pass.

Implementation Patterns

• Let observers own counters. Create, update, soft-delete, and restore threads/posts through the package models and relationships rather than raw inserts. ThreadObserver now uses increment(), decrement(), and incrementEach() to keep board.post_count correct; don’t manually set or recalculate the counter in normal flows.
• Use model APIs for lifecycle changes. Thread::create(), $thread->delete(), $thread->restore(), and post creation via relationships are the expected paths. The observer handles counter semantics consistently across soft delete and restore.
• Search via the scope. Use Thread::search($term) (the scopeSearch entry point). The scope is deliberately join-free, which is why the ranking CASE no longer qualifies with getTable(). Keep custom search extensions join-free unless you re-qualify columns.
• Respect the caching split. Board and thread read caching is enabled; ACL/policy reads are deliberately uncached. If you perform bulk writes or direct DB updates, clear/invalidate the relevant read caches rather than assuming the package will notice.
• Filament integration: register the package’s Filament resources in your panel. The package supports Filament 3, 4, and 5, so use the shipped resources and adapt panel registration to your Filament version rather than copying resource code.
• Modules integration: follow the laravel-modules-core conventions for service provider/module registration, and use laravel-modules-interactions for cross-module hooks. Keep package-specific behavior in observers, scopes, and resources rather than scattering it through app code.

Gotchas and Tips

• Breaking upgrade: v2 drops Laravel 12 and PHP 8.3. Composer will block installation on those versions; upgrade the app runtime/framework first.
• Laravel 13 raw SQL narrowing: DB::raw() and orderByRaw() now expect literal strings. Do not splice runtime values into raw SQL. Use query-builder methods, bindings (selectRaw('... ?', [$value])), or the observer’s increment()/decrement()/incrementEach() helpers. If you override or extend ThreadObserver, preserve the atomic counter operations.
• Custom search joins: Thread::scopeSearch() intentionally drops the table qualifier because it never joins. If you add joins in a custom search scope, re-qualify columns to avoid ambiguous SQL.
• Counter drift: bulk inserts/updates that bypass observers will desynchronize board.post_count. Use the package models, or mirror the ThreadDeletionDriftTest approach to assert board.post_count matches a recount across soft delete and restore.
• Caching expectations: board/thread read caching is not a full invalidation layer for arbitrary direct DB writes. ACL/policy reads are uncached by design; don’t wrap them in a cache without your own invalidation strategy.
• Filament version differences: the package supports Filament 3/4/5, but resource registration and panel APIs differ. Test the admin surface on your exact Filament version.
• Extension points: custom observers, search scopes, and Filament resources are the safest extension surfaces. Keep counter logic atomic and keep raw SQL literal/bound, especially under Laravel 13.