Meerkat

Upgrading from v3

Meerkat 4 stores comments in the database and uses Statamic 6 Control Panel components. Upgrade the blueprint, templates, configuration, and existing flat-file comments.

#Breaking changes

#Tag renames

v3 Meerkat 4
{{ meerkat:create }} {{ meerkat:form }}
{{ meerkat:responses }} {{ meerkat:comments }}
{{ meerkat:count }} {{ meerkat:comment_count }}
{{ meerkat:replies-to }} {{ meerkat:replies_to }}

Inside the loop, the comment body variable also renamed:

v3 Meerkat 4
{{ content }} {{ comment }} (raw value) or {{ comment_html }} (sanitized Markdown)
{{ date }} {{ created_at }}
{{ author.name }} {{ author_name }}
{{ author.email }} {{ author_email }}

#Update comment filters

v3 used a custom filter language inside the responses tag:

1{{ meerkat:responses is:spam(false) like:content("hello") }}

Meerkat 4 uses Statamic conditions:

1{{ meerkat:comments is_spam:is="false" comment_text:contains="hello" }}

1<s-meerkat:comments is_spam:is="false" comment_text:contains="hello" />

Use field:operator="value". See Statamic's collection filtering reference.

For cross-thread queries (v3's thread:in("a","b")), separate thread IDs with a pipe, or use thread="*" for every thread:

1{{ meerkat:comments thread="blog/first|blog/second" }} ... {{ /meerkat:comments }}

2{{ meerkat:comments thread="*" order_by="created_at:desc" paginate="20" }} ... {{ /meerkat:comments }}

1<s-meerkat:comments thread="blog/first|blog/second"> ... </s-meerkat:comments>

2<s-meerkat:comments thread="*" order_by="created_at:desc" paginate="20"> ... </s-meerkat:comments>

Use thread="*" collection:is="blog" to limit the query to one collection. See Displaying comments: Querying multiple threads.

#Update comment sorting

v3 used order="property,direction|property2,direction2". Meerkat 4 uses Statamic's order_by:

1{{ meerkat:comments order_by="created_at:asc|name:asc" }}

1<s-meerkat:comments order_by="created_at:asc|name:asc" />

#Use Control Panel filters

The comments dashboard replaces the v3 status tabs with Statamic filters. Choose Filters → Moderation Status, then select pending, spam, approved, or rejected. Filtered URLs are bookmarkable, and frequently used filters can be saved as presets.

#Migrate permissions

Meerkat 4 uses Statamic permissions, roles, and user groups. Add the required Meerkat permissions to Statamic roles, then assign those roles directly to users or through user groups. Existing Meerkat access rules are not migrated automatically.

Moderators need view comments plus the permissions for the actions they perform, such as edit comments, delete comments, or the spam permissions. Signed-in commenters need submit comments. Super users bypass these checks.

See Permissions & Roles for the complete list.

#Removed features

These v3 features are not present in Meerkat 4.

  • Control Panel "Comment Reporting" page. Removed. Thread statistics remain available through {{ meerkat:thread_stats }}.
  • config/meerkat/storage.php. Meerkat 4 stores comments in the database.
  • Meerkat::onCommentCreated() static hook. Use Laravel events (CommentSubmitted, CommentSaved) and Meerkat hooks instead. See Events.
  • Per-comment permissions author array. Meerkat 4 replaces it with the current_user.* block.

#Move configuration to one file

v3 divides configuration between config/meerkat/{akismet,authors,iplist,permissions,publishing,search,storage,wordlist}.php. Meerkat 4 uses config/meerkat.php, with editorial overrides in the Control Panel. See Configuration.

#Migration steps

  1. Back up the v3 site. Make an archive of content/comments/ or commit it to a branch.
  2. Install Meerkat 4. composer require stillat/meerkat:^4.0 (replace your v3 entry).
  3. Publish the blueprint and migrations. Run php artisan meerkat:install; plain php artisan migrate is not sufficient until Meerkat's migrations have been published.
  4. Import comments. Copy the v3 content/comments tree to the same path on the new site, then run php artisan meerkat:sync. Use --path= for a different location. The command is safe to rerun.
  5. Migrate your blueprint. Copy your v3 blueprint customizations to resources/blueprints/meerkat.yaml.
  6. Migrate templates. Replace the names in Tag renames. Test the form and listing in a nonproduction environment first.
  7. Migrate configuration. Move values into the matching groups in config/meerkat.php. If editors should own publishing, author, spam, IP/word-list, rate-limit, or Akismet settings, save those overrides under Tools → Addons → Meerkat.
  8. Migrate permissions. Add Meerkat permissions to Statamic roles and assign those roles to the appropriate users or user groups.

#Import details

#Soft-deleted threads

Meerkat recognizes both v3 thread-deletion formats:

  • An _-prefixed thread directory imports under its real thread ID as soft-deleted. The first sync renames the directory and records trashed: true in .meta.
  • A thread with trashed: true in .meta imports as soft-deleted without a directory rename.

If both the prefixed and unprefixed directories exist, Meerkat reports the conflict and leaves them unchanged. Use php artisan meerkat:sync --dry-run to find these conflicts before importing.

#Comment field mapping

v3 front matter Meerkat 4 value Notes
id timestamp_id Preserves the original timestamp-based ID.
name, email author name and email Imported as stored.
user_ip, user_agent, referer request metadata Privacy settings affect new submissions, not imported values.
published publication state A missing value imports as unpublished.
spam spam state Also records that the comment has been checked.
comment / content comment body Used when the file has no Markdown body.
is_deleted moderation tombstone Preserves removed-comment placeholders.
authenticated_user Statamic author Preserves the associated user ID.
Other values custom comment data Custom blueprint fields remain available after import.

#Revision history

The sync imports each comment's current content but does not convert v3 .revisions history into Meerkat 4 revisions. Keep the original tree in Git if that edit history matters. Meerkat 4 begins its own revision history with later edits.

#After upgrading

  • Open the Comments dashboard in the Control Panel and verify that the imported data is correct.
  • Run php artisan meerkat:health to verify the database connection, comment blueprint, and required tables.
  • Run php artisan meerkat:sync-metrics to rebuild thread statistics.
  • Verify your Akismet credentials.

Was this page helpful?