Add-ons can consume the API's of other Statamic add-ons. Because of this, Meerkat provides a fairly simple, but powerful API that you can use in your own add-ons.

Consuming an API

You generally consume an API within the context of a Statamic add-on by calling the api() method within your addon file. To access an add-on's API, pass in the name of the API and then call a method on the API:

<?php

namespace Statamic\Addons\Awesome;

use Statamic\Extend\Tags;

public class AwesomeTags extends Tags
{

    public function index()
    {
        $result = $this->api('Meerkat')->someMethod();
    }

}

API Methods

The following sections will discuss the various API methods that are generally safe for you to use within your own add-ons.

getComments

The getComments method can be used to retreive the comments for a given context (Meerkat defines a context as any piece of data that can have comments associated with, so pretty much everything in Statamic can have comments!). To use this method, you must supply the ID of the context (the ID of a blog post, for example):

<?php

namespace Statamic\Addons\Awesome;

use Statamic\Extend\Tags;

public class AwesomeTags extends Tags
{

    public function index()
    {
        $comments = $this->api('Meerkat')
                         ->getComments('f5e0a21b-1b9d-4bb8-8638-6b9c3b2612cf');
    }

}

This method will return an instance of Statamic\Addons\Meerkat\Comments\CommentCollection which is essentially a special version of Statamic's Statamic\Data\DataCollection\DataCollection. You can read more about data collections here.

getContext

This method is like the logical opposite of the getComments. They have different personalities, but were made for one another and are meant to be together ♡. This method will return the original Statamic\Data\Entries\Entry for any given comment based on the comment's ID:

<?php

namespace Statamic\Addons\Awesome;

use Statamic\Extend\Tags;

public class AwesomeTags extends Tags
{

    public function index()
    {
        $entry = $this->api('Meerkat')->getContext('1443303352');

        // You can also use the `getEntry()` method:
        $entry = $this->api('Meerkat')->getEntry('1443303352');
    }
}

findOrFail

The findOrFail method can be used to retrieve a single comment by it's ID. If the comment is not found, an instance of Statamic\Addons\Meerkat\Comments\CommentNotFoundException will be thrown.

<?php

namespace Statamic\Addons\Awesome;

use Statamic\Extends\Tags;
use Statamic\Addons\Meerkat\Comments\CommentNotFoundException;

public class AwesomeTags extends Tags
{

    public function index()
    {
        try {
            $comment = $this->api('Meerkat')->findOrFail('1443303351');
        } catch (CommentNotFoundException $e) {
            // Handle comment not found.
        }
    }

}

This method will return an instance of Statamic\Addons\Meerkat\Comments\Comment if the comment is found.

findComments

The findComments method can be used to find a single comment, or a list of comments based on their IDs. This comment does not throw an exception if the comment is not found.

<?php

namespace Statamic\Addons\Awesome;

use Statamic\Extends\Tags;

public class AwesomeTags extends Tags
{

    public function index()
    {
        // Find a single comment.
        $comments = $this->api('Meerkat')->findComments('1443303351');

        // Find multiple comments.
        $comments = $this->api('Meerkat')->findComments([
            '1443303351',
            '1443303352',
            '1443303353'
        ]);
    }

}

This method will return an instance of Statamic\Addons\Meerkat\Comments\CommentCollection regardless of how many comments were found.

Determining the Meerkat Version

You might not have a need for this, but you can learn a little more about the installed version of Meerkat using the version() method:

<?php

namespace Statamic\Addons\Awesome;

use Statamic\Extends\Tags;

public class AwesomeTags extends Tags
{

    public function index()
    {
        // Get the Meerkat version.
        $version = $this->api('Meerkat')->version();
    }

}