How to output custom HTTP body contents with CakePHP 3.4? Echoing causes “Unable to emit headers” error

Question 1

Using CakePHP 3.4, PHP 7.0.

I'm attempting to do a really simple controller method to output some JSON. It is outputting "Cannot modify headers...".

public function test() {
    $this->autoRender = false;
    echo json_encode(['method' => __METHOD__, 'class' => get_called_class()]);
}

Browser output

{"method":"App\Controller\SomeController::test", "class":"App\Controller\SomeController"}

Warning (512): Unable to emit headers. Headers sent in file=...
Warning (2): Cannot modify header information - headers already sent by (output started at ...)
Warning (2): Cannot modify header information - headers already sent by (output started at ...)

I fully understand why PHP complains about this. The question is why does CakePHP complain and what can I do about it?

It should be noted that CakePHP 2.x allowed this.

Question 2

Controllers should never echo data! Echoing data can lead to all kinds of problems, from the data not being recognized in the test environment, to headers not being able to be sent, and even data being cut off.

Doing it that way was already wrong in CakePHP 2.x, even though it might have worked in some, maybe even most situations. With the introduction of the new HTTP stack, CakePHP now explicitly checks for sent headers before echoing the response, and will trigger an error accordingly.

The proper way to send custom output was to configure and return the response object, or to use serialized views, and it's still the same in 3.x.

Quote from the docs:

Controller actions generally use Controller::set() to create a context that View uses to render the view layer. Because of the conventions that CakePHP uses, you don’t need to create and render the view manually. Instead, once a controller action has completed, CakePHP will handle rendering and delivering the View.

If for some reason you’d like to skip the default behavior, you can return a CakeNetworkResponse object from the action with the fully created response.

^{* As of 3.4 that would be CakeHttpResponse}

Cookbook > Controllers > Controller Actions

Configure the response

Using the PSR-7 compliant interface

$content = json_encode(['method' => __METHOD__, 'class' => get_called_class()]);

$this->response = $this->response->withStringBody($content);
$this->response = $this->response->withType('json');
// ...

return $this->response;

The PSR-7 compliant interface uses immutable methods, hence the utilization of the return value of withStringBody() and withType(). In CakePHP < 3.4.3, withStringBody() is not available, and you can instead directly write to the body stream, which will not change the state of the response object:

$this->response->getBody()->write($content);

Using the deprecated interface

$content = json_encode(['method' => __METHOD__, 'class' => get_called_class()]);

$this->response->body($content);
$this->response->type('json');
// ...

return $this->response;

Use a serialized view

$content = ['method' => __METHOD__, 'class' => get_called_class()];

$this->set('content', $content);
$this->set('_serialize', 'content');

This requires to also use the request handler component, and to enable extensing parsing and using correponsing URLs with .json appended, or to send a proper request with a application/json accept header.

def nexmo_sendsms(api_key, api_secret, sender, receiver, body):
    """
    Sends a message using Nexmo.

    :param api_key: Nexmo provided api key
    :param api_secret: Nexmo provided secrety key
    :param sender: The number used to send the message
    :param receiver: The number the message is addressed to
    :param body: The message body
    :return: Returns the msgid received back from Nexmo after message has been sent.
    """


    msg = {
        'api_key': api_key,
        'api_secret': api_secret,
        'from': sender,
        'to': receiver,
        'text': body
    }
    nexmo_url = 'https://rest.nexmo.com/sms/json'
    data = urllib.parse.urlencode(msg)
    binary_data = data.encode('utf8')
    req = urllib.request.Request(nexmo_url, binary_data)
    response = urllib.request.urlopen(req)
    result = json.loads(response.readall().decode('utf-8'))
    return result['messages'][0]['message-id']

Question 4

http://api.cakephp.org/2.4/source-class-Controller.html#209-214

Set the Controller::$ext property in your app controller to "tpl" and your're done.

Searching before asking is also always a good idea, see CakePHP View change extension

Question 5

It's probably not possible without tradeoffs. Next.js has Automatic Static Optimization, so pages that can be statically exported will be exported to plain .html files. And .html files require no code execution on a server so there is no place to add a custom HTTP header.

Alternatively, you could add custom HTTP headers on every response with getServerSideProps in _app.js:

export async function getServerSideProps(context) {

  // set HTTP header
  context.res.setHeader('Content-Type', 'application/json')

  return {
    props: {}, // will be passed to the page component as props
  }
}

But having getServerSideProps would disable static optimization as all pages will be only server-side rendered.

Server-side Rendering

Question 6

I found a way. It actually wasn't hard at all, in the end. When running through some requests with my debugger, I noticed that onEndRequest() does get called for Ajax requests too.

The onEndRequest() method was already overriden in our custom RequestCycle implementation for other purposes (transaction commit), so I just moved the code that sets the header there from getWebResponse().

@Override
protected void onEndRequest() {
    super.onEndRequest();
    ((WebResponse) response).setHeader("X-custom", "..." );
    // ...
}

Perhaps the only non-obvious thing here was that I needed to cast response into WebResponse (when the field's type is Response) to be able to call setHeader().

This could have been done in a normal Java EE filter too, by setting the header after chain.doFilter() call (see my second comment on the question). I didn't choose that because 1) it wasn't clear to me how to wire up data access there and 2) I don't want extra moving parts if I can avoid it. We already use our RequestCycle subclass for HTTP header related things and this fits in nicely. In fact, this change simplified that class, as there's no reason to override getWebResponse() anymore!

How to output custom HTTP body contents with CakePHP 3.4? Echoing causes “Unable to emit headers” error

Answers

Configure the response

Using the PSR-7 compliant interface

Using the deprecated interface

Use a serialized view

See also

php,cakephp,httpresponse,cakephp-3.x,cakephp-3.4