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;
}