Request Handling

The Quantum PHP Framework provides comprehensive methods for interacting with request parameters, files, and payload data.

Input Merge Precedence

When a request is initialized, the Request object aggregates parameters from various sources. The final parameters are merged in the following order of precedence (each source overwrites the previous one):

  1. Query Parameters: Parameters from the request URI query string.
  2. POST Parameters: Standard $_POST data.
  3. JSON Payload: Parsed contents of the request body if the content type is JSON.
  4. URL-Encoded Body: Parsed contents of the request body if the content type is application/x-www-form-urlencoded.
  5. Multipart Raw Inputs: Parsed parameters for requests with multipart/form-data.

Multipart Raw Parsing

The framework supports raw parsing for multipart/form-data requests.

  • Parser Gate: The multipart raw parser is triggered for PUT, PATCH, and POST requests where the Content-Type header explicitly identifies multipart/form-data.
  • Precedence: These parameters are merged last, giving them the highest precedence over values defined in other sources.

Uploaded Files

Uploaded files are handled through the setUploadedFiles method, which follows this merge baseline:

  1. $_FILES Normalization: PHP's native $_FILES global is processed via the handleFiles() method, which iterates over all top-level keys in $_FILES and normalizes both single and multi-file payloads.
  2. Multipart Raw Files: Files extracted during raw multipart parsing are merged into the collection if present.
  3. Resulting Collection: The finalized files collection contains the normalized keys from $_FILES merged with any files extracted by the raw multipart parser.

See the Advanced Request Lifecycle for further technical details on the parsing contract.

Query Accessors

The Query trait provides the mechanism for reading and modifying the raw query string associated with the current request.

getQueryParam(string $key): ?string

This method returns the first-match raw value for the specified key from the current request's query string.

  • Note on decoding: It returns the raw value exactly as it appears in the query string; it does not URL decode the value.
  • Return value: Returns the raw value if found, or null if the key is not present in the query string or if the query string is unset.

Examples:

// Assuming current query string: "id=123&name=John%20Doe"

$request->getQueryParam('id');   // Returns "123"
$request->getQueryParam('name'); // Returns "John%20Doe"
$request->getQueryParam('age');  // Returns null

setQueryParam(string $key, string $value): void

This method appends a new query parameter to the query string.

  • Non-overwriting: It does not overwrite existing keys. If a key already exists, appending will result in duplicate keys in the raw query string.
  • Encoding contract: The framework does not URL-encode the key or value. Callers are responsible for encoding values if they contain spaces or special characters.

Example:

// Initial state: query string is null

$request->setQueryParam('user', 'arman');
// Query string: "user=arman"

// Appending with special characters (no automatic encoding)
$request->setQueryParam('message', 'hello world'); 
// Raw query string: "user=arman&message=hello world"

// Appending an existing key (duplicate keys)
$request->setQueryParam('id', '1');
$request->setQueryParam('id', '2');
// Raw query string: "user=arman&message=hello world&id=1&id=2"

After request handling, continue with: