Advanced Filtering

Meerkat exposes an incredibly powerful filtering API to Statamic developers. This API allows developers to craft custom filters, organize multiple filters into a single group to simplify template code, and to also define custom variables that can be automatically injected when a filter is being evaluated.

#Creating the Meerkat Helper File

Meerkat will look for a meerkat/filters.php file when it starts. If you do not have this directory and file, feel free to create it now before we continue. The directory structure should look similar to this once done:

1project-rooot/
2├── app/
3├── bootstrap/
4├── .../
5├── meerkat/
6|  ├── fiters.php

Use the following as the default content for this file:

1<?php
2 
3use Stillat\Meerkat\Support\Facades\Comments;

#Custom Filter Groups

The filter syntax can get quite long if your chaining multiple filters, or be annoying to keep updated if you're using them in many places (and not using Statamic partials). To help with this, you can define a filter group like so:

1<?php
2 
3use Stillat\Meerkat\Support\Facades\Comments;
4 
5Comments::filterGroup('myGroup', 'is:spam(false)|is:published(*)');

Then, in your Antlers template, you may refer to this filter by prefixing it with @:

1{{ meerkat:responses filter="@myGroup" }}
2 
3  {{ comments }}
4    <!-- Render your comment thread here. -->
5  {{ /comments }}
6 
7{{ /meerkat:responses }}

#Custom Variable Input

As we saw in the Basic Filtering guide, we can supply input to our comment filters:

 1{{ meerkat:responses filter="user:in(92283631-5e22-4e21-8764-0aad0cf59bfe, 6f2d63ce-e760-4c5b-85ad-7ddbaf7d7ada)" }}
 2 
 3<ul>
 4  {{ comments }}
 5  <li>
 6    <p>{{ author.name }} says: {{ content }}</p>
 7  </li>
 8  {{ /comments }}
 9</ul>
10 
11{{ /meerkat:responses }}

When there are only a few values, this can be maintained easily within the template. However, with Meerkat comment filters, you can inject values into the filter. Within the meerkat/filters.php site helper file, we can teach Meerkat how to resolve filter input like so:

 1<?php
 2 
 3use Stillat\Meerkat\Support\Facades\Comments;
 4 
 5Comments::resolve('usersToInclude', function () {
 6    // Whatever PHP code you want to generate the
 7    // list of user ID's you are interested in.
 8 
 9    return [
10        '*current*', // The *current* shortcut works here, too :)
11        '9d697ec3-9e55-4a91-b20c-3ae3c558e925',
12        '38fda2fb-2d86-46bf-a4ab-18e2ae67ffec',
13        '07ec3f6b-ec1b-4b5c-a63a-efe05640b6d6'
14    ];
15});

Then, in the Antlers template we can let Meerkat know we want to use the returned value of the usersToInclude callback as the filter's input by prefixing it with the $ symbol:

 1{{ meerkat:responses filter="user:in($usersToInclude)" }}
 2 
 3<ul>
 4  {{ comments }}
 5  <li>
 6    <p>{{ author.name }} says: {{ content }}</p>
 7  </li>
 8  {{ /comments }}
 9</ul>
10 
11{{ /meerkat:responses }}

This feature works even in PHP support is disabled for the Antlers template engine. Don't worry - the syntax is similar to PHP's variable syntax, but does not enable PHP support behind the scenes.

#Defining Custom Filters

Custom filters can also be defined in the meerkat/filters.php file using the filter helper method. The following filter will only return comments that contain the phrase hello in their content:

 1<?php
 2 
 3use Illuminate\Support\Str;
 4use Stillat\Meerkat\Support\Facades\Comments;
 5 
 6 
 7Comments::filter('myfilter', function ($comments) {
 8  return array_filter($comments, function ($comment) {
 9    return Str::contains($comment->getContent(), 'hello');
10  });
11});

The custom filter can be used like any built-in filter in templates and groups:

 1{{ meerkat:responses filter="myfilter" }}
 2 
 3<ul>
 4  {{ comments }}
 5  <li>
 6    <p>{{ author.name }} says: {{ content }}</p>
 7  </li>
 8  {{ /comments }}
 9</ul>
10 
11{{ /meerkat:responses }}

And in a filter group:

1<?php
2 
3use Stillat\Meerkat\Support\Facades\Comments;
4 
5Comments::filterGroup('customGroup', 'myfilter|is:spam(false)');