Comments Laravel Package

Getting Started

1. Confirm the foundation first. laravel-enso/comments is not a standalone package — it is a module of the Enso ecosystem. Before installing, verify the host application already runs laravel-enso/enso (or at least Enso core, users, and the API conventions). If the app is a plain Laravel project, either install Enso scaffolding first or budget time to adapt the package's routes, controllers, and policies by hand.
2. Install via Composer.

   composer require laravel-enso/comments
   

3. Publish and migrate.

   php artisan vendor:publish --tag=comments
   php artisan migrate
   

   Inspect the published migration before running it on an existing database — the comments table name may collide with an in-house table.
4. Look at these files first, in order:
   • src/Comment.php — the Eloquent model and its relations (user, commentable, tagged users).
   • src/Traits/Commentable.php (or similarly named trait) — the polymorphic comments() relation you add to any model.
   • src/Policies/CommentPolicy.php — the authorization rules that govern create/update/delete.
   • src/routes/api.php — the HTTP surface (index, store, update, destroy), and any tagging endpoints.
   • config/enso/comments.php (or the package config) — notification and tagging toggles.
5. Wire up your first model. Add the commentable trait to a model you already expose in the UI:

   use LaravelEnso\Comments\Traits\Commentable;
   
   class Project extends Model
   {
       use Commentable;
   }
   

6. First use case: a comment thread on a record. Create a comment through the API (typically POST /api/comments with body, commentable_type, commentable_id), then list it back with GET /api/comments?commentable_type=...&commentable_id=.... Confirm the comment appears with its author and that a second user cannot edit it — that proves the policy layer is active.

Implementation Patterns

Trait-per-model, not a central registry. Enso's comments are polymorphic, so the normal pattern is to add the trait to each model that should be discussable (orders, projects, tickets). The relation is then $project->comments, usually eager-loaded with ->with('user') to avoid N+1s in listings.

Authorization belongs in the policy, not the controller. The package's selling point is "policy enforced rules," which typically means: any authenticated user with access to the parent record can comment; authors can edit their own comments; admins or record owners can delete. Enso registers the policy automatically in most setups, but if comments are created through a custom controller, call $this->authorize('create', Comment::class) explicitly. For per-record rules (e.g. "only the project owner can comment on a locked project"), extend the policy with a createFor/custom ability and check the parent model.

User tagging. Tagging is normally expressed either as an array of user IDs in the payload or as @username tokens in the body, which the package resolves server-side. When integrating with a frontend, keep tagging and notification logic on the server: send IDs or mention tokens, and let the package dispatch notifications. If you implement a custom tag parser, reuse the package's resolution path so mentioned users still receive the real-time notification.

Real-time notifications depend on Laravel broadcasting, not just the package. The working combination is:

• BROADCAST_DRIVER set to pusher, redis, or log for local testing,
• a running queue worker (php artisan queue:work) because notifications are queued,
• a private channel per user (commonly App.Models.User.{id}),
• Echo configured in the frontend to subscribe to that channel.

Without those four pieces the comments still save, but the "real time" part silently does nothing.

Integration tips.

• If you use Enso's Vue frontend, keep the backend package and its @enso-ui/comments counterpart version-matched; mismatches show up as missing props or 404s on endpoints.
• For comment listings, eager-load user and any tagged-user relation, and paginate — long threads on a busy record will otherwise become a slow endpoint.
• Hook into model events (created, deleted) for audit logging or analytics rather than overriding the controller.
• To customize behavior, extend the published Comment model and rebind it in a service provider, or override the notification class; avoid editing vendor files because Composer updates will overwrite them.

Gotchas and Tips

• Age and version compatibility. The last release is from April 2019, so expect Laravel 5.7–6.x era constraints. On Laravel 8+ you will likely hit PHP version constraints, deprecated helpers, and facade/discovery issues. Check composer why-not before committing to the package, and plan a fork or replacement if the app is on a modern Laravel.
• It is not a drop-in for a vanilla Laravel app. Enso packages assume the Enso users table, role/permission model, and API response conventions. On a plain app, you may end up using the schema and policy as a reference implementation rather than the controller layer.
• Broadcasting fails quietly. No queue worker, no Echo subscription, or a log driver means notifications are "sent" but never seen. Test with log first, then switch to a real driver. Watch storage/logs/laravel.log and the failed-jobs table.
• Morph maps. If you register Relation::morphMap(), the commentable_type stored in the database changes from a fully qualified class to your alias. The frontend and any hard-coded type checks must use the same alias, or comments silently attach to "nothing" and return empty threads.
• No automatic cleanup on parent deletion. Deleting a project generally does not cascade its comments. Add a deleting listener on the commentable model to purge comments, or use a database foreign key with cascadeOnDelete — but only if you control the migration.
• Policy registration is easy to miss. If custom abilities return 403 for everyone, check that CommentPolicy is registered in AuthServiceProvider (or that Enso's auto-registration is enabled for the namespace) and test with Gate::forUser($user)->allows('update', $comment).
• Config caching. After publishing or editing the package config, run php artisan config:clear locally and config:cache in deployment; stale cached config is a common cause of notifications not firing.
• Route collisions. api/comments may already exist in the application. Run php artisan route:list --path=comments after install to see what actually won and which middleware applies.
• Debugging checklist: confirm the migration ran (SHOW TABLES LIKE 'comments'), confirm the trait is on the model (class_uses_recursive), confirm the policy via Gate, confirm the queue worker is running, then confirm the frontend subscribes to the right private channel. That sequence isolates most failures in this package.
• Extension points worth knowing: the policy (permission logic), the Comment model and its notifications (custom payloads), and model events (side effects like audit logs). These three cover most day-to-day customization without forking the package.