Form Handling

Form handling support in the framework

All the usual PHP form handling mechanisms work ($_POST, $_GET, etc.) but the framework provides a singleton class that has utility methods that makes access a bit simpler and cleaner - most importantly they include error handling. Note, the class does not provide access to the $_REQUEST array as there are some potential issues with using the integrated array associated with the order in which the various data arrays are combined to form it.

For the Twig macros that help generate forms, see the macros section.

Getting the Formdata object

Use the call : 


                    $formd = $context->formdata(method);
where $context is the Context object. method is one of 'get', 'post', 'put', 'patch', 'cookie' and 'file' and selects the apporpriate source of data for your requests. If you need to access the query string ('get') and post data then you will need to invoke the call twice.

N.B. All the API documentation links below, apart from the twol file calls, go to the 'get' version of the interface, however the call semantics are identical across the other instances.

Existence functions

The Formdata class provides a method that test to see if a particular field exists: 


                    $formd->exists('xyz')

Data access

This method lets you ask for an element of the appropriate data source, and, if it does not exist, returns the default value you provide or an empty string if you don't provide a value. Note that access to uploaded files is done through other methods as the data is more structured and complex. 


                $formd->fetch('xyz', 'empty', OPTIONAL_FILTER, 'filter options', FALSE)

The first parameter identifies the element you wish to retrieve. It can be either a string, naming a simple element, or see below for format when accessing an array element The second parameter is a default value for use when the element is not present.

The third and fourth parameters allow you to apply a PHP filter to the results. They default to NULL and '' respectively, so no filter will be applied. If the fifth paramter is set to TRUE then the element being retrieved can be an array. Normallly, results are strings and are trimmed by the function, this is, of course, not appropriate for arrays. See below for other ways to access array data.

The nextmethod lets you ask for an element of the appropriate data source, and, if it does not exist, then the method throws an exception. 


                $formd->mustFetch('xyz', OPTIONAL_FILTER, 'filter options', FALSE)

See above for details of the parameters after the element name field.

If you want to get an element of an array then you can pass an array as the first parameter to the relevant function, e.g. to get at the element ['xyz']['abc'] in $_GET or $_POST: 


                $formd->fetch(['xyz', 'abc'], TRUE)

                $formd->mustFetch(['xyz', 'abc'], TRUE)

Array Values

The following functions look for an array value in the superglobal arrays and return an ArrayIterator that can be used to process the array. The default parameter must be an array of course if you provide one. If you need an actual copy of the array then you can use the getArrayCopy() method of the Iterator. 


                $formd->fetchArray('xyz', [])


                $formd->mustFetchArray('xyz')

Files

There is an unfortunate PHP inconsistency/misfeature/misdesign between accessing individual file uploads and arrays of file uploads. This function harmonises access and allows you to access them in the same way. The second parameter is the key to be used when accessing an array of files. Note this only works with single dimensional arrays of file uploads. 


                $formd->fileData('xyz')

If you have an array of files and want to iterate over them use: 


                $formd->fileArray('batch', [])

Which returns an iterator that will also harmonise the format of the data for each element retrieved. Note that currently this does not