Responses

All controllers must return a response to be sent back to the user's browser. Siteadmin provides many response types which configure the appropriate headers for each content type.

HTML Response

<?php
use sa\application\controller;
use sa\application\responses\View;

class UserController extends controller {
    public function index() {
        // Use master theme.
        // Render the '/{module}/views/user_list.php' view
        $html = new View('master', 'user_list');
        
        // Pass variables $first_name and $last_name into HTML view.
        $html->data = array('first_name' => 'John', 'last_name' => 'Doe');
        
        // Render the view
        return $html;
    }
}

Constructor Parameters

Field

Type

Optional/Required

Definition

$template

string

required

The layout to wrap around the HTML content. Use null for no layout. Use master for default application layout.

$view

string

required

The HTML content to render in the template. Siteadmin will search for the template in /themes/{theme}/views, then /modules/{module}/views if not found.

$location

string

optional

Location of the view. To load a view from a different module, use \{vendor}\{module}\SomeController::viewLocation().

$responseCode

int

optional

HTTP response code (200, 404, etc.)

JSON Response

<?php
use sa\application\controller;
use sa\application\responses\Json;

class UserController extends controller {
    public function index() {
        $json = new Json();
        
        // Set json content.
        $json->data = array('first_name' => 'John', 'last_name' => 'Doe');
        
        // render json
        return $json;
    }
}

Constructor Parameters

Field

Type

Optional/Required

Definition

$responseCode

int

optional

HTTP response code (200, 404, etc.)

XML Response

<?php
use sa\application\controller;
use sa\application\responses\Xml;

class UserController extends controller {
    public function index() {
        $xml = new Xml('root_tag', 'namespace', 200);
        
        // Set XML content.
        $xml->data = array('first_name' => 'John', 'last_name' => 'Doe');
        
        // render xml
        return $xml;
    }
}

Constructor Parameters

Field

Type

Optional/Required

Definition

$rootTag

string

required

The XML document's root tag.

$namespace

string

optional

XML namespace definition.

$responseCode

int

optional

HTTP response code (200, 404, etc.)

File/Binary Response

Renders a file, such as an image or PDF, in the browser.

<?php
use sa\application\controller;
use sa\application\responses\File;

class UserController extends controller {
    public function index() {
        $file = new File('/path/to/file.ext');
        
        // render or download file
        return $file;
    }
}

Constructor Parameters

Field

Type

Optional/Required

Definition

$filePath

string

required

Path to file.

HTTP Redirect

<?php
use sa\application\controller;
use sa\application\responses\Redirect;

class UserController extends controller {
    public function index() {
        // 302 temporary redirect
        $redirect = new Redirect('/url-to-new-page');
        
        // 301 permanent redirect
        $redirect = new Redirect('/url-to-new-page', true);
        
        return $redirect;
    }
}

Constructor Parameters

Field

Type

Optional/Required

Definition

$location

string

required

A website URL. (e.g. http://domain.com or /path/on/current/website)

$isPermanent

boolean

false

Default: false. If true, 301 redirect header will be included in the response.

Custom Responses

The Response Interface

All responses must implement the sa\application\responses\ISaResponse interface. This requires your custom response to include the following methods,

Method

Returns

Description

buildResponse

void

Sets appropriate headers for the response.

getResponse

string

Serializes the response's data into a string.

getHeaders

array

Returns key-value pairs as an array, where the key is a header and the value is its value.

The Response Trait

Most responses allow the developer to set custom headers and a custom response code. A wrapper for this exists through the \sa\application\responses\TViews trait, which exposes a headers property, as well as a helper method for setting the response code: setResponseCode().

Method/Property

Type

Description

headers

array

An associative array of headers. The key is the header name. The value is the header content.

setResponseCode($httpCode)

function

Sets the response code for the request to the given HTTP code.

Custom Response Example

<?php
use sa\application\responses\ISaResponse;
use sa\application\responses\TViews;
use sa\application\responses\ResponseHeader;

class Yaml implements ISaResponse {
    use TViews;
    
    public $data = array();
    private $responseCode;

    public function __construct($responseCode = 200) {
        $this->responseCode = $responseCode;
    }

    /**
     * Gets called before getHeaders and getResponse
     */
    public function buildResponse()
    {
        $this->setResponseCode($this->responseCode);
        $this->headers[] = new ResponseHeader('Content-Type', 'application/x-yaml');
    }

    /**
     * Gets the response content to be echo to the user
     *
     * @return string
     */
    public function getResponse()
    {
        return yaml_emit($this->data);
    }

    /**
     * Gets the headers to be sent to the user
     *
     * @return array();
     */
    public function getHeaders()
    {
        return $this->headers;
    }
}

Downloading Files

Sometimes an application will need to download a file instead of rendering its contents in the browser. This is useful for exporting XML, images, word documents, zip files, among others.

The Downloadable Response Trait

Download capabilities are exposed through the DownloadableResponseTrait . This trait exposes a setDownloadable() method which accepts a file name as its only parameter. Once this method is executed, the response object will configure the necessary headers to download its contents as a file.

The following response types implement this trait:

  • JSON

  • XML

  • File

Download JSON

public function downloadJson() {
    $json = new Json();
    $json->data = [
        "id" => 1,
        "first_name" => "John",
        "last_name" => "Doe"
    ];

    $json->setDownloadable('member.json');
    return $json;
}

public function downloadXml() {
    $member = modRequest::request('auth.member');
    $xml = new Xml('member');
    $xml->data = doctrineUtils::getEntityArray($member);

    $xml->setDownloadable('test.xml');
    return $xml;
}

Download XML

public function downloadXml() {
    $xml = new Xml('member');
    $xml->data = [
        "id" => 1,
        "first_name" => "John",
        "last_name" => "Doe"
    ];

    $xml->setDownloadable('member.xml');
    return $xml;
}

Download Files

The File response can be used to download any type of file. Common use cases include:

  • CSV

  • Images

  • PDFs

  • Word Documents

...or any other type of file.

public function downloadFile() {
    // Download file from the module's /img directory.
    $file = new File(__DIR__ . '/../img/photo_1.png');
    $file->setDownloadable('photo_1.png');
    return $file;
}

Last updated