The Request Object

The Hazaar\Application\Request object is a central component in the Hazaar Framework that encapsulates all the details of an incoming HTTP request. It serves as the primary interface for accessing client input, including query parameters, form data, JSON payloads, and HTTP headers.

By automatically parsing and normalizing request data, the Request object simplifies the task of handling different types of requests, whether they are standard page loads, AJAX calls, or API interactions. It acts as a container for the state of the current request, ensuring that controllers and middleware have consistent access to the information they need to process the user's intent.

The request object is accessible within your controllers via $this->request and is instantiated automatically by the application during the bootstrap process.

Key capabilities include:

• Input Retrieval: Unified access to data from $_GET, $_POST, and raw request bodies.
• Content Parsing: Automatic decoding of JSON payloads into usable arrays.
• Header Access: Simple methods to retrieve and inspect HTTP headers.
• Method Detection: Helper methods to check the HTTP verb (GET, POST, PUT, DELETE, etc.).
• Context Awareness: Methods to detect AJAX requests, mobile devices, and client IP addresses.
• Data Passing: A mechanism to store and retrieve attributes, facilitating data sharing between middleware and controllers.

For a complete list of available methods and properties, please refer to the Request API documentation.

Request Methods

The request object provides the following methods to determine the request method:

• isGet() - Returns true if the request uses the GET method.
• isPut() - Returns true if the request uses the PUT method.
• isPost() - Returns true if the request uses the POST method.
• isDelete() - Returns true if the request uses the DELETE method.
• getMethod() - Returns the name of the request method for this request.

Tips

Hazaar\Application\Request::getMethod() is available in CLI requests as well, but will always be GET.

public function action(): Response
{
    if($this->request->isPOST()){
        // Store the update and return status
    }elseif($this->request->isGET()){
        // Return the product
    }
    
    return BadRequest;
}

Example

In this example our controller has a get method that returns a product formatted as JSON. The URL would be:

/api/v1/product/get/1234

This URL loads Application\Controller\Product and executes its list method. The corresponding controller is located in application/controllers/api/v1/product.php:

namespace App\Controller\Api\V1;

use Hazaar\Controller\Basic;
use Hazaar\Controller\Response;
use Hazaar\Controller\Response\Json;
use Hazaar\Controller\Response\HTTP\BadRequest;
use Hazaar\DBI\Adapter;

class Product extends Basic {

    public function init(): void
    {
        // Initialization code
    }

    public function get(int $productId): Response
    {
        if(!$this->request->isGET()){
            return new BadRequest;
        }
        $db = Adapter::create();

        return new Json($db->table('product')->find(['id' => $productId]));
    }
}

Remote IP Address

The request object provides the getRemoteAddr() method to determine the remote IP address of the client making the request.

• getRemoteAddr() - Returns the remote IP address.

public function action(): Response
{
    $ip = $this->request->getRemoteAddr();
    
    return new Json(['ip' => $ip]);
}

If a X-Forwarded-For header is present in the request, the getRemoteAddr method will return the first IP address in the list.

Request Attributes

Request attributes are a mechanism to pass data between middleware and controllers, or between different middleware components. Attributes are stored on the Request object and persist for the duration of the request. This is useful for things like passing an authenticated user object or other data that is derived from the request.

• setAttribute(string $key, mixed $value) - Sets a request attribute.
• getAttribute(string $key) - Retrieves a request attribute. Returns null if the attribute does not exist.

Setting Attributes

Attributes are typically set in middleware.

public function handle(Request $request, callable $next, mixed ...$args): Response
{
    $request->setAttribute('key', 'value');
    
    return $next($request);
}

Getting Attributes

Attributes can be retrieved in controllers or subsequent middleware.

public function index(): Response
{
    $value = $this->request->getAttribute('key') ?? 'default_value';

    return new Json(['value' => $value]);
}