Accessing User Input

User input is normally handled in PHP scripts using the $_GET, $_POST, $_COOKIE, etc superglobals. Once the library is bootstrapped, these superglobals remain unaffected and can be manipulated as normal. If you choose to use the library code environments, an alternative route to access user input is also available.

GET and POST Variables

The GET and POST data is available through the environment input() method as caged arrays (see T_Cage_Array). When retrieving array keys the interface forces the user to specify what you are expecting (a scalar or array), and provides an optional filter method to validate the input.

  1. <?php
  2. $env = new T_Environment_Http;
  4. $page = 1;
  5. // either ...
  6. if (isset($_GET['page'])) $page = (int) $_GET['page'];
  7. // ... or ...
  8. if ($env->input('GET')->exists('page')) {
  9. try {
  10. $page = $env->input('GET')
  11. ->asScalar('page')
  12. ->filter(new T_Validate_Int)
  13. ->uncage();
  14. } catch (Exception $e) { $page = 1; }
  15. }
  16. ?>

In the example above, the 'page' GET variable is validated as a scalar integer. If it is an array or not an integer an exception will be thrown. In most cases this can be left to bubble up to the global error handler, or it can be explicitally handled with a try-catch block. The example above is trivial and the normal $_GET code is shorter and cleaner (although note it is not entirely safe, an error will occur if the input is an array). However, once things become more complicated the cage interface actually helps:

  1. <?php
  2. $choices = array(); // expect array of integers via POST
  3. // e.g. $choices = $_POST['choices'];
  4. if ($env->input('POST')->exists('choices')) {
  5. $f = new T_Filter_ArrayMap(new T_Validate_Int);
  6. $choices = $env->input('POST')
  7. ->asArray('choice')
  8. ->filter($f)
  9. ->uncage();
  10. }
  11. ?>

Note that the filter method can be called multiple times to execute multiple filters against the input (these can validate or simply manipulate the data), or the filter method does not need to be called at all. The asArray or asScalar methods are called with the key name as an argument to retrieve that element, and the uncage method is always called finally to retrieve the filtered data from the "cage".

Cookies

Cookie data can be retrieved in a similar manner to the GET or POST data via the environment input() method, and is uncaged in the same way: the example below shows how you could use a PHP5.3 lambda function to validate your input.

  1. <?php
  2. $theme = 'default';
  3. if ($env->input('COOKIE')->exists('theme')) {
  4. $fn = function ($th) {
  5. if (!/* theme is installed */) $th='default';
  6. return $th;
  7. };
  8. $theme = $env->input('COOKIE')
  9. ->asScalar('theme')
  10. ->filter($fn)
  11. ->uncage();
  12. }
  13. ?>

To manage the cookies, the Cookie cage has a set() and delete() method.

  1. <?php
  2. // set a new theme
  3. $env->input('COOKIE')
  4. ->set('theme','newThemeName',time()+30*24*60*60);
  5. // expires in 30 days ^
  6. // delete new theme
  7. $env->input('COOKIE')->delete('theme');
  8. ?>

The set method supports the same argument list to the inbuilt setcookie function, but default values for path and domain that are taken from the environment app root URL if it is available.

Uploaded Files

TODO

$_SERVER Variables

TODO

How-Tos

Want to see the code?

If you want to poke around the code itself, you can use git to grab yourself a copy.

Reference

If you're already familar with the codebase but simply want to look something up, best to head over to the code reference.

Had enough of an introduction?