Media Views

Class MediaView

Media views allow you to send binary files to the user. For example, you may wish to have a directory of
files outside of the webroot to prevent users from direct linking them. You can use the Media view to pull
the file from a special folder within /app/, allowing you to perform authentication before delivering the file
to the user.

To use the Media view, you need to tell your controller to use the MediaView class instead of the default
View class. After that, just pass in additional parameters to specify where your file is located:

class ExampleController extends AppController {
public function download() {
$this->viewClass = 'Media';
// Download app/outside_webroot_dir/example.zip
$params = array(
'id' => 'example.zip',
'name' => 'example',
'download' => true,
'extension' => 'zip',
'path' => APP . 'outside_webroot_dir' . DS
);
$this->set($params);
}
}

Here’s an example of rendering a file whose mime type is not included in the MediaView’s $mimeType
array. We are also using a relative path which will default to your app/webroot folder:

public function download() {
$this->viewClass = 'Media';
// Render app/webroot/files/example.docx
$params = array(
'id' => 'example.docx',
'name' => 'example',
'extension' => 'docx',
'mimeType' => array(
'docx' => 'application/vnd.openxmlformats-officedocument' .
'.wordprocessingml.document'
),
'path' => 'files' . DS
);
$this->set($params);
}

Settable Parameters

id The ID is the file name as it resides on the file server including the file extension.
name The name allows you to specify an alternate file name to be sent to the user. Specify the name without
the file extension.
download A boolean value indicating whether headers should be set to force download.
extension The file extension. This is matched against an internal list of acceptable mime types. If the
mime type specified is not in the list (or set in the mimeType parameter array), the file will not be
downloaded.
path The folder name, including the final directory separator. The path should be absolute but can be
relative to the app/webroot folder.
mimeType An array with additional mime types to be merged with MediaView internal list of acceptable
mime types.
cache A boolean or integer value - If set to true it will allow browsers to cache the file (defaults to false if
not set); otherwise set it to the number of seconds in the future for when the cache should expire.

JSON and XML views

New in CakePHP 2.1 are two new view classes. The XmlView and JsonView let you easily create XML
and JSON responses, and integrate with the RequestHandlerComponent.

By enabling RequestHandlerComponent in your application, and enabling support for the xml and
or json extensions, you can automatically leverage the new view classes. XmlView and JsonView will
be referred to as data views for the rest of this page.

There are two ways you can generate data views. The first is by using the _serialize key, and the second
is by creating normal view files.

Enabling data views in your application

Before you can use the data view classes, you’ll need to do a bit of setup:

1. Enable the json and or xml extensions with Router::parseExtensions(). This will enableRouter to handle multiple extensions.
2. Add the RequestHandlerComponent to your controller’s list of components. This will enableautomatic view class switching on content types. You can also set the component up with the viewClassMap setting, to map types to your custom classes and/or map other data types.

New in version 2.3: RequestHandlerComponent::viewClassMap() method has been added to
map types to viewClasses. The viewClassMap setting will not work on earlier versions.

After adding Router::parseExtensions('json'); to your routes file, CakePHP will automatically
switch view classes when a request is done with the .json extension, or the Accept header is
application/json.

Using data views with the serialize key

The _serialize key is a special view variable that indicates which other view variable(s) should be
serialized when using a data view. This lets you skip defining view files for your controller actions if you
don’t need to do any custom formatting before your data is converted into json/xml. If you need to do any formatting or manipulation of your view variables before generating the response, you should use view files. The value of _serialize can be either a string or an array of view variables to serialize:

class PostsController extends AppController {
public $components = array('RequestHandler');
public function index() {
$this->set('posts', $this->Paginator->paginate());
$this->set('_serialize', array('posts'));
}
}

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

class PostsController extends AppController {
public $components = array('RequestHandler');
public function index() {
// some code that created $posts and $comments
$this->set(compact('posts', 'comments'));
$this->set('_serialize', array('posts', 'comments'));
}
}

Defining _serialize as an array has the added benefit of automatically appending a top-level
<response> element when using XmlView. If you use a string value for _serialize and XmlView,

make sure that your view variable has a single top-level element. Without a single top-level element the Xml will fail to generate.

Using a data view with view files

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

// Controller code
class PostsController extends AppController {
public function index() {
$this->set(compact('posts', 'comments'));
}
}
// View code - app/View/Posts/json/index.ctp
foreach ($posts as &$post) {
unset($post['Post']['generated_html']);
}
echo json_encode(compact('posts', 'comments'));

class XmlView
A view class for generating Xml view data. See above for how you can use XmlView in your application.
By default when using _serialize the XmlView will wrap your serialized view variables with a
<response> node. You can set a custom name for this node using the _rootNode view variable.
New in version 2.3: The _rootNode feature was added.
New in version 2.6: The XmlView class supports the _xmlOptions variable that allows you to
customize the options used to generate XML, e.g. tags vs attributes.

class JsonView
A view class for generating Json view data. See above for how you can use JsonView in your application.
New in version 2.6: JsonView now supports the _jsonOptions view variable. This allows you to
configure the bit-mask options used when generating JSON.