> For the complete documentation index, see [llms.txt](https://docs.siteadministrator.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.siteadministrator.com/developer-guide/the-basics/responses.md).

# 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
<?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
<?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
<?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
<?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
<?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
<?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

```php
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

```php
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.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.siteadministrator.com/developer-guide/the-basics/responses.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.