Events

Developers
Version 1.5.8+
8 min read

You are viewing the documentation for Meerkat version 1 for Statamic 2. The latest version is Meerkat 2 for Statamic 3.

Read v2 docs

Events are a way for your custom addon to be notified of when Meerkat does something. If you are new to events, or would like a quick refresher of Statamic's event system, you should read through the official documentation here.

Events

Meerkat raises many events that can be used in your own custom add-ons to extend and react to actions that Meerkat takes. The events listed below are considered "stable" and can be used in your add-ons.

For the extremely adventurous, you may discover additional events raised when "source diving". While these may not change with every update, they should not be considered stable and should be used at your own risk!

Meerkat.comment.beforeDelete

Deleting a comment is a little trickier than you might think. For example, if you delete a comment that has replies, those replies also have to be removed from the system. However, Meerkat has got you covered and fires a very useful event: Meerkat.comment.beforeDelete. Any event handlers should accept a reference to a $comment variable:

public $events = ['Meerkat.comment.beforeDelete' => 'handle'];

public function handle(&$comment);

The value that is passed into your event handlers is a special object of type Statamic\Addons\Meerkat\Comments\CommentRemovalEventArgs. Using this, you have access to all of the comment's data before it is removed like so:

public $events = ['Meerkat.comment.beforeDelete' => 'handle'];

public function handle(&$comment)
{
    // Access comment data.
    $email = $comment['email'];
}

Since Meerkat will recursively find all of the replies to a comment, you can use the isTarget() method to determine if the current comment is the comment that was intended to be removed (if this is true, this is the comment that was going to be deleted. If false, it is a reply to that comment):

public $events = ['Meerkat.comment.beforeDelete' => 'handle'];

public function handle(&$comment)
{
    if ($comment->isTarget()) {
        // This is the comment that was deleted
        // by the user, in the control panel.
    }
}

The result of isTarget() always returns true when the last comment in the list of comments to be removed is being prepared for removal (due to the way Meerkat handles comment sorting internally). This means that if isTarget() is true, there will be no further iterations for the current comment removal process.

On some sites and services, you may have noticed that when a comment has been removed by an administrator, the comment still appears on the site but usually has it's content removed; it's replies are left in-tact. This can be accomplished using Meerkat (yes, really) by calling the keep() method when a comment is being prepared for deletion. This will instruct Meerkat to keep the target comment, as well as all replies, and just set an is_deleted value on the comment itself:

public $events = ['Meerkat.comment.beforeDelete' => 'handle'];

public function handle(&$comment)
{
    // Mark the comment as deleted, but keep it in storage.
    $comment->keep();
}

Important: Meerkat really does not like "orphaned" comments. After the results of all the add-ons that provide information when the Meerkat.comment.beforeDelete event is fired, Meerkat will then analyze the results to ensure that there are no orphaned comments. What this means that, if a parent comment was not set to keep(), but it's replies were, the replies would also be removed. Plan accordingly.

Meerkat.comment.removed

This event is raised when a comment is deleted from the Control Panel. If the comment had replies, this event will also be raised for each reply and any replies to that reply. This event provides you with the id of the comment that was removed.

public $events = ['Meerkat.comment.removed' => 'handle'];

public function handle($id);

Meerkat.comment.approved

This event is raised after a comment has been approved from the Control Panel. Handlers should accept only one argument, which is an instance of Statamic\Addons\Meerkat\Comments\Comment:

public $events = ['Meerkat.comment.approved' => 'handle'];

public function handle($comment);

Meerkat.comment.unapproved

This event is raised after a comment has been un-approved from the Control Panel. Handlers should accept only one argument, which is an instance of Statamic\Addons\Meerkat\Comments\Comment:

public $events = ['Meerkat.comment.unapproved' => 'handle'];

public function handle($comment);

Meerkat.comment.markedAsSpam

This event is raised after a comment has been marked as spam. Handlers should accept only one argument, which is an instance of Statamic\Addons\Meerkat\Comments\Comment:

public $events = ['Meerkat.comment.markedAsSpam' => 'handle'];

public function handle($comment);

Meerkat.comment.markedAsNotSpam

This event is raised after a comment has been marked as not spam (or ham). Handlers should accept only one argument, which is an instance of Statamic\Addons\Meerkat\Comments\Comment:

public $events = ['Meerkat.comment.markedAsNotSpam' => 'handle'];

public function handle($comment);

Meerkat.comments.collecting

With Meerkat, the process of gathering all of the comments for a given stream is called collecting the comments. This event is raised for each comment collected during this process. The event handler should accept a single parameter $data, which will be an array of the comment's data.

You can return modified comment data, add new information, etc. and use it within your template by modifying the array that is returned by your event handler.

public $events = ['Meerkat.comments.collecting' => 'handle'];

public function handle($data)
{
    // Do anything you'd like with the comment data.

    // Give the data back.
    return $data;
}

Meerkat.comment.creating

This event is rzasied before a comment is saved to disk; this makes it useful for adding or modifying data before it is saved. Handlers should accept a single argument, which will be an array containing the comment's data.

You may add or modify any data that you wish, but it is recommended that you do not remove any of the keys that already exist in the data array. Also, if you are simply modifying or filtering out the data, consider doing so when the comments are being collected to be presented on your site instead; this will allow you to keep the original comment.

public $events = ['Meerkat.comment.collecting' => 'handle'];

public function handle($data)
{
    // Do anything you'd like with the comment data.

    // Give the data back.
    return $data;
}

Meerkat.comment.attach.failed

This event is raised whenever there is a problem adding a new comment to a comment stream (a stream is essentially a collection of comments that belong to a context, such as a blog post). Handlers should accept a single argument, which will be an instance of Statamic\Exceptions\PublishException:

public $events = ['Meerkat.comment.attach.failed' => 'handle'];

public function handle($exception);

Meerkat.comment.attach.reply

This event is raised after a comment has been saved as a reply to another comment. Handlers may accept two arguments, which are the ID of the comment being replied to as well as the data of the new comment, which will be an instance of Statamic\Addons\Meerkat\Forms\Submission:

public $events = ['Meerkat.comment.attach.reply' => 'handle'];

public function handle($replyingToId, $submission);

Meerkat.comment.attach.success

This event is raised after a new comment has been saved. This event will be emitted after a new comment has been saved or a reply to a comment has been saved. Handler's should accept an instance of Statamic\Addons\Meerkat\Forms\Submissions:

public $events = ['Meerkat.comment.attach.success' => 'handle'];

public function handle($submission);

Meerkat.guard.starting

This is a special event, as it is emitted when Meerkat's spam guard service is starting. Any handlers of this event may use this as an opportunity to register their own spam guard implementations. Meerkat uses this event internally to register the default spam guards, for instance.

Event handlers should accept one argument, which will be an instance of Statamic\Addons\Meerkat\Comments\Spam\Guard:

public $events = ['Meerkat.guard.starting' => 'handle'];

public function handle($guard);

Any custom spam detectors must implement the Statamic\Addons\Meerkat\Contracts\Comments\Spam\SpamDetector. After doing this, you may use the registerDetector method to load your custom spam detectors:

public $events = ['Meerkat.guard.starting' =>? 'handle'];

public function handle($guard)
{
    // Initialize your custom spam detector.
    $spamDetector = new MyAwesomeSpamDetector;

    $guard->registerDetector($spamDetector);
}