ModxComments — a free comments component for MODX 2 and MODX 3

When I needed a comments system for a MODX website, it quickly became clear that I did not just want a form with a “Your comment” field.

I wanted a complete, practical component that could be installed once and then reused across different projects without constant workarounds.

And the list of requirements turned out to be quite specific.

  • I wanted comments to work without page reloads, through AJAX, while keeping the actual MODX page fully cacheable.
  • I wanted proper threaded discussions, where users could reply not only to the first comment but also to other replies, without breaking the thread structure during pagination or deletion.
  • I wanted both guest comments and authenticated users, while MODX administrators should not need to log in separately on the frontend if they were already authenticated in the manager.
  • I wanted authors to be able to edit and delete their own comments for a configurable period of time, and I wanted guest ownership to be handled securely as well.
  • I wanted proper moderation: immediate publishing or pending approval, statuses such as pending, spam and published, and separate rules for guests and authenticated users.
  • I wanted a proper comments management panel inside MODX, with search, filters, publishing, moderation, spam marking, soft deletion and permanent deletion from the database.
  • I wanted 👍 / 👎  voting, pagination, permanent comment links, relative timestamps, convenient replies, quoting, emoji and link insertion.
  • I wanted email notifications for administrators and reply authors, while keeping email templates editable through normal MODX Chunks.
  • I wanted anti-spam protection without being locked to one CAPTCHA provider, so the component should support Cloudflare Turnstile, hCaptcha, Google reCAPTCHA v2/v3 and Yandex SmartCaptcha.
  • I also wanted the whole system to be properly secured: CSRF protection, resource signing, rate limiting, safe guest cookies, server-side CAPTCHA verification, escaped user content and no way to use the public connector as an arbitrary write endpoint.

And there was one more important requirement: I did not want to maintain two separate components for MODX 2 and MODX 3.

I wanted one transport package that could be installed on an old MODX 2.8 project as well as on MODX 3.

And ideally, installation should come down to something as simple as this:

[[ModxComments]]

Install the package, add one snippet call — and the comments work.

That is how ModxComments was created: a free comments component for MODX Revolution that works with both MODX 2.8.x and MODX 3.0–3.2.

Project repository:

https://github.com/web86/ModxComments

The component is free, and the source code is openly available in the repository.


Why the comments are AJAX-based

One of the main ideas behind ModxComments is that comments should not interfere with page caching.

A regular MODX page can remain fully cached:

[[ModxComments]]

The page HTML is rendered by MODX as usual, while the comments list is loaded separately through AJAX.

The same approach is used for:

  • posting comments;

  • replying to comments;

  • voting;

  • editing;

  • deleting;

  • switching comment pages.

So there is no need to make the whole resource uncached or turn the page into a collection of [[!Snippet]] calls.


One package for MODX 2 and MODX 3

This is one of the main features of ModxComments.

The same transport package can be installed on:

  • MODX Revolution 2.8.x;

  • MODX Revolution 3.0;

  • MODX Revolution 3.1;

  • MODX Revolution 3.2.

Internally, the component contains separate compatibility layers for MODX 2 and MODX 3, and the correct implementation is selected automatically.

So a site owner does not need to wonder:

“Is this the MODX 2 version or the MODX 3 version?”

There is only one package.


Threaded comments

Comments support full reply trees.

Users can reply to a root comment or to an existing reply.

The result looks like a normal discussion tree:

Comment
└── Reply
    └── Reply to a reply
        └── Another reply

The maximum nesting depth is configurable in MODX system settings.

For example:

modxcomments.max_depth = 5

The internal structure is stored in a way that keeps the thread intact during pagination.


Guest comments and authenticated users

The component supports both authenticated MODX users and regular site visitors.

Guests can submit comments with their name and email address.

For authenticated users, author data is taken from their MODX profile.

Guest comments can also be disabled completely through a system setting.


Administrators can comment too

There is another small but useful feature.

If an administrator is already logged into the MODX manager, the component can recognize that session on the frontend.

There is no need to log in again as a separate web user.

Administrator comments receive a special badge:

★ Admin  Administrator Name

The displayed name comes from the MODX user profile.


Editing and deleting your own comments

After submitting a comment, its author can edit or delete it for a configurable amount of time.

The time window is controlled by:

modxcomments.edit_time = 900

900 seconds means 15 minutes.

For authenticated users, ownership is determined by their MODX user ID.

For guests, a separate secure browser identifier is used. The raw secret token is never stored in the database — only its hash is stored.


Soft deletion

When a user deletes their own comment, the database record is not physically removed.

This is important for discussion trees.

Imagine the following structure:

Comment #1
└── Reply #2
    └── Reply #3

If comment #1 were simply removed from the database, its replies would lose their parent.

So regular deletion is soft deletion: the comment content is hidden, while the thread structure remains intact.


Permanent deletion from the manager

Administrators have a separate action:

Delete permanently

This really removes the comment from the database.

If the selected comment has replies, those replies are removed as well.

Related votes are also deleted.

So after permanent deletion, the database no longer contains the selected comment, its descendant thread or any associated vote records.

The regular soft-delete action remains available for normal moderation.


Comment moderation

New comments can either:

  • be published immediately;

  • be sent for moderation.

The rules can be configured separately for guests and authenticated users.

For example:

modxcomments.guest_status = pending
modxcomments.user_status = published

With this setup, comments from authenticated users are published immediately, while guest comments require moderator approval.


Comments management panel

After installation, MODX gets a separate menu item:

Comments

From there, administrators can:

  • view all comments;

  • search by text, name and email;

  • filter comments;

  • inspect threads and replies;

  • publish comments;

  • send comments back to moderation;

  • mark comments as spam;

  • soft-delete comments;

  • permanently delete comments.

Replies also show which comment they were posted under.

Administrator-authored comments are highlighted separately.


Voting 👍 / 👎 

Each published comment can have a rating.

Users can vote with:

  • 👍

  • 👎 

A vote can also be changed or removed.

For authenticated users, the vote is linked to the user account.

For guests, a secure browser identifier is used.


Anti-spam protection

The component includes several anti-spam layers.

Rate limiting

You can configure how many comments can be submitted within a certain period of time.

For example:

modxcomments.rate_limit_count = 5
modxcomments.rate_limit_window = 60

This allows no more than five comments per minute.

The IP address is not stored in plain text — only a hash is stored.

Honeypot

The form contains a hidden honeypot field for simple bots.

Normal users never see it, while many automated spambots fill it in.

Multiple CAPTCHA providers

CAPTCHA is not tied to a single service.

The following providers are currently supported:

  • Cloudflare Turnstile;

  • hCaptcha;

  • Google reCAPTCHA v2;

  • Google reCAPTCHA v3;

  • Yandex SmartCaptcha;

  • or CAPTCHA can be disabled entirely.

The provider is selected through:

modxcomments.captcha_provider

For example:

turnstile

or:

hcaptcha

or:

recaptcha

or:

yandex

CAPTCHA can also be required only for guests:

modxcomments.captcha_guests_only = 1

Authenticated users can then comment without CAPTCHA.


Server-side CAPTCHA verification

CAPTCHA is not validated only in JavaScript.

The token is always sent to the server, and the component verifies it through the selected CAPTCHA provider API.

That means simply sending a POST request directly to the endpoint is not enough to bypass the check.

For Google reCAPTCHA v3, the score is also validated.

The minimum score can be configured:

modxcomments.recaptcha_min_score = 0.5

Email notifications

ModxComments can send notifications about new comments.

Administrator notifications can be enabled with:

modxcomments.notify_admin = 1

The recipient email address can be configured separately. If it is left empty, the standard MODX emailsender setting is used.

The component can also notify a comment author when a new published reply is posted to their comment.


Editable email templates

Email content is stored in regular MODX Chunks.

For example:

ModxCommentsEmailAdminSubject
ModxCommentsEmailAdminBody
ModxCommentsEmailReplySubject
ModxCommentsEmailReplyBody

They can be edited directly in the MODX manager.

User-edited templates are preserved during component upgrades.


Pagination

Large discussions do not have to load hundreds of threads at once.

The number of root discussion threads per page is controlled by:

modxcomments.threads_per_page = 20

Replies belonging to each visible root thread are loaded together with it.

This means a reply tree is never split between pages.


Frontend conveniences

The frontend includes a number of small details that make the comment system more pleasant to use:

  • threaded replies;

  • parent comment quote previews;

  • editing without reloading the page;

  • deletion without browser alert() or prompt() dialogs;

  • character counter;

  • link insertion;

  • emoji;

  • relative timestamps such as “5 minutes ago”;

  • permanent comment links such as #comment-123;

  • automatic scrolling to a newly submitted comment;

  • highlighting of a newly added comment;

  • loading and submission states;

  • a visible “awaiting moderation” state.


Russian and English interfaces

The frontend and manager interfaces use separate MODX lexicons.

Out of the box, the component includes:

  • Russian;

  • English.

Interface text is not hard-coded directly in JavaScript.

Additional translations can be added through the normal MODX lexicon mechanism.


Security

A lot of attention was paid to making sure the public AJAX API could not be used as an arbitrary write endpoint.

Every rendered comments widget receives a signed resource token.

The token is tied to:

  • the resource ID;

  • the MODX context;

  • a private site secret.

The signing key is generated automatically during installation:

modxcomments.resource_signing_key

This prevents someone from simply taking the public comments API and passing an arbitrary resource ID to it.

The component also includes:

  • CSRF protection;

  • permission checks;

  • server-side CAPTCHA verification;

  • request size limits;

  • HttpOnly cookies;

  • SameSite cookies;

  • safe handling of user content;

  • URL validation;

  • protection against MODX tag execution inside email templates;

  • manager session validation;

  • POST-only administrative mutations.

Unexpected public errors do not expose internal PHP exceptions or server file paths.


User content remains safe

Comments are not treated as HTML.

User-provided HTML is never executed.

Text is escaped, while safe HTTP/HTTPS links are supported.

Users can write:

https://example.com

or:

[Link title](https://example.com)

Everything else remains plain text.


MODX events

The component provides its own MODX events for integration with other functionality:

ModxCommentsBeforeCommentCreate
ModxCommentsOnCommentCreate
ModxCommentsOnCommentUpdate
ModxCommentsOnCommentDelete
ModxCommentsOnCommentPublish
ModxCommentsOnCommentVote

This makes it possible to attach a custom MODX plugin and extend the behavior.

For example:

  • send a Telegram notification;

  • synchronize comments with an external system;

  • run an additional anti-spam check;

  • collect custom statistics.


How to install ModxComments

Installation is standard for MODX.

Download the transport ZIP and install it through:

Packages → Installer

Then clear the MODX cache.

Ready-to-install builds and source code are available in the repository:

https://github.com/web86/ModxComments

A separate directory is provided for ready-made transport packages:

distr/

How to display comments

After installation, add this snippet call to the desired resource or template:

[[ModxComments]]

That is all.

You do not need to manually include the connector, JavaScript or CSS.

The component loads the required frontend files automatically.

The snippet call itself can remain cacheable.


Basic configuration

For most sites, only a few settings are needed.

For example:

modxcomments.allow_guests = 1
modxcomments.guest_status = pending
modxcomments.user_status = published
modxcomments.max_depth = 5
modxcomments.threads_per_page = 20

If CAPTCHA is needed:

modxcomments.captcha_enabled = 1
modxcomments.captcha_provider = turnstile
modxcomments.captcha_guests_only = 1

Then simply configure the keys for the selected CAPTCHA provider.


Who is this component for?

ModxComments can be useful for:

  • blogs;

  • articles;

  • news sites;

  • documentation;

  • catalogs;

  • product pages;

  • service pages;

  • small communities;

  • any MODX site that needs discussions.

The component does not dictate the structure of your template and barely interferes with the page rendering itself.


Free to use

ModxComments is a free component.

The project started from a practical need: I wanted a modern comments system that could be used both on older MODX 2 projects and on MODX 3 without maintaining two separate codebases.

If the component turns out to be useful for other projects as well, then the goal has been achieved.

Source code, documentation and the latest version are available here:

https://github.com/web86/ModxComments

To use it, install the package and add:

[[ModxComments]]

That is all. The component takes care of the rest.

Хотите заказать вебсайт? Давайте познакомимся и обсудим ваш проект. 30 минут бесплатно

Контакты
Спросить моего помощника