Response Component

    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 a HTTP client to send the response back to the caller. You can always use the for a PSR-7 compatible response and use a client such as Guzzle to send it back to the caller.

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

    The component implements the Phalcon\Http\ResponseInterface, 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.

    3. use Phalcon\Http\Response;
    5. // Getting a response instance
    6. $response = new Response(
    7.     "Sorry, the page doesn't exist",
    8.     404, 
    9.     'Not Found'
    10. );
    12. $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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. // Getting a response instance
    6. $response = new Response(
    7.     "Sorry, the page doesn't exist",
    8.     404, 
    9.     'Not Found'
    10. );
    12. if (true !== $response->isSent()) {
    13.     $response->send();
    14. }

    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:

    • getContent(): string - Returns the HTTP response body.
    • getHeaders(): HeadersInterface - Returns the headers object, containing headers set by the user.
    • getReasonPhrase(): string | null - Returns the reason phrase (e.g. Not Found). The text returned is the one specified in the document.
    • getStatusCode(): int | null - Returns the status code (e.g. 200).

    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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. // Getting a response instance
    6. $response = new Response();
    8. $response->setContent("<h1>Hello World!</h1>");
    9. $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:

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    6. $contents = file_get_contents('/app/storage/files/invoice.pdf');
    8. $response
    9.     ->setContent($contents)
    10.     ->setContentType('application/pdf')
    11.     ->setHeader(
    12.         'Content-Disposition', 
    13.         "attachment; filename='downloaded.pdf'"
    14.     )
    15.     ->send()
    16. ;

    JSON:

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    6. $contents = [
    7.     'invoice' => [
    8.         'id'    => 12345,
    9.         'name'  => 'invoice.pdf',
    10.         'date'  => '2019-01-01 01:02:03',
    11.         'owner' => 'admin',
    12.     ]   
    13. ];
    15. $response
    16.     ->setJsonContent($contents)
    17.     ->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 internally:

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    6. $contents = [
    7.     'invoice' => [
    8.         'id'    => 12345,
    9.         'name'  => 'invoice.pdf',
    10.         'date'  => '2019-01-01 01:02:03',
    11.         'owner' => 'admin',
    12.     ]   
    13. ];
    15. $response
    16.     ->setJsonContent($contents, JSON_PRETTY_PRINT, 512)
    17.     ->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.

    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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    7. $response
    8.     ->setHeader(
    9.         'Content-Type', 
    10.         'application/pdf'
    11.     )
    12.     ->setHeader(
    13.         'Content-Disposition', 
    14.         "attachment; filename='downloaded.pdf'"
    15.     )
    16. ;
    18. $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().

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    7. $response->setHeader(
    8.     'Content-Type', 
    9.     'application/pdf'
    10. );
    11. if (true === $response->hasHeader('Content-Type')) {
    12.     $response->removeHeader('Content-Type');
    13. }
    15. $response->resetHeaders();
    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    8.     'Content-Type', 
    9.     'application/pdf'
    10. );
    12. $response->sendHeaders();

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

    Note that using setHeaders() merges the passed headers with the ones present in the response object already. The method will not clear the headers before setting them. To clear the headers you need to call reset() first (or resetHeaders() on the response object).

    The object offers the following methods, allowing you to manipulate headers:

    • get( string $name ): string | bool - Gets a header value from the object
    • has( string $name ): bool - Sets a header to be sent at the end of the request
    • remove( string $header ) - Removes a header to be sent at the end of the request
    • reset() - Resets all headers
    • send(): bool - Sends the headers to the client
    • set( string $name, string $value ) - Sets a header to be sent at the end of the request
    • setRaw( string $header ) Sets a raw header to be sent at the end of the request
    • toArray(): array - Returns the current headers as an array
    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    6. $headers  = $response->getHeaders();
    8. $headers->set('Content-Type', 'application/json');
    10. $response->setHeaders($headers);

    Cookies

    The 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 .

    1. <?php
    3. use Phalcon\Http\Response;
    4. use Phalcon\Http\Response\Cookies;
    6. $response = new Response();
    7. $cookies  = new Cookies();
    9. $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 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.

    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:

    1. <?php 
    3. use Phalcon\Http\Response;
    4. use Phalcon\Http\Response\Cookies;
    6. $response = new Response();
    7. $signKey  = "#1dj8$=dp?.ak//j1V$~%*0XaK\xb1\x8d\xa9\x98\x054t7w!z%C*F-Jk\x98\x05\\\x5c";
    9. $cookies  = new Cookies(true, $signKey);
    11. $response->setCookies($cookies);

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

    1. <?php 
    3. use Phalcon\Http\Response;
    4. use Phalcon\Http\Response\Cookies;
    6. $response = new Response();
    7. $signKey  = "#1dj8$=dp?.ak//j1V$~%*0XaK\xb1\x8d\xa9\x98\x054t7w!z%C*F-Jk\x98\x05\\\x5c";
    9. $cookies  = new Cookies();
    11. $cookies->setSignKey($signKey);
    13. $response->setCookies($cookies);

    Cookies can contain complex structures such as service information, resultsets etc. As a result, sending cookies without encryption to clients could expose application details that can be used by attackers to compromise the application and underlying system. If you do not wish to use encryption, you could send only unique identifiers that could be tied to a database table that stores more complex information that your application can use.

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

    • delete( string $name ): bool - Deletes a cookie by name. This method does not removes cookies from the $_COOKIE superglobal
    • get( string $name ): CookieInterface - Gets a cookie by name
    • getCookies(): array - Returns an array of all available cookies in the object
    • has( string $name ): bool - Check if a cookie is defined in the bag or exists in the $_COOKIE superglobal
    • isUsingEncryption(): bool - Returns if the bag is automatically encrypting/decrypting cookies.
    • reset(): CookiesInterface - Reset all set cookies
    • send(): bool - Sends all the cookies to the client. Cookies are not sent if headers are already sent during the current request
    • setSignKey( string $signKey = null ): CookieInterface - Sets the cookie’s sign key. If set to NULL the signing is disabled.
    • useEncryption( bool $useEncryption ): CookiesInterface - Set if cookies in the bag must be automatically encrypted/decrypted

    • set() - Sets a cookie to be sent at the end of the request.set(): CookiesInterface accepts the following parameters:

    • string $name - The name of the cookie

    • mixed $value = null - The value of the cookie
    • int $expire = 0 - The expiration of the cookie
    • string $path = "/" - The path of the cookie
    • bool $secure = null - Whether the cookie is secure or not
    • string $domain = null - The domain of the cookie
    • bool $httpOnly = null - Whether to set http only or not
    1. <?php
    3. use Phalcon\Http\Response\Cookies;
    5. $now = new DateTimeImmutable();
    6. $tomorrow = $now->modify('tomorrow');
    8. $cookies = new Cookies();
    9. $cookies->set(
    10.     'remember-me',
    11.     json_encode(
    12.         [
    13.             'user_id' => 1,
    14.         ]
    15.     ),
    16.     (int) $tomorrow->format('U')
    17. );

    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:

    • filePath - string - The path of where the file is
    • attachmentName - string - the name that the browser will save the file as
    • attachment - bool - whether this is an attachment or not (sets headers)
    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    6. $contents = file_get_contents();
    8. $response
    9.     ->setFileToSend(
    10.         '/app/storage/files/invoice.pdf',
    11.         'downloaded.pdf',
    12.         true
    13.     )
    14.     ->send()
    15. ;

    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 and the contents will be sent back to the caller.

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

    Examples

    1. <?php 
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    7. $response->redirect();

    Redirect to posts/index

    1. <?php 
    4. $response = new Response();
    6. $response->redirect('posts/index');

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

    1. <?php 
    5. $response = new Response();
    7. $response->redirect('https://en.wikipedia.org', true);

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

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

    1. <?php 
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    7. return $response->redirect(
    8.     [
    9.         'for'        => 'index-lang',
    10.         'lang'       => 'jp',
    11.         'controller' => 'index',
    12.     ]
    13. );

    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.

    Depending on the needs of your application, you might not want to control HTTP caching using Phalcon. There are several services available on the Internet that can help with that and could potentially be cheaper and easier to maintain (BitMitigate, Varnish etc.). Implementing HTTP Cache in your application will definitely help but it will have a small impact in the performance of your application. It is up to you to decide which strategy is best for your application and audience.

    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: - Set the expiration date of the page. Once the page expires the browser will request a fresh copy of the page vs. using the cached one.
    • Cache-Control: - How long is a page considered fresh in the browser.
    • Last-Modified: - When was the last time that this page was modified by the application (avoids reloading).
    • ETag: - Also known as entity tag, is a unique identifier for each page, created using the modification timestamp.
    • 304: - Send a not modified back

    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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response   = new Response();
    6. $expiryDate = new DateTime();
    8. $expiryDate->modify('+2 months');
    10. $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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response   = new Response();
    6. $expiryDate = new DateTime();
    8. $expiryDate->modify('-10 minutes');
    10. $response->setExpires($expiryDate);

    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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    7. $response->setHeader(
    8.     'Cache-Control', 
    9.     'max-age=86400'
    10. );

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

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    7. // $response->setHeader('Cache-Control', 'max-age=86400');
    8. $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:

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response = new Response();
    7. $response->setHeader(
    8.     'Cache-Control', 
    9.     'private, max-age=0, must-revalidate'
    10. );

    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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response   = new Response();
    6. $expiryDate = new DateTime();
    8. $expiryDate->modify('+2 months');
    10. $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.

    1. <?php
    3. use Phalcon\Http\Response;
    5. $response   = new Response();
    6. $expiryDate = new DateTime();
    8. $expiryDate->modify('-10 minutes');
    10. $response->setLastModified($expiryDate);

    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:

    1. <?php
    3. use MyApp\Models\Invoices;
    4. use Phalcon\Http\Response;
    6. $response = new Response();
    8. $mostRecentDate = Invoices::maximum(
    9.     [
    10.         'column' => 'inv_created_date',
    11.     ]
    12. );
    14. $eTag = sha1($mostRecentDate);
    16. $response->setHeader('E-Tag', $eTag);

    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.

    Dependency Injection

    The 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.

    1. <?php
    3. use Phalcon\Http\Response;
    4. use Phalcon\Mvc\Controller;
    6. /**
    7.  * Class PostsController
    8.  * 
    9.  * @property Response $response
    10.  */
    11. class PostsController extends Controller
    12. {
    13.     public function uploadAction()
    14.     {
    15.         return $this
    16.             ->response
    17.             ->setStatusCode(404, 'Not Found')
    18.             ->setContent("Sorry, the page doesn't exist")
    19.             ->send();
    20.     }

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