To accept user-provided data from a web page, we need two logically
distinct components: a form for the user to enter the data, and a handler
to accept that data. We will call the form in
form1.html and the
form1_handler.php. Note that there's no reason why the
form must be a static html file, but there's no technical reason it can't be,
either. The handler, however, must be written in some programming language;
in this case, we're using PHP.
<html> <body> <form action="form1_handler.php" method="POST"> <input type="text" name="my_text_field" /> <input type="submit" name="send_button" value="Send" /> </form> </body> </html>
The important part is the form tag, which has two required attributes: the action, which is the URL that is called when the form is submitted, and the method, which is the format in which the data is transmitted (either POST or GET). The difference between POST and GET, and when you should use one over the other is beyond the scope of this introductory tutorial. We will use POST in this example because it is the more flexible of the two methods.
The <form>...</form> tag pair encloses 1 or more <input> tags. These are the controls which are displayed in the user's browser. The input tag has two required attributes: type and name. For a list of valid types see the input tag documentation. The "file" input type requires special handling, which will be the subject of a later discussion. While it isn't a strict requirement that the form have a submit control, it isn't very useful if it doesn't, as this is what is used to transmit the user's data to our handler. A form can have multiple submit buttons, as long as they all have unique names. The value attribute in the submit button is not strictly needed; this controls the text that is displayed on the button; if we don't specify anything the default value of "Submit Query" will be used.
The important consideration is that each input element have
a unique name. These names form the keys in a list of key-value pairs that are
transmitted to our handler when the submit button is pressed. In PHP,
we can use the
$_POST array to access this list of key value pairs:
<?php $text_field_value = $_POST['my_text_field']; $send_button_value = $_POST['send_button']; ?>
Notice that the 1:1 correspondence between the elements in the $_POST array and the input element names in our form. In the case of the text element, the value will be whatever the user typed in; in the caes of the submit element, the value will be what we set in the form (or the aforementioned default value). If we have more than one submit element, only the one that the user clicked will have a value, any others will be NULL.
The preceding code, by itself, will do nithing except set a local variable which holds the submitted values, which are then immediately discarded. Nothing is displayed or saved because we haven't explicitly written any code to do so. One option is to use the submitted values to perform some calculation or process, the result of which we will display to the user. Another typical operation is to save the values to a database or other persistent storage for later use. As a trivial example, we can echo back the values the user submitted:
<?php $text_field_value = $_POST['my_text_field']; $send_button_value = $_POST['send_button']; ?> <html> <body> <ul> <li>my_text_field = <? print $text_field_value ?></li> <li>send_button = <? print $send_button_value ?></li> </ul> <a href="form1.html">Return to Form 1</a> </body> </html>
It's important to note at this point that the values that we get from $_POST cannot be trusted in any way. There is nothing preventing a malicious user from writing his own form which submits hostile data to our handler, bypassing any protections we put in our form. We have to be very careful what we do with incoming data, and take steps to render it safe before we use it for anything. Even seemingly trivial operations using unsanitized data, like the example above, can potentially provide an attacker with a vector by which our website can be attacked. Failure to properly validate and sanitize form data is by far the most common security error made on the web. How to do this is the subject of a later article.