Response Component

Overview

Phalcon\Http\Response is a component that encapsulates the actual HTTP response by the application to the user. The most commonly returned payload is headers and content. Note that this is not only the actual response payload. The component acts as a constructor of the response and as an HTTP client to send the response back to the caller.

<?php

use Phalcon\Http\Response;

// Getting a response instance
$response = new Response();

$response->setStatusCode(404, 'Not Found');
$response->setContent("Sorry, the page doesn't exist");
$response->send();

The above example demonstrates how we can send a 404-page back to the user.

The component implements the Phalcon\Http\ResponseInterface, Phalcon\Di\InjectionAware and Phalcon\Events\EventsAware interfaces.

Upon instantiation, you can use the constructor to set your content, the code as well as the status if you need to.

<?php

use Phalcon\Http\Response;

// Getting a response instance
$response = new Response(
    "Sorry, the page doesn't exist",
    404, 
    'Not Found'
);

$response->send();

After we set up all the necessary information, we can call the send() method to send the response back. There are however instances that due to errors or application workflow, that our response might have already been sent back to the caller. Calling send() will therefore introduce the dreaded headers already sent message on screen.

To avoid this we can use the isSent() method to check if the response has already sent the data back to the caller.

<?php

use Phalcon\Http\Response;

// Getting a response instance
$response = new Response(
    "Sorry, the page doesn't exist",
    404, 
    'Not Found'
);

if (true !== $response->isSent()) {
    $response->send();
}

Getters

The Phalcon\Http\Response offers several getters, allowing you to retrieve information regarding the response based on your application needs. The following getters are available:

Content

There are a number of methods available that allow you to set the content or body of the response. setContent() is the most frequently used method.

<?php

use Phalcon\Http\Response;

// Getting a response instance
$response = new Response();

$response->setContent("<h1>Hello World!</h1>");
$response->send();

You can also accompany that with setContentLength() which allows you to set the length or number of bytes that the response has, as well as the setContentType() which tells the recipient what type the data is. This is especially handy to use, because the recipient (often a browser) will treat different types of content differently.

Examples

PDF File:

<?php

use Phalcon\Http\Response;

$response = new Response();
$contents = file_get_contents('/app/storage/files/invoice.pdf');

$response
    ->setContent($contents)
    ->setContentType('application/pdf')
    ->setHeader(
        'Content-Disposition', 
        "attachment; filename='downloaded.pdf'"
    )
    ->send()
;

JSON:

<?php

use Phalcon\Http\Response;

$response = new Response();
$contents = [
    'invoice' => [
        'id'    => 12345,
        'name'  => 'invoice.pdf',
        'date'  => '2019-01-01 01:02:03',
        'owner' => 'admin',
    ]   
];

$response
    ->setJsonContent($contents)
    ->send();

Note that in the above JSON example we used the setJsonContent() instead of the setContent(). setJsonContent() allows us to send a payload to the method, and it will automatically set the content type header to application/json and call json_encode on the payload. You can also pass options and depth as the last two parameters of the method, which will be used by json_encode internally:

<?php

use Phalcon\Http\Response;

$response = new Response();
$contents = [
    'invoice' => [
        'id'    => 12345,
        'name'  => 'invoice.pdf',
        'date'  => '2019-01-01 01:02:03',
        'owner' => 'admin',
    ]   
];

$response
    ->setJsonContent($contents, JSON_PRETTY_PRINT, 512)
    ->send();

For applications that need to add content to the response based on certain criteria (various if statements for instance), you can use the appendContent() method, which will just add the new content to the existing one stored in the component.

Headers

The HTTP headers are a very important part of the HTTP response, since they contain information regarding the response. Information such as the status, content type, cache etc. is wrapped in the headers. The Phalcon\Http\Response object offers methods that allow you to manipulate those headers based on your application workflow and needs.

Setting headers using the response object only requires you to call the setHeader() method.

<?php

use Phalcon\Http\Response;

$response = new Response();

$response
    ->setHeader(
        'Content-Type', 
        'application/pdf'
    )
    ->setHeader(
        'Content-Disposition', 
        "attachment; filename='downloaded.pdf'"
    )
;

$response->setRawHeader('HTTP/1.1 200 OK');

You can also use the setRawHeader() method to set the header using the raw syntax.

You can check whether a header exists using hasHeader(), remove it using removeHeader() method, or clear the headers completely using resetHeaders().

<?php

use Phalcon\Http\Response;

$response = new Response();

$response->setHeader(
    'Content-Type', 
    'application/pdf'
);

if (true === $response->hasHeader('Content-Type')) {
    $response->removeHeader('Content-Type');
}

$response->resetHeaders();

If you need to, you can also send only the headers back to the caller using sendHeaders()

<?php

use Phalcon\Http\Response;

$response = new Response();

$response->setHeader(
    'Content-Type', 
    'application/pdf'
);

$response->sendHeaders();

The Phalcon\Http\Response object also wraps the Phalcon\Http\Response\Headers collection object automatically, which offers more methods for header manipulation. You can instantiate a Phalcon\Http\Response\Headers object or any object that implements the Phalcon\Http\Response\HeadersInterface and then set it in the response using setHeaders():

<?php

use Phalcon\Http\Response;
use Phalcon\Http\Response\Headers;

$response = new Response();
$headers  = new Headers();

$headers
    ->set(
        'Content-Type', 
        'application/pdf'
    )
    ->set(
        'Content-Disposition', 
        "attachment; filename='downloaded.pdf'"
    )
;

$response->setHeaders($headers);

The Phalcon\Http\Response\Headers object offers the following methods, allowing you to manipulate headers:

<?php

use Phalcon\Http\Response;

$response = new Response();
$headers  = $response->getHeaders();

$headers->set('Content-Type', 'application/json');

$response->setHeaders($headers);

Cookies

The Phalcon\Http\Response offers a collection to store and manipulate cookies. You can then send those cookies back with the response.

To set up cookies you will need to instantiate a Phalcon\Http\Response\Cookies object or any object that implements the Phalcon\Http\Response\CookiesInterface.

<?php

use Phalcon\Http\Response;
use Phalcon\Http\Response\Cookies;

$response = new Response();
$cookies  = new Cookies();

$response->setCookies($cookies);

To get the cookies set by the user you can use the getCookies() method on the Phalcon\Http\Response object. The method returns a Phalcon\Http\Response\Cookies collection object. You can set the cookies in the response object using the setCookies(), as shown above, and then use sendCookies() to send them back to the caller.

SameSite

If you are using PHP 7.3, or later you can set the SameSite as an element to the options array (last parameter of the constructor) or by using setOptions(). It is your responsibility to assign a valid value for SameSite (such as Strict, Lax etc.)

<?php

use Phalcon\Http\Cookie;

$cookie  = new Cookie(
    'my-cookie',                   // name
    1234,                          // value
    time() + 86400,                // expires
    "/",                           // path
    true,                          // secure
    ".phalcon.io",                 // domain
    true,                          // httponly
    [                              // options
        "samesite" => "Strict",    // 
    ]                              // 
);

Encryption

The cookies collection is automatically registered as part of the response service that is registered in the DI container. By default, cookies are automatically encrypted prior to sending them to the client and are decrypted when retrieved from the user.

In order to set the sign key used to generate a message you can either set it in the constructor:

<?php 

use Phalcon\Http\Response;
use Phalcon\Http\Response\Cookies;

$response = new Response();
$signKey  = "#1dj8$=dp?.ak//j1V$~%*0XaK\xb1\x8d\xa9\x98\x054t7w!z%C*F-Jk\x98\x05\\\x5c";

$cookies  = new Cookies(true, $signKey);

$response->setCookies($cookies);

or if you want you can use the setSignKey() method:

<?php 

use Phalcon\Http\Response;
use Phalcon\Http\Response\Cookies;

$response = new Response();
$signKey  = "#1dj8$=dp?.ak//j1V$~%*0XaK\xb1\x8d\xa9\x98\x054t7w!z%C*F-Jk\x98\x05\\\x5c";

$cookies  = new Cookies();

$cookies->setSignKey($signKey);

$response->setCookies($cookies);

Methods

There are several methods available to help you retrieve data from the component:

set(): CookiesInterface accepts the following parameters:

<?php

use Phalcon\Http\Response\Cookies;

$now = new DateTimeImmutable();
$tomorrow = $now->modify('tomorrow');

$cookies = new Cookies();
$cookies->set(
    'remember-me',
    json_encode(
        [
            'user_id' => 1,
        ]
    ),
    (int) $tomorrow->format('U')
);

Files

The setFileToSend() helper method allows you to easily set a file to be sent back to the caller using the response object. This is particularly useful when we want to introduce download files functionality in our application.

The method accepts the following parameters:

<?php

use Phalcon\Http\Response;

$response = new Response();
$contents = file_get_contents();

$response
    ->setFileToSend(
        '/app/storage/files/invoice.pdf',
        'downloaded.pdf',
        true
    )
    ->send()
;

In the above example, we set where the file lives (/app/storage/files/invoice.pdf). The second parameter will set the name of the file (when downloaded by the browser) to downloaded.pdf. The third parameter instructs the component to set the relevant headers for the download to happen. These are:

• Content-Description: File Transfer
• Content-Type: application/octet-stream"
• Content-Disposition: attachment; filename=downloaded.pdf;"
• Content-Transfer-Encoding: binary"

When calling send(), the file will be read using readfile() and the contents will be sent back to the caller.

Redirections

With Phalcon\Http\Response you can also execute HTTP redirections.

Examples

Redirect to the default URI

<?php 

use Phalcon\Http\Response;

$response = new Response();

$response->redirect();

Redirect to posts/index

<?php 

use Phalcon\Http\Response;

$response = new Response();

$response->redirect('posts/index');

Redirect to an external URI (note the second parameter set to true)

<?php 

use Phalcon\Http\Response;

$response = new Response();

$response->redirect('https://en.wikipedia.org', true);

Redirect to an external URI with an HTTP status code, handy for permanent or temporary redirections.

<?php 

use Phalcon\Http\Response;

$response = new Response();

$response->redirect('https://www.example.com/new-location', true, 301);

All internal URIs are generated using the url service (by default Phalcon\Mvc\Url). This example demonstrates how you can redirect using a route you have defined in your application:

<?php 

use Phalcon\Http\Response;

$response = new Response();

return $response->redirect(
    [
        'for'        => 'index-lang',
        'lang'       => 'jp',
        'controller' => 'index',
    ]
);

HTTP Cache

One of the easiest ways to improve the performance in your applications and reduce the traffic is using HTTP Cache. The Phalcon\Http\Response object exposes methods that help with this task.

HTTP Cache is implemented by setting certain headers in the response. The cache is set (using the headers) upon the first visit of the user to our application. The following headers help with HTTP Cache:

Expires

The expiration date is one of the easiest and most effective ways to cache a page in the client (browser). Starting from the current date we add the amount of time the page will be stored in the browser cache. The browser will not request a copy of this page until the time expires.

<?php

use Phalcon\Http\Response;

$response   = new Response();
$expiryDate = new DateTime();

$expiryDate->modify('+2 months');

$response->setExpires($expiryDate);

The Phalcon\Http\Response component automatically formats the date to the GMT timezone as expected in an Expires header. Irrespective of the timezone of your application, the component converts the time first to UTC and then sets the Expires header. Setting the expiry with a date in the past will instruct the browser to always request a fresh copy of the page. This is particularly useful if we want to force the client browsers to request a new copy of our page.

<?php

use Phalcon\Http\Response;

$response   = new Response();
$expiryDate = new DateTime();

$expiryDate->modify('-10 minutes');

$response->setExpires($expiryDate);

Cache-Control

This header provides a better to cache the pages served. We simply specify a time in seconds, instructing the browser that our content is cached for that amount of time.

<?php

use Phalcon\Http\Response;

$response = new Response();

$response->setHeader(
    'Cache-Control', 
    'max-age=86400'
);

If you do not want to call the setHeaders(), a utility method is available to you setCache() which sets the Cache-Control for you.

<?php

use Phalcon\Http\Response;

$response = new Response();

// $response->setHeader('Cache-Control', 'max-age=86400');
$response->setCache(86400);

To invalidate the above or to instruct the browser to always request a fresh copy of the page, we can do the following:

<?php

use Phalcon\Http\Response;

$response = new Response();

$response->setHeader(
    'Cache-Control', 
    'private, max-age=0, must-revalidate'
);

Last-Modified

You can also use the setLastModified() method to instruct the browser on when the page was last modified. This header is less accurate than the E-Tag header but can be used as a fallback mechanism.

<?php

use Phalcon\Http\Response;

$response   = new Response();
$expiryDate = new DateTime();

$expiryDate->modify('+2 months');

$response->setLastModified($expiryDate);

The Phalcon\Http\Response component automatically formats the date to the GMT timezone as expected in an Last-Modified header. Irrespective of the timezone of your application, the component converts the time first to UTC and then sets the Last-Modified header. Setting the expiry with a date in the past will instruct the browser to always request a fresh copy of the page. This is particularly useful if we want to force the client browsers to request a new copy of our page.

<?php

use Phalcon\Http\Response;

$response   = new Response();
$expiryDate = new DateTime();

$expiryDate->modify('-10 minutes');

$response->setLastModified($expiryDate);

E-Tag

An entity-tag or E-tag is a unique identifier that helps the browser identify if the page has changed or not between requests. The identifier is usually calculated taking into account the last modified date, the contents and other identifying parameters for the page:

<?php

use MyApp\Models\Invoices;
use Phalcon\Http\Response;

$response = new Response();

$mostRecentDate = Invoices::maximum(
    [
        'column' => 'inv_created_date',
    ]
);

$eTag = sha1($mostRecentDate);

$response->setHeader('E-Tag', $eTag);

Not Modified - 304

Generating a not-modified response also helps with caching, by instructing the browser that the contents have not been modified, and therefore the locally cached copy of the data on the browser should be used.

<?php

use MyApp\Models\Invoices;
use Phalcon\Http\Response;

$response = new Response();

$response->setNotModified();

Dependency Injection

The Phalcon\Http\Response object implements the Phalcon\Di\InjectionAwareInterface interface. As a result, the DI container is available and can be retrieved using the getDI() method. A container can also be set using the setDI() method.

If you have used the Phalcon\Di\FactoryDefault DI container for your application, the service is already registered for you. You can access it using the response name. The example below shows the usage in a controller

<?php

use Phalcon\Http\Response;
use Phalcon\Mvc\Controller;

/**
 * @property Response $response
 */
class PostsController extends Controller
{
    public function uploadAction()
    {
        return $this
            ->response
            ->setStatusCode(404, 'Not Found')
            ->setContent("Sorry, the page does not exist")
            ->send();
    }
}

Events

The Phalcon\Http\Response object implements the Phalcon\Events\EventsAware interfaces. As a result getEventsManager() and setEventsManager() are available for you to use.