Overview
What it does
Section titled “What it does”Comments adds threaded public discussion to registered content types and gives moderators a site-scoped queue. Only approved comments are returned to the public thread; pending, rejected, spam, and archived records remain private.
Setup requirements
Section titled “Setup requirements”Run capell-comments:install to publish the package config, database migrations, and settings migration, then migrate the application. Add the Comments thread renderable where discussion should appear. Automatic injection into the main content hook is disabled by default and is controlled by the deployed capell-comments.auto_inject configuration.
Keep a queue worker running. Author verification, moderator alerts, and reply notifications are queued; a stopped worker leaves comments waiting for email verification and prevents notification mail from being delivered. Configure moderator recipient addresses under capell-comments.notifications.moderators. Reply notifications can be disabled globally in config, and every author notification includes its own tokenised opt-out link.
Set stable CAPELL_COMMENTS_EMAIL_HASH_SECRET and CAPELL_COMMENTS_VISITOR_HASH_SECRET values when you do not want the application key used for hashing. Changing either secret later changes the deterministic hashes used to match authors or visitors.
Configure publication and identity
Section titled “Configure publication and identity”Open the package’s Comments settings to enable or disable comments and choose:
- Identity mode: anonymous visitors, authenticated users, or both.
- Publication policy: require approval, auto-publish, or disable public publication.
- Verification flow: verify then moderate, or moderate then verify.
- Whether email verification is required, the maximum reply depth, and the verification-token lifetime.
Site and commentable-type overrides can replace those rules for a narrower scope. Treat auto-publish carefully: when verification is required, only a verified, trusted, unblocked author is eligible for automatic publication. A reply is not approved before its parent is public.
Spam screening applies the local minimum form age, link limit, blocked terms, and any configured external spam providers before verification or moderation. Public submissions are also throttled and bot-trap fields are rejected.
Moderate comments and authors
Section titled “Moderate comments and authors”Go to Comments in the admin. The Moderation inbox focuses pending email verification, pending approval, and spam records. The full Comments resource lets an authorised moderator approve, reject, archive, mark as spam, add a moderation note, and open the related public context. Each transition records a moderation event.
Use Comment authors to inspect verification state and internal notes, mark an author trusted, or block them. Trust can make future comments eligible for auto-publication; blocking prevents that author from receiving reply notifications. Visitors create and reply through the public thread rather than the admin.
Comment access requires ViewAny:Comment or View:Comment and an assigned site. The current table’s approve, reject, spam, and archive actions require Update:Comment; deletion requires Delete:Comment. The policy also exposes Approve:Comment for integrations that authorise the dedicated approve ability. Author records use the corresponding view/update CommentAuthor permissions. Global administrators bypass site assignment; other moderators cannot use records from another site.
Privacy and retention
Section titled “Privacy and retention”Author names and email addresses are encrypted. Email, visitor IP, and user-agent matching values are stored as one-way hashes; comment bodies, statuses, spam reasons, moderation notes, and moderation history remain database content. Approved bodies and author display names are deliberately rendered publicly, with comment content escaped.
When Privacy Center is installed, Comments contributes subject export and erasure handlers. The erasure flow anonymises the author’s identity while preserving public discussion content.
capell-comments:privacy-retention is an operator command, not a package-scheduled task. Run it first with --dry-run --json, then schedule it at the cadence required by your policy. The default 180-day window deletes old consumed/expired tokens and clears stale visitor hashes and moderation notes; it does not delete comment bodies. Supplying --email anonymises matching author records and deletes their tokens, optionally within one --site-id. Database backups need a compatible retention policy as well.
For how to use Comments, see the admin guide. For developers: see the README.