A request is where an end user requests a resource in !TheBugGenie. Everything that is invoked is done so by a request, and in !TheBugGenie, this is represented by the TBGRequest class. This class performs several tasks, but its main purpose is to act as a bridge between the information passed on from the user making the request, and the application (or module).

The request class  

One of the first things done in the core framework is the instantiation of the request object. This object is used for several things, mainly determining the format of the response (based on the request), logging, XSS/CSRF protection, file uploads and basic request parameter handling and sanitation.

The request object is passed on to all controller methods whenever they are invoked (the method signature for a controller method requires a request as the only parameter) and is also accessible in all templates (via the $tbg_request variable). Whenever you need to access information passed on from the user - be it cookies, form data, route/url parameters, etc - you do so via the request object.

Accessing request information in a controller action  

Whenever you need to access information from a request inside an action, you just access the $request object passed to the action. As an example, in a controller, given the following url:

 http://thebuggenie.example.com/issue/1

you can access the issue id like this, via the request object:

echo $request->getParameter('issue_id');
  // echoes 1

This is possible because the issue_id parameter is defined as a part of the route. For unnamed query parameters (not defined explicitly in a route), the same applies:

 http://thebuggenie.example.com/custom_url/parameter1/value1/parameter2/value2

or

 http://thebuggenie.example.com/custom_url?parameter1=value1&parameter2=value2

the same applies:

echo $request->getParameter('parameter1');
  // echoes value1

  echo $request->getParameter('parameter2');
  // echoes value2

Accessing request information in a template  

Although most request handling should happen outside templates, sometimes it can be useful to access request information inside templates, too. !TheBugGenie passes a special variable $tbg_request to all templates and template partials/components. This behaves exactly as the request object passed to controllers.

As an example, in a template, given the following url:

 http://thebuggenie.example.com/issue/1

you would access the issue id like this:

echo $tbg_request->getParameter('issue_id');
  // echoes 1

Please note: By default, all request information is sanitized whenever it is being passed through TBGRequest::getParameter(). If you really need the unsanitized information, use the TBGRequest::getRawParameter() function - this will not sanitize the information passed on from the request.

Request methods  

You can use the request class to determine what method was used to execute the request, using the TBGRequest::isMethod() method. In addition to this, the request class also lets you check if the request was made via an AJAX method, using the TBGRequest::isAjaxCall() method:

if ($tbg_request->isMethod(TBGRequest::POST)):
    echo 'post';
  elseif ($tbg_request->isMethod(TBGRequest::GET)):
    echo 'get';
  elseif ($tbg_request->isAjaxCall()):
    echo 'ajax';
  endif;

(As seen above, both POST and GET methods are defined as TBGRequest constants)

Request formats  

Some routes are predefined to use a specific request format, and some routes have an optional request format parameter that can be passed to it. To check for the currently request format, use the TBGRequest::getRequestedFormat() function:

echo $tbg_request->getRequestedFormat();
  // echoes the requested format, defaults to 'html'

Note: This does not necessarily mean that the returned response will be in this format - this is simply the requested format. Check the response object to see what information is actually going to be passed back to the user.

Cookies  

Remember that cookies are passed on to the server via a request, and passed back to the user / browser via the response. This means you can access cookie information passed to !TheBugGenie via the request object, but you cannot manipulate it. Access cookies via TBGRequest::getCookie():

echo $tbg_request->getCookie('tbg3_username');
  // echoes the username

Handling file uploads  

The request object also handles file uploads. Whenever a file is uploaded, you can use the TBGRequest::handleUpload($key) function to handle an uploaded item from a form. The $key passed to this function is the name property on the file upload input field in the form. The function safely handles the upload, including error handling, and throws exceptions whenever an error occurs in the upload process. Assuming a successful upload, the file will be stored in the database or filesystem (depending on the configured upload storage method) and a TBGFile object will be returned.

Tip: To see if any files are included in a request, use the TBGRequest::hasFileUploads() method.

Upload progress  

When properly configured with apc, !TheBugGenie will allow you to check for the upload progress (see the apc documentation for information about how to enable this) for any download. You can check to see if this is supported using TBGRequest::CanGetUploadStatus(). Pass the download identificator to the TBGRequest::getUploadStatus() function to get the status information back:

if ($tbg_request->CanGetUploadStatus())
  {
    var_dump($tbg_request->getUploadStatus('random_id');
    // Dumps an array with upload status progress information
  }

Tips and tricks  

• You can check for the existence of a request parameter by using the TBGRequest::hasParameter($key) method
• Similar to the request parameter, you can also check for the existence of a cookie using TBGRequest::hasCookie($key)
• The request object safely handles input sanititation, including checks against phps gpc settings. The request also deep-sanitizes array information, and will return correct types for numbers (integer) and strings whenever it can detect it.
• Use the main/uploader component for a simple and easy to use uploader component which includes file upload progress support.