JSON and XML views

JSON and XML views

The JsonView and XmlViewlet you create JSON and XML responses, and integrate with theCake\Controller\Component\RequestHandlerComponent.

By enabling RequestHandlerComponent in your application, and enablingsupport for the json and/or xml extensions, you can automaticallyleverage the new view classes. JsonView and XmlView will be referred toas data views for the rest of this page.

There are two ways you can generate data views. The first is by using theserialize option, and the second is by creating normal template files.

Enabling Data Views in Your Application

Before you can use the data view classes, you’ll first need to load theCake\Controller\Component\RequestHandlerComponent in yourcontroller:

public function initialize(): void
{
    ...
    $this->loadComponent('RequestHandler');
}

This can be done in your AppController and will enable automatic view classswitching on content types. You can also set the component up with theviewClassMap setting, to map types to your custom classes and/or map otherdata types.

You can optionally enable the json and/or xml extensions withRouting File Extensions. This will allow you to access the JSON, XML orany other special format views by using a custom URL ending with the name of theresponse type as a file extension such as http://example.com/articles.json.

By default, when not enabling Routing File Extensions, the request, the Acceptheader is used for, selecting which type of format should be rendered to theuser. An example Accept format that is used to render JSON responses isapplication/json.

Using Data Views with the Serialize Key

The serialize option indicates which view variable(s) should beserialized when using a data view. This lets you skip defining template filesfor your controller actions if you don’t need to do any custom formatting beforeyour data is converted into json/xml.

If you need to do any formatting or manipulation of your view variables beforegenerating the response, you should use template files. The value ofserialize can be either a string or an array of view variables toserialize:

namespace App\Controller;
 
class ArticlesController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('RequestHandler');
    }
 
    public function index()
    {
        // Set the view vars that have to be serialized.
        $this->set('articles', $this->paginate());
        // Specify which view vars JsonView should serialize.
        $this->viewBuilder()->setOption('serialize', 'articles');
    }
}

You can also define serialize as an array of view variables to combine:

namespace App\Controller;
 
class ArticlesController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('RequestHandler');
    }
 
    public function index()
    {
        // Some code that created $articles and $comments
 
        // Set the view vars that have to be serialized.
        $this->set(compact('articles', 'comments'));
 
        // Specify which view vars JsonView should serialize.
        $this->viewBuilder()->setOption('serialize', ['articles', 'comments']);
    }
}

Defining serialize as an array has added the benefit of automaticallyappending a top-level <response> element when using XmlView.If you use a string value for serialize and XmlView, make sure that yourview variable has a single top-level element. Without a single top-levelelement the Xml will fail to generate.

Using a Data View with Template Files

You should use template files if you need to do some manipulation of your viewcontent before creating the final output. For example if we had articles, that hada field containing generated HTML, we would probably want to omit that from aJSON response. This is a situation where a view file would be useful:

// Controller code
class ArticlesController extends AppController
{
    public function index()
    {
        $articles = $this->paginate('Articles');
        $this->set(compact('articles'));
    }
}
 
// View code - templates/Articles/json/index.php
foreach ($articles as &$article) {
    unset($article->generated_html);
}
echo json_encode(compact('articles'));

You can do more complex manipulations, or use helpers to do formatting as well.The data view classes don’t support layouts. They assume that the view file willoutput the serialized content.

Creating XML Views

class XmlView

By default when using serialize the XmlView will wrap your serializedview variables with a <response> node. You can set a custom name forthis node using the rootNode option.

The XmlView class supports the xmlOptions option that allows you tocustomize the options used to generate XML, e.g. tags vs attributes.

An example of using XmlView would be to generate a sitemap.xml. This document type requires that youchange _rootNode and set attributes. Attributes are defined using the @prefix:

public function sitemap()
{
    $pages = $this->Pages->find();
    $urls = [];
    foreach ($pages as $page) {
        $urls[] = [
            'loc' => Router::url(['controller' => 'Pages', 'action' => 'view', $page->slug, '_full' => true]),
            'lastmod' => $page->modified->format('Y-m-d'),
            'changefreq' => 'daily',
            'priority' => '0.5'
        ];
    }
 
    // Define a custom root node in the generated document.
    $this->viewBuilder()
        ->setOption('rootNode', 'urlset')
        ->setOption('serialize', ['@xmlns', 'url']);
    $this->set([
        // Define an attribute on the root node.
        '@xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9',
        'url' => $urls
    ]);
}

Creating JSON Views

class JsonView

The JsonView class supports the _jsonOptions variable that allows you tocustomize the bit-mask used to generate JSON. See thejson_encode documentation for the validvalues of this option.

For example, to serialize validation error output of CakePHP entities in a consistent form of JSON do:

// In your controller's action when saving failed
$this->set('errors', $articles->errors());
$this->viewBuilder()
    ->setOption('serialize', ['errors'])
    ->setOption('jsonOptions', JSON_FORCE_OBJECT);

JSONP Responses

When using JsonView you can use the special view variable _jsonp toenable returning a JSONP response. Setting it to true makes the view classcheck if query string parameter named “callback” is set and if so wrap the jsonresponse in the function name provided. If you want to use a custom query stringparameter name instead of “callback” set _jsonp to required name instead oftrue.

Example Usage

While the RequestHandlerComponent can automatically set the view basedon the request content-type or extension, you could also handle viewmappings in your controller:

// src/Controller/VideosController.php
namespace App\Controller;
 
use App\Controller\AppController;
use Cake\Http\Exception\NotFoundException;
 
class VideosController extends AppController
{
    public function export($format = '')
    {
        $format = strtolower($format);
 
        // Format to view mapping
        $formats = [
          'xml' => 'Xml',
          'json' => 'Json',
        ];
 
        // Error on unknown type
        if (!isset($formats[$format])) {
            throw new NotFoundException(__('Unknown format.'));
        }
 
        // Set Out Format View
        $this->viewBuilder()->className($formats[$format]);
 
        // Get data
        $videos = $this->Videos->find('latest');
 
        // Set Data View
        $this->set(compact('videos'));
        $this->viewBuilder()->setOption('serialize', ['videos']);
 
        // Set Force Download
        return $this->response->withDownload('report-' . date('YmdHis') . '.' . $format);
    }
}