Laravel Forum Laravel Package

Getting Started

• Pin a compatible version first. riari/laravel-forum has distinct major lines with different Laravel/PHP constraints and namespaces. Check the release you are installing against your app’s Laravel and PHP versions before writing any integration code. On an older app you may need the older branch; on a newer app confirm the package supports it rather than assuming.
• Install and publish:

  composer require riari/laravel-forum
  php artisan vendor:publish --provider="Riari\Forum\ForumServiceProvider"
  php artisan migrate
  

  If the provider publishes multiple groups, publish them deliberately: config, migrations, views, language files, and assets. Read the publish output rather than accepting everything blindly.
• Look at config/forum.php first. This is the control panel for integration: the user model, route prefix/name/middleware, pagination, validation, search, attachments, and view/layout settings. Most “the forum doesn’t fit my app” problems are solved here or by overriding views, not by editing vendor code.
• Wire up your User model. Point forum.integration.user_model at your application user class and add whatever contract/trait the installed version requires. Ensure the attributes the forum expects for an author display name exist; if your column is name and the package expects username, add an accessor rather than duplicating data.
• Verify routing and access before styling. Run php artisan route:list --path=forum, open the configured prefix (usually /forum), and confirm the package routes are registered and reachable. Check whether they are public by default; most apps want at least write actions behind auth.
• First real use case: an internal support/discussion board. Create categories such as “Announcements”, “Support”, and “Feature Requests”, then use the built-in thread/post/moderation features. This gives you a working forum quickly while you learn the package’s authorization, view, and event surfaces before exposing it to external users.

Implementation Patterns

• Theme by publishing views, not forking the package. Published Blade views under resources/views/vendor/forum are the intended customization point. Replace the package layout with your app shell, keep the package partials and route names intact, and override only what you need. Run php artisan view:clear after changes.
• Use policies for role-based behavior. The package’s authorization is policy/Gate-driven. Implement the policy methods it checks for viewing, creating, replying, editing, deleting, approving, pinning, locking, and moving. For a simple “admins can do everything” rule, use Gate::before returning true for admins and null otherwise so normal policy checks still run for everyone else.
• Separate read and write access with middleware. If guests should read but only authenticated users should post, do not simply apply auth to the whole route group. Either use policy checks for writes and keep reads public, or take over route registration in your app and group the package controllers’ write routes behind auth.
• Hook into lifecycle events. The package fires thread/post created, updated, and deleted events. Register listeners for notifications, audit logs, spam checks, search indexing, or Slack/webhook integration. Prefer queued listeners so posting stays fast.
• Use built-in moderation instead of building it. Pinning, locking, moving, approving, and soft-deleting are already modeled and exposed. Add value on top with an audit listener that records who pinned/locked/deleted what, rather than reimplementing moderation screens.
• Add custom fields in a separate migration. If you need a “solved” flag, tags, or a custom thread type, add your own columns and a migration. Override the relevant create/edit views and validate in a custom request/controller only if necessary. Do not edit already-deployed published migrations.
• Integrate author profiles through view overrides. Link the author name in thread and post partials to your existing user profile route. This is much safer than modifying package models or controllers.
• Treat search as configuration-sensitive. The package’s search support depends on the configured driver and database capabilities. On MySQL, ensure the expected full-text indexes exist; on SQLite or CI, use a null/simple driver or skip search assertions. Test search explicitly in the environment you deploy to.
• Use route names, not hard-coded URLs. Link to categories and threads with the package’s route names (forum.category.show, forum.thread.show, etc., depending on version). If you change the route prefix or name, those helpers keep your app consistent.
• For a SPA or mobile client, do not assume a JSON API. The package is primarily server-rendered Blade. You can add API routes over its models or wrap controllers, but plan for a separate resource layer, authentication strategy, and response shaping. Do not expose the web routes directly as an API.
• For multi-tenant apps, scope at the query/policy layer. A single global forum prefix is not tenant-aware. Add a tenant global scope to categories/threads/posts and enforce tenant membership in policies; if each tenant needs its own prefix, take over route registration with tenant middleware.
• Test with model factories you create yourself. The package does not necessarily ship factories for its models. Build small factories for category/thread/post, use RefreshDatabase, and write policy tests around actingAs. Seed categories explicitly in tests rather than relying on published seeders.

Gotchas and Tips

• User key type is the biggest fresh-install trap. Published migrations often assume an integer/BIGINT author_id. If your users table uses UUIDs or ULIDs, inspect and adjust the forum migrations before running them. Fixing this after data exists is painful.
• Version drift causes most “class not found” errors. Confirm the installed major line against the Laravel version. A package that works on Laravel 8 may not install cleanly on Laravel 11+, and namespaces/config keys can differ between branches. Read the changelog before upgrading.
• Republishing can overwrite your customizations. vendor:publish --force will replace edited views/config. Keep customizations in version control and diff before forcing. Prefer publishing only the specific tag you need.
• Clear caches after config changes. config/forum.php is cached in production. Run php artisan config:clear and php artisan config:cache as appropriate. Route changes require route:clear; view changes require view:clear.
• If routes disappear, check provider discovery and route caching. In older Laravel versions the service provider may need manual registration. In all versions, a stale route cache can hide newly registered forum routes.
• A 403 usually means policy mismatch, not middleware. Verify the policy is registered for the right model, the method name exactly matches what the package checks, and Gate::before returns null for non-admins. Returning false from before denies everything.
• Guest posting is easy to leave enabled. The default middleware may be web only. Decide explicitly whether unauthenticated users can create threads or replies, and enforce it in both middleware and policy.
• Escape post content correctly. Forum posts are user-generated content. If you render markdown or HTML, sanitize the output with a trusted parser/sanitizer. Do not switch to raw {!! !!} rendering just to make formatting work.
• Watch for N+1 queries on thread lists. Eager-load authors, categories, and last-post relationships in any custom listings or dashboard widgets. The package’s own listing may be fine, but your added “latest threads” sidebar often is not.
• Soft deletes affect counts and moderation screens. Deleted threads/posts may still exist in the database. Use the package’s scopes or withTrashed deliberately in admin views; otherwise counts and audit screens will disagree.
• Attachments need storage and a symlink. If attachments are enabled, configure the disk and run php artisan storage:link; otherwise downloads 404 even though uploads appear to succeed. Check file size and MIME validation in config/forum.php.
• Published assets are a separate step. If styles or scripts 404, confirm the package assets were published to public/vendor/forum (or the equivalent for your version). Do not assume vendor:publish handled assets if you used a narrow tag.
• Search failures are environment-specific. A search that works on MySQL may fail on SQLite or a database without the expected index. Add a search smoke test to CI or configure the null driver in testing.
• Do not edit vendor code. Every fix belongs in config, published views, policies, events/listeners, or your own migrations. Vendor edits vanish on composer update and make upgrades opaque.
• Plan the upgrade path before customizing heavily. The package is intentionally slim; if you need a full community suite (reactions, rich notifications, granular moderation dashboards), budget for building those around it. Use its events and view overrides as extension points, and keep your integration code in app-level classes so a future package swap is feasible.