Skip to main content

Responses

About 3 min

Responses

In the Hazaar Framework, a Response object represents the HTTP response that will be sent back to the client. It aggregates the response body (content), HTTP status code, and headers into a single object, allowing for precise control over what the client receives.

Every controller action should primarily return a Hazaar\Controller\Response object. This explicit return type ensures that the application behaves predictably and that the framework can correctly process the output before sending it to the browser or API client.

Basic Usage

The most direct way to generate a response is to instantiate and return a Response object from your controller action.

use Hazaar\Controller\Response\HTTP\OK;

public function index(): Response
{
    return new OK('Hello World!');
}

However, Hazaar provides several specialized response classes to handle different content types like JSON, XML, files, and images.

Automatic Response Creation

To simplify development, Hazaar allows you to return common PHP types directly from your controller actions. The framework automatically converts these return values into the appropriate Response object:

  • Strings: Returning a string will automatically create a Hazaar\Controller\Response\Text object.
  • Arrays: Returning an array (or stdClass) will automatically create a Hazaar\Controller\Response\JSON object.
  • Views: In Hazaar\Controller\Action controllers, returning nothing (void) triggers the default view rendering mechanism. However, returning a Response object explicitly will override this default behavior.

Available Response Types

Hazaar provides a comprehensive set of response classes located in the Hazaar\Controller\Response namespace. Below is a summary of the available response types and their intended usage.

Text

Hazaar\Controller\Response\Text

Used for returning simple plain text responses. This is the default response type if you return a string from a controller action.

return new Text('Simple text response');

JSON

Hazaar\Controller\Response\JSON

Used for returning JSON formatted data. This is typically used for API endpoints. It automatically handles the Content-Type: application/json header and JSON encoding of the data. If you return an array from a controller action, it is automatically converted to this response type.

return new JSON(['status' => 'ok', 'data' => []]);

HTML

Hazaar\Controller\Response\HTML

Used for returning HTML content. It sets the Content-Type to text/html.

return new HTML('<h1>Hello World</h1>');

XML

Hazaar\Controller\Response\XML

Used for returning XML content. It requires a Hazaar\XML\Element object as its content and sets the Content-Type to text/xml.

use Hazaar\XML\Element;

$xml = new Element('root');
$xml->add('child', 'value');
return new XML($xml);

File

Hazaar\Controller\Response\File

Used to serve files to the client. This class handles setting the correct MIME type, Content-Length, and other headers for file downloads or inline display. It also supports cache control directives.

// Serve a file for download
return new File('/path/to/file.zip');

Image

Hazaar\Controller\Response\Image

Extends the File response to specifically handle image files. It can be used to serve images directly and provides integration with Hazaar\File\Image for on-the-fly manipulation if needed.

return new Image('/path/to/image.jpg');

PDF

Hazaar\Controller\Response\PDF

Used to serve PDF documents. It works in conjunction with Hazaar\File\PDF to serve existing PDF files or to generate PDFs from HTML on the fly.

To serve an existing file:

// Display PDF in browser
return new PDF('/path/to/document.pdf');

// Force download
return new PDF('/path/to/document.pdf', true);

To generate a PDF from HTML:

use Hazaar\File\PDF as PDFFile;
use Hazaar\Controller\Response\PDF;

$pdf = new PDFFile();
$pdf->setContents('<h1>Hello World</h1>'); // Convert HTML to PDF

return new PDF($pdf);

Stream

Hazaar\Controller\Response\Stream

Used for streaming responses, typically for large datasets or implementing custom stream protocols. This is often used internally by the Basic controller for stream output.

HTTP Status Responses

Located in the Hazaar\Controller\Response\HTTP namespace, these responses correspond to standard HTTP status codes. They are useful for returning semantic responses indicating success, errors, or redirects.

For a complete list of available HTTP response classes, please see the API Documentation.

Here are some of the most commonly used status responses:

use Hazaar\Controller\Response\HTTP\NotFound;
use Hazaar\Controller\Response\HTTP\Redirect;

// Return a 404 error
return new NotFound();

// Redirect to another URL
return new Redirect('/home');
Copyright © 2012-present Hazaar Labs