User input

The Input repository is separately maintained at https://github.com/PhpGt/Input

By default, PHP exposes all user input in the superglobal variables $_GET, $_POST and $_FILES, which are readable and writable by any code, including third party libraries.

All superglobals are protected within WebEngine, and instead user input is encapsulated within the Input object, which is available as the input property of your application's Logic classes.

Reading an input value from within a Logic class

The get function of the Input class will return the data matching the provided key, or null if the user input doesn't exist.

public function getUserInput() {
// Read the "telephone" parameter from the query string or post body:
	$telephone = $this->input->get("telephone");

// Read the "name" parameter, supplying a default if input is empty:
	$name = $this->input->get("name") ?? "Anon";
}

It doesn't matter what HTTP verb (GET, POST, PUT, DELETE, etc.) is used for the request as input is accessed in the same way for all verbs.

You can however specify only to load the input value from the querystring, body or files section of the request parameters. This can be done by passing in one of the following constants as the second parameter to the get function:

• Input::DATA_QUERYSTRING
• Input::DATA_BODY
• Input::DATA_FILES.

The default is Input::DATA_COMBINED.

The InputData object

The Input object represents a combination of the different InputData objects that make up the HTTP request; QueryStringInputData, BodyInputData and FileUploadInputData, which correspond to PHP's $_GET, $_POST and $_FILES superglobals.

When passing specific input data to callback functions, the callbacks receive a customised InputData object too, containing just the requested keys. For information, see the Passing input data to callback functions section below.

When getting a value from InputData using the get function you will receive a string representation of the input value, or null if the input does not exist. If other data types are required from user input, use one of the get* functions, as described in the next section.

Returning a specific type of data

All user input is treated internally as strings, due to the plaintext protocol of HTTP, however it is possible to get user input as a specific datatype if you expect it to be that type.

Use the following functions to return the type you desire:

• string - getString, a synonym of getValue
• int - getInt
• float - getFloat
• bool - getBool
• DateTime - getDateTime

You may also supply your own class with the getAs function, passing in the key as the first parameter and the class name as the second parameter. This function constructs the provided class with the value of the user input.

Example:

<form>
	<label>
		Your name:
		<input name="name" />
	</label>
	<label>
		Your date of birth:
		<input name="dob" type="date" />
	</label>
	<label>
		Your postcode:
		<input name="postcode" />
	</label>
</form>

public function getPersonDetails() {
	$name = $this->input->get("name");

	$dob = $this->input->getDateTime("dob");
	// same as $dob = new DateTime($this->input->get("dob"));

	$address = $this->input->getAs("postcode", Address::class);
	// same as $address = new Address($this->input->get("postcode"));
}

When using get* functions, if the requested type can not be used to cast/construct from the user input, a DataNotCompatibleFormatException will be thrown.

Getting uploaded files

The getFile function returns a FileUpload object, which is an instance of the base InputData class and contains useful functions to work with uploaded files. If you were to supply an uploaded file's input key to the get function, it will return a string containing the original filename of the uploaded file.

Read more about handling file uploads

The MultipleInputData object

Using square brackets in the HTML form element's name denotes a multiple input field as described in the PHP HTML FAQ.

// TODO: clarify below...

Calling a get function on a multiple key will return a MultipleInputData object, rather than an InputData object.

All get* functions come with getMultiple* counterparts.

// TODO: complete

Checking the presence of specific user input

// has

// hasValue

// hasQueryStringParameter

// hasBodyParameter

// hasFile

Passing input data to callback functions

The code in your application's Logic classes has full access to the user input, but you don't want to pass all user input around to all other areas of code. Instead, it is possible to call functions with only the user input they are required to know about. For example, in an e-commerce application, only the payment processor needs to be handed the user's credit card details, and not any other areas of code.

Using do triggers

// Shorthand for when - easily hook up button presses to callbacks

The with and without functions

// with returns a Trigger

Triggering a callback when there's matching user input

// when only calls callback when provided input is present

// or functionality...

Handling multiple input

// Square brackets - MultipleInputDatum

// getMultipleFile

// getMultipleDateTime

Handling file uploads

// getFile, getMultipleFile

// move

// getFileInfo, getRealPath, getOriginalName, getOriginalExtension, getSize, getMimeType

// FailedFileUpload