MixerAPI CollectionView

A simple Collection View for displaying configurable pagination meta data in JSON or XML collection responses. Read more at MixerAPI.com.

Installation

You can skip this step if MixerAPI is installed.

composer require mixerapi/collection-view
bin/cake plugin load MixerApi/CollectionView

Alternatively after composer installing you can manually load the plugin in your Application:

# src/Application.php
public function bootstrap(): void
{
    // other logic...
    $this->addPlugin('MixerApi/CollectionView');
}

Setup

Your controllers must be using the RequestHandler component. This is typically loaded in your AppController.

# src/Controller/AppController.php
public function initialize(): void
{
    parent::initialize();
    $this->loadComponent('RequestHandler');
    // other logic...
}

Usage

That's it, you're done. Perform application/xml or application/json requests as normal. You may also request by .xml or .json extensions (assuming you've enabled them in your config/routes.php). This plugin will only modify collections (e.g. controller::index action) requests, not item (e.g. controller::view action) requests.

JSON sample

{
    "collection": {
        "url": "/films?page=3&direction=desc",
        "count": 20,
        "total": 1000,
        "pages": 50,
        "next": "/films?page=4",
        "prev": "/films?page=2",
        "first": "/films",
        "last": "/films?page=50"
    },
    "data": [
        {
            "id": 1,
            "first_name": "PENELOPE",
            "last_name": "GUINESS",
            "modified": "2006-02-15T04:34:33+00:00",
            "films": [
                {
                    "id": 1,
                    "title": "ACADEMY DINOSAUR",
                    "description": "A Epic Drama of a Feminist And a Mad Scientist who must Battle a Teacher in The Canadian Rockies",
                    "release_year": "2006",
                    "language_id": 1,
                    "rental_duration": 6,
                    "length": 86,
                    "rating": "PG",
                    "special_features": "Deleted Scenes,Behind the Scenes",
                    "modified": "2006-02-15T05:03:42+00:00"
                }
            ]
        }
    ]
}

XML sample

<response>
  <collection>
    <url>/films?page=3&amp;direction=desc</url>
    <count>20</count>
    <total>1000</total>
    <pages>50</pages>
    <next>/films?page=4</next>
    <prev>/films?page=2</prev>
    <first>/films</first>
    <last>/films?page=50</last>
  </collection>
  <data>
    <id>1</id>
    <first_name>PENELOPE</first_name>
    <last_name>GUINESS</last_name>
    <modified>2/15/06, 4:34 AM</modified>
    <films>
      <id>1</id>
      <title>ACADEMY DINOSAUR</title>
      <description>A Epic Drama of a Feminist And a Mad Scientist who must Battle a Teacher in The Canadian Rockies</description>
      <release_year>2006</release_year>
      <language_id>1</language_id>
      <rental_duration>6</rental_duration>
      <length>86</length>
      <rating>PG</rating>
      <special_features>Deleted Scenes,Behind the Scenes</special_features>
      <modified>2/15/06, 5:03 AM</modified>
    </films>
  </data>
</response>

Configuration

This is optional. You can alter the names of the response keys, simply create a config/collection_view.php file. Using the example below we can change the collection key to pagination, data to items, and alter some key names within our new pagination object. Just keep the mapped items {{names}} as-is.

# config/collection_view.php
return [
    'CollectionView' => [
        'pagination' => '{{collection}}', // array that holds pagination data
        'pagination.url' => '{{url}}', // url of current page
        'pagination.count' => '{{count}}', // items on the page
        'pagination.total' => '{{total}}', // total database records
        'pagination.pages' => '{{pages}}', // total pages
        'pagination.next' => '{{next}}', // next page url
        'pagination.prev' => '{{prev}}', // previous page url
        'pagination.first' => '{{first}}', // first page url
        'pagination.last' => '{{last}}', // last page url
        'items' => '{{data}}', // the collection of data
    ]
];