filter option syntax

Filter Option Syntax

The Filter option is accepted by all core decorators and by the show method of Malini\Post. When passed as an option of a decorator, this value is applied to the attributes exposed by that single decorator; when passed to the show method it is applied to all the Malini\Post attributes. It has a pretty flexible syntax, as it accepts the list of attributes to expose in different ways.

Nested Array Notation

The defult way is using an array with nested information. If we wanted to expose the three attributes id, title and featuredimage, we could do it this way:

$a_malini_post
    ->show([
        'id',
        'title',
        'featuredimage'
    ]);

Obtaining:

array (
  'id' => 62,
  'title' => 'Example',
  'featuredimage' => 
  array (
    'name' => 'featuredimage',
    'filename' => 'featuredimage.jpg',
    'alt' => '',
    'caption' => '',
    'description' => '',
    'originalurl' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
    'mime' => 'image/jpeg',
    'type' => 'image',
    'subtype' => 'jpeg',
    'filesize' => 14136,
    'readablefilesize' => '14 KB',
    'size' => 'full',
    'url' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
    'width' => 800,
    'height' => 800,
    'orientation' => 'landscape',
    'ratio' => 1,
  ),
)

The featuredimage is too big; let's say that we want only url and size:

$a_malini_post
    ->show([
        'id',
        'title',
        'featuredimage' => [
            'url',
            'size'
        ]
    ]);

Now we have:

array (
  'id' => 62,
  'title' => 'Example',
  'featuredimage' => 
  array (
    'size' => 'full',
    'url' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
  ),
)

Now, let's say we also want the categories, which is an array of array, and that we only want term_id, name and slug for every category:

$a_malini_post
    ->show([
        'id',
        'title',
        'categories' => [
            '*' => [
                'term_id',
                'name',
                'slug'
            ]
        ],
        'featuredimage' => [
            'url',
            'size'
        ]
    ]);

Now we have:

array (
  'id' => 62,
  'title' => 'Example',
  'featuredimage' => 
  array (
    'size' => 'full',
    'url' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
  ),
  'categories' => 
  array (
    0 => 
    array (
      'term_id' => 5,
      'name' => 'Category Example 1',
      'slug' => 'category-example-1',
    ),
    1 => 
    array (
      'term_id' => 1,
      'name' => 'Category Example 2',
      'slug' => 'category-example-2',
    ),
    2 => 
    array (
      'term_id' => 8,
      'name' => 'Category Example 3',
      'slug' => 'category-example-3',
    ),
  ),
)

The * key tells us that the keys we are specifying are to be applied to every element of the array. We could also specify different filters for specific elements of the array; let's say that we also want the taxonomy and count but only for the first element of the categories array; we could write it this way:

$a_malini_post
    ->show([
        'id',
        'title',
        'categories' => [
            '0' => [
                'term_id',
                'name',
                'slug',
                'taxonomy',
                'count'
            ],
            '*' => [
                'term_id',
                'name',
                'slug'
            ]
        ],
        'featuredimage' => [
            'url',
            'size'
        ]
    ]);

This will apply the 0-indexed keys to the 0-indexed element of the array and use * for all the others:

array (
  'id' => 62,
  'title' => 'Example',
  'featuredimage' => 
  array (
    'size' => 'full',
    'url' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
  ),
  'categories' => 
  array (
    0 => 
    array (
      'term_id' => 5,
      'name' => 'Category Example 1',
      'slug' => 'category-example-1',
      'taxonomy' => 'my-category',
      'count' => 2,
    ),
    1 => 
    array (
      'term_id' => 1,
      'name' => 'Category Example 2',
      'slug' => 'category-example-2',
    ),
    2 => 
    array (
      'term_id' => 8,
      'name' => 'Category Example 3',
      'slug' => 'category-example-3',
    ),
  ),
)

It is also possible to quicly rename some attributes, prefixing the attribute name with an alias and a colon, like this:

$a_malini_post
    ->show([
        'the_id:id',
        'the_title:title',
        'cats:categories' => [
            '*' => [
                'id:term_id',
                'name',
                'slug'
            ]
        ],
        'image:featuredimage' => [
            'url',
            'size'
        ]
    ]);

We obtain:

array (
  'the_id' => 62,
  'the_title' => 'Example',
  'cats' => 
  array (
    0 => 
    array (
      'id' => 5,
      'name' => 'Category Example 1',
      'slug' => 'category-example-1',
    ),
    1 => 
    array (
      'id' => 1,
      'name' => 'Category Example 2',
      'slug' => 'category-example-2',
    ),
    2 => 
    array (
      'id' => 8,
      'name' => 'Category Example 3',
      'slug' => 'category-example-3',
    ),
  ),
  'image' => 
  array (
    'size' => 'full',
    'url' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
  ),
)

Lastly, we can also specify a Closure to do some data manipulation:

$a_malini_post
    ->show([
        'the_id:id' => function($value) {
            return 'The id of this post is: ' . $value;
        },
        'the_title:title',
        'cats:categories' => [
            '*' => [
                'id:term_id',
                'name',
                'slug'
            ]
        ],
        'image:featuredimage' => [
            'url' => function($value) {
                return str_replace(
                    'http://www.malini.test/',
                    '',
                    $value
                );
            },
            'size'
        ]
    ]);

And obtain:

array (
  'the_id' => 'The id of this post is: 62',
  'the_title' => 'Example',
  'cats' => 
  array (
    0 => 
    array (
      'id' => 5,
      'name' => 'Category Example 1',
      'slug' => 'category-example-1',
    ),
    1 => 
    array (
      'id' => 1,
      'name' => 'Category Example 2',
      'slug' => 'category-example-2',
    ),
    2 => 
    array (
      'id' => 8,
      'name' => 'Category Example 3',
      'slug' => 'category-example-3',
    ),
  ),
  'image' => 
  array (
    'size' => 'full',
    'url' => 'wp-content/uploads/featuredimage.jpg',
  ),
)

Array of String Notation

All the rules expressed in the section before, with the obvous exception of the one using Closures, can also be written in a compact way, through strings by splitting every nested level with a dot and every group of elements with parenthesis:

$a_malini_post
    ->show([
        'the_id:id',
        'the_title:title',
        'cats:categories.*.(id:id_term,name,slug)',
        'image:featuredimage.(url,size)'
    ]);

Results in:

array (
  'the_id' => 62,
  'the_title' => 'Example',
  'cats' => 
  array (
    0 => 
    array (
      'id' => 5,
      'name' => 'Category Example 1',
      'slug' => 'category-example-1',
    ),
    1 => 
    array (
      'id' => 1,
      'name' => 'Category Example 2',
      'slug' => 'category-example-2',
    ),
    2 => 
    array (
      'id' => 8,
      'name' => 'Category Example 3',
      'slug' => 'category-example-3',
    ),
  ),
  'image' => 
  array (
    'size' => 'full',
    'url' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
  ),
)

One String Notation

It is also possible to pass all in a single string, dividing keys with a comma, like:

$a_malini_post
    ->show('the_id:id,title,image:featuredimage.url');

array (
  'the_id' => 62,
  'title' => 'Example',
  'image' => 
  array (
    'url' => 'http://www.malini.test/wp-content/uploads/featuredimage.jpg',
  ),
)

Although, as the syntax can become quite complex, it is recommended to us this notation only when there aren't a lot of keys or you'll find yourself with monsters like this:

$a_malini_post
    ->show('the_id:id,the_title:title,cats:categories.*.(id:id_term,name,slug),image:featuredimage.(url,size)');

Explicit Nested Array Notation

All the previous notations are normalized inside Malini in the form of an associative array with name, alias, filter and children. These notations are equivalent:

// string version
$a_malini_post
    ->show([
        'image:featuredimage' => [
            'url' => function($value) {
                return str_replace(
                    'http://www.malini.test/',
                    '',
                    $value
                );
            }
        ]        
    ]);

// normalized version
$a_malini_post
    ->show([
        [
            'name' => 'featuredimage',
            'alias' => 'image',
            'filter' => null,
            'children' => [
                [
                    'name' => 'featuredimage',
                    'alias' => 'image',
                    'filter' => function($value) {
                        return str_replace(
                            'http://www.malini.test/',
                            '',
                            $value
                        );
                    },
                    'children' => []
                ]
            ]
        ]
    ]);

This is obviously quite verbose, but it is important noting that all other notations are transformed in this one before execution.