Useful Server Variables

In addition to PHP_SELF and REQUEST_METHOD, the $_SERVER auto-global array contains a number of useful elements that provide information on the web server and the current request. Table 7-1 lists some of them.

Accessing Form Parameters

At the beginning of every request, the PHP engine sets up some auto-global arrays that contain the values of any parameters submitted in a form or passed in the URL. URL and form parameters from GET method forms are put into $_GET. Form parameters from POST method forms are put into $_POST.

The URL http://www.example.com/catalog.php?product_id=21&category=fryingpan puts two values into $_GET:

• $_GET['product_id'] is set to 21
• $_GET['category'] is set to fryingpan

Submitting the form in Example 7-2 causes the same values to be put into $_POST, assuming 21 is entered in the text box and Frying Pan is selected from the menu.

<form method="POST" action="catalog.php">
<input type="text" name="product_id">
<select name="category">
<option value="ovenmitt">Pot Holder</option>
<option value="fryingpan">Frying Pan</option>
<option value="torch">Kitchen Torch</option>
</select>
<input type="submit" name="submit">
</form>

Example 7-3 incorporates the form in Example 7-2 into a complete PHP program that prints the appropriate values from $_POST after displaying the form. Because the action attribute of the <form> tag in Example 7-3 is catalog.php, you need to save the program in a file called catalog.php on your web server. If you save it in a file with a different name, adjust the action attribute accordingly.

<form method="POST" action="catalog.php">
<input type="text" name="product_id">
<select name="category">
<option value="ovenmitt">Pot Holder</option>
<option value="fryingpan">Frying Pan</option>
<option value="torch">Kitchen Torch</option>
</select>
<input type="submit" name="submit">
</form>
Here are the submitted values:

product_id: <?php print $_POST['product_id'] ?? '' ?>
<br/>
category: <?php print $_POST['category'] ?? '' ?>

To avoid a warning message from PHP when no POST variables have been submitted, Example 7-3 uses ??, the null coalesce operator.

The code $_POST['product_id'] ?? '' evaluates to whatever’s in $_POST['product_id'] if there’s something there, or the empty string ('') otherwise. Without it, you’d see messages like PHP Notice: Undefined index: product_id when the page is retrieved by the GET method and no POST variables have been set up.

if (isset($_POST['product_id'])) { 
   print $_POST['product_id']; 
   }

A form element that can have multiple values needs to have a name that ends in []. This tells the PHP engine to treat the multiple values as array elements. The <select> menu in Example 7-4 has its submitted values put into $_POST['lunch'].

<form method="POST" action="eat.php">
<select name="lunch[]" multiple>
<option value="pork">BBQ Pork Bun</option>
<option value="chicken">Chicken Bun</option>
<option value="lotus">Lotus Seed Bun</option>
<option value="bean">Bean Paste Bun</option>
<option value="nest">Bird-Nest Bun</option>
</select>
<input type="submit" name="submit">
</form>

If the form in Example 7-4 is submitted with Chicken Bun and Bird-Nest Bun selected, then $_POST['lunch'] becomes a two-element array, with element values chicken and nest. Access these values using the regular multidimensional array syntax. Example 7-5 incorporates the form from Example 7-4 into a complete program that prints out each value selected in the menu. (The same rule applies here to the filename and the action attribute. Save the code in Example 7-5 in a file called eat.php or adjust the action attribute of the <form> tag to the correct filename.)

<form method="POST" action="eat.php">
<select name="lunch[]" multiple>
<option value="pork">BBQ Pork Bun</option>
<option value="chicken">Chicken Bun</option>
<option value="lotus">Lotus Seed Bun</option>
<option value="bean">Bean Paste Bun</option>
<option value="nest">Bird-Nest Bun</option>
</select>
<input type="submit" name="submit">
</form>
Selected buns:
<br/>
<?php
if (isset($_POST['lunch'])) {
    foreach ($_POST['lunch'] as $choice) {
        print "You want a $choice bun. <br/>";
    }
}
?>

With Chicken Bun and Bird-Nest Bun selected in the menu, Example 7-5 prints (after the form):

Selected buns:
You want a chicken bun.
You want a nest bun.

You can think of a form element named lunch[] as translating into the following PHP code when the form is submitted (assuming the submitted values for the form element are chicken and nest):

$_POST['lunch'][] = 'chicken';
$_POST['lunch'][] = 'nest';

As you saw in Example 4-6, this syntax adds an element to the end of an array.

Form Processing with Functions

The basic form in Example 7-1 can be made more flexible by putting the display code and the processing code in separate functions. Example 7-6 is a version of Example 7-1 with functions.

// Logic to do the right thing based on
// the request method
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    process_form();
} else {
    show_form();
}

// Do something when the form is submitted
function process_form() {
    print "Hello, ". $_POST['my_name'];
}

// Display the form
function show_form() {
    print<<<_HTML_
<form method="POST" action="$_SERVER[PHP_SELF]">
Your name: <input type="text" name="my_name">
<br/>
<input type="submit" value="Say Hello">
</form>
_HTML_;
}

To change the form or what happens when it’s submitted, change the body of process_form() or show_form().

Breaking up the form processing and display into functions also makes it easy to add a data validation stage. Data validation, covered in detail in “Validating Data”, is an essential part of any web application that accepts input from a form. Data should be validated after a form is submitted, but before it is processed. Example 7-7 adds a validation function to Example 7-6.

// Logic to do the right thing based on
// the request method
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    if (validate_form()) {
        process_form();
    } else {
        show_form();
    }
} else {
    show_form();
}

// Do something when the form is submitted
function process_form() {
    print "Hello, ". $_POST['my_name'];
}

// Display the form
function show_form() {
    print<<<_HTML_
<form method="POST" action="$_SERVER[PHP_SELF]">
Your name: <input type="text" name="my_name">
<br/>
<input type="submit" value="Say Hello">
</form>
_HTML_;
}

// Check the form data
function validate_form() {
    // Is my_name at least 3 characters long?
    if (strlen($_POST['my_name']) < 3) {
        return false;
    } else {
        return true;
    }
}

The validate_form() function in Example 7-7 returns false if $_POST['my_name'] is less than three characters long, and returns true otherwise. At the top of the page, validate_form() is called when the form is submitted. If it returns true, then process_form() is called. Otherwise, show_form() is called. This means that if you submit the form with a name that’s at least three characters long, such as Bob or Bartholomew, the same thing happens as in previous examples: a Hello, Bob or Hello, Bartholomew message is displayed. If you submit a short name such as BJ or leave the text box blank, then validate_form() returns false and process_form() is never called. Instead show_form() is called and the form is redisplayed.

Example 7-7 doesn’t tell you what’s wrong if you enter a name that doesn’t pass the test in validate_form(). Ideally, when someone submits data that fails a validation test, you should explain the error when you redisplay the form and, if appropriate, redisplay the value entered inside the appropriate form element. The following section shows you how to display error messages, and “Displaying Default Values” explains how to safely redisplay user-entered values.

Validating Data

Data validation is one of the most important parts of a web application. Weird, wrong, and damaging data shows up where you least expect it. Users can be careless, malicious, and fabulously more creative (often accidentally) than you may ever imagine when you are designing your application. Even a a Clockwork Orange–style forced viewing of a filmstrip on the dangers of unvalidated data would not over-emphasize how crucial it is that you stringently validate any piece of data coming into your application from an external source. Some of these external sources are obvious: most of the input to your application is probably coming from a web form. But there are lots of other ways data can flow into your programs as well: databases that you share with other people or applications, web services and remote servers, even URLs and their parameters.

As mentioned earlier, Example 7-7 doesn’t indicate what’s wrong with the form if the check in validate_form() fails. Example 7-8 alters validate_form() and show_form() to manipulate and print an array of possible error messages.

// Logic to do the right thing based on
// the request method
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    // If validate_form() returns errors, pass them to show_form()
    if ($form_errors = validate_form()) {
        show_form($form_errors);
    } else {
        process_form();
    }
} else {
    show_form();
}

// Do something when the form is submitted
function process_form() {
    print "Hello, ". $_POST['my_name'];
}

// Display the form
function show_form($errors = ) {
    // If some errors were passed in, print them out
    if ($errors) {
        print 'Please correct these errors: <ul><li>';
        print implode('</li><li>', $errors);
        print '</li></ul>';
    }

    print<<<_HTML_
<form method="POST" action="$_SERVER[PHP_SELF]">
Your name: <input type="text" name="my_name">
<br/>
<input type="submit" value="Say Hello">
</form>
_HTML_;
}

// Check the form data
function validate_form() {
    // Start with an empty array of error messages
    $errors = array();

    // Add an error message if the name is too short
    if (strlen($_POST['my_name']) < 3) {
        $errors[  ] = 'Your name must be at least 3 letters long.';
    }

    // Return the (possibly empty) array of error messages
    return $errors;
}

The code in Example 7-8 takes advantage of the fact that an empty array evaluates to false. The line if ($form_errors = validate_form()) decides whether to call show_form() again and pass it the error array, or to call process_form(). The array that validate_form() returns is assigned to $form_errors. The truth value of the if() test expression is the result of that assignment, which, as you saw in “Understanding true and false”, is the value being assigned. So, the if() test expression is true if $form_errors has some elements in it, and false if $form_errors is empty. If validate_form() encounters no errors, then the array it returns is empty.

It is a good idea to do validation checks on all of the form elements in one pass, instead of redisplaying the form immediately when you find a single element that isn’t valid. A user should find out all of his errors when he submits a form instead of having to submit the form over and over again, with a new error message revealed on each submission. The validate_form() function in Example 7-8 does this by adding an element to $errors for each problem with a form element. Then, show_form() prints out a list of the error messages.

The validation methods shown here all go inside the validate_form() function. If a form element doesn’t pass the test, then a message is added to the $errors array.

if (strlen($_POST['email']) == 0) {
   $errors[] = "You must enter an email address.";
}

$ok = filter_input(INPUT_POST, 'age', FILTER_VALIDATE_INT);
if (is_null($ok) || ($ok === false)) {
    $errors[] = 'Please enter a valid age.';
}

$ok = filter_input(INPUT_POST, 'price', FILTER_VALIDATE_FLOAT);
if (is_null($ok) || ($ok === false)) {
    $errors[] = 'Please enter a valid price.';
}

if (strlen(trim($_POST['name'])) == 0) {
    $errors[] = "Your name is required.";
}

function validate_form() {
    $errors = array();
    $input = array();

    $input['age'] = filter_input(INPUT_POST, 'age', FILTER_VALIDATE_INT);
    if (is_null($input['age']) || ($input['age'] === false)) {
        $errors[] = 'Please enter a valid age.';
    }

    $input['price'] = filter_input(INPUT_POST, 'price', FILTER_VALIDATE_FLOAT);
    if (is_null($input['price']) || ($input['price'] === false)) {
        $errors[] = 'Please enter a valid price.';
    }

    // Use the null coalesce operator in case $_POST['name'] isn't set
    $input['name'] = trim($_POST['name'] ?? '');
    if (strlen($input['name']) == 0) {
        $errors[] = "Your name is required.";
    }

    return array($errors, $input);
}

// Logic to do the right thing based on the request method
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    // If validate_form() returns errors, pass them to show_form()
    list($form_errors, $input) = validate_form();
    if ($form_errors) {
        show_form($form_errors);
    } else {
        process_form($input);
    }
} else {
    show_form();
}

$input['age'] = filter_input(INPUT_POST, 'age', FILTER_VALIDATE_INT,
                             array('options' => array('min_range' => 18,
                                                      'max_range' => 65)));
if (is_null($input['age']) || ($input['age'] === false)) {
    $errors[] = 'Please enter a valid age between 18 and 65.';
}

$input['price'] = filter_input(INPUT_POST, 'price', FILTER_VALIDATE_FLOAT);
if (is_null($input['price']) || ($input['price'] === false) ||
    ($input['price'] < 10.00) || ($input['price'] > 50.00)) {
    $errors[] = 'Please enter a valid price between $10 and $50.';
}

// Make a DateTime object for 6 months ago
$range_start = new DateTime('6 months ago');
// Make a DateTime object for right now
$range_end   = new DateTime();

// 4-digit year is in $_POST['year']
// 2-digit month is in $_POST['month']
// 2-digit day is is $_POST['day']
$input['year'] = filter_input(INPUT_POST, 'year', FILTER_VALIDATE_INT,
                              array('options' => array('min_range' => 1900,
                                                       'max_range' => 2100)));
$input['month'] = filter_input(INPUT_POST, 'month', FILTER_VALIDATE_INT,
                               array('options' => array('min_range' => 1,
                                                        'max_range' => 12)));
$input['day'] = filter_input(INPUT_POST, 'day', FILTER_VALIDATE_INT,
                             array('options' => array('min_range' => 1,
                                                      'max_range' => 31)));
// No need to use === to compare to false since 0 is not a valid
// choice for year, month, or day. checkdate() makes sure that
// the number of days is valid for the given month and year.
if ($input['year'] && input['month'] && input['day'] &&
    checkdate($input['month'], $input['day'], $input['year'])) {
    $submitted_date = new DateTime(strtotime($input['year'] . '-' .
                                             $input['month'] . '-' .
                                             $input['day']));
    if (($range_start > $submitted_date) || ($range_end < $submitted_date)) {
        $errors[] = 'Please choose a date less than six months old.';
    }
} else {
    // This happens if someone omits one of the form parameters or submits
    // something like February 31.
    $errors[] = 'Please enter a valid date.';
}

$input['email'] = filter_input(INPUT_POST, 'email', FILTER_VALIDATE_EMAIL);
if (! $input['email']) {
    $errors[] = 'Please enter a valid email address';
}

$sweets = array('Sesame Seed Puff','Coconut Milk Gelatin Square',
                 'Brown Sugar Cake','Sweet Rice and Meat');

function generate_options($options) {
    $html = '';
    foreach ($options as $option) {
        $html .= "<option>$option</option>\n";
    }
    return $html;
}

// Display the form
function show_form() {
    $sweets = generate_options($GLOBALS['sweets']);
    print<<<_HTML_
<form method="post" action="$_SERVER[PHP_SELF]">
Your Order: <select name="order">
$sweets
</select>
<br/>
<input type="submit" value="Order">
</form>
_HTML_;
}

<form method="post" action="order.php">
Your Order: <select name="order">
<option>Sesame Seed Puff</option>
<option>Coconut Milk Gelatin Square</option>
<option>Brown Sugar Cake</option>
<option>Sweet Rice and Meat</option>

</select>
<br/>
<input type="submit" value="Order">
</form>

$input['order'] = $_POST['order'];
if (! in_array($input['order'], $GLOBALS['sweets'])) {
    $errors[] = 'Please choose a valid order.';
}

$sweets = array('puff' => 'Sesame Seed Puff',
                'square' => 'Coconut Milk Gelatin Square',
                'cake' => 'Brown Sugar Cake',
                'ricemeat' => 'Sweet Rice and Meat');

function generate_options_with_value ($options) {
    $html = '';
    foreach ($options as $value => $option) {
        $html .= "<option value=\"$value\">$option</option>\n";
    }
    return $html;
}


// Display the form
function show_form() {
    $sweets = generate_options_with_value($GLOBALS['sweets']);
    print<<<_HTML_
<form method="post" action="$_SERVER[PHP_SELF]">
Your Order: <select name="order">
$sweets
</select>
<br/>
<input type="submit" value="Order">
</form>
_HTML_;
}

<form method="post" action="order.php">
Your Order: <select name="order">
<option value="puff">Sesame Seed Puff</option>
<option value="square">Coconut Milk Gelatin Square</option>
<option value="cake">Brown Sugar Cake</option>
<option value="ricemeat">Sweet Rice and Meat</option>

</select>
<br/>
<input type="submit" value="Order">
</form>

$input['order'] = $_POST['order'];
if (! array_key_exists($input['order'], $GLOBALS['sweets'])) {
    $errors[] = 'Please choose a valid order.';
}

HTML and JavaScript

Submitted form data that contains HTML or JavaScript can cause big problems. Consider a simple blog application that lets users submit comments on a blog post page and then displays a list of those comments below the blog post. If users behave nicely and enter only comments containing plain text, the page remains benign. One user submits Cool page! I like how you list the different ways to cook fish. When you come along to browse the page, that’s what you see.

The situation is more complicated when the submissions are not just plain text. If an enthusiastic user submits This page <b>rules!!!!</b> as a comment, and it is redisplayed verbatim by the application, then you see rules!!!! in bold when you browse the page. Your web browser can’t tell the difference between HTML tags that come from the application itself (perhaps laying out the comments in a table or a list) and HTML tags that happen to be embedded in the comments that the application is printing.

Although seeing bold text instead of plain text is a minor annoyance, displaying unfiltered user input leaves the application open to giving you a much larger headache. Instead of <b></b> tags, one user’s submission could contain a malformed or unclosed tag (such as <a href=" with no ending " or >) that prevents your browser from displaying the page properly. Even worse, that submission could contain JavaScript code that, when executed by your web browser as you look at the page, does nasty stuff such as send a copy of your cookies to a stranger’s email box or surreptitiously redirect you to another web page.

The application acts as a facilitator, letting a malicious user upload some HTML or JavaScript that is later run by an unwitting user’s browser. This kind of problem is called a cross-site scripting attack because the poorly written blog application allows code from one source (the malicious user) to masquerade as coming from another place (the application hosting the comments).

To prevent cross-site scripting attacks in your programs, never display unmodified external input. Either remove suspicious parts (such as HTML tags) or encode special characters so that browsers don’t act on embedded HTML or JavaScript. PHP gives you two functions that make these tasks simple. The strip_tags() function removes HTML tags from a string, and the htmlentities() function encodes special HTML characters.

Example 7-21 demonstrates strip_tags().

Example 7-21. Stripping HTML tags from a string

// Remove HTML from comments
$comments = strip_tags($_POST['comments']);
// Now it's OK to print $comments
print $comments;

If $_POST['comments'] contains

I
<b>love</b> sweet <div
class="fancy">rice</div> &
tea.

then Example 7-21 prints:

I love sweet rice & tea.

All HTML tags and their attributes are removed, but the plain text between the tags is left intact. The strip_tags() function is very convenient, but it behaves poorly with mismatched < and > characters. For example, it turns I <3 Monkeys into I . It starts stripping once it sees that < and never stops because there’s no corresponding <.

Encoding instead of stripping the tags often gives better results. Example 7-22 demonstrates encoding with htmlentities().

Example 7-22. Encoding HTML entities in a string

$comments = htmlentities($_POST['comments']);
// Now it's OK to print $comments
print $comments;

If $_POST['comments'] contains

I
<b>love</b> sweet <div
class="fancy">rice</div> &
tea

then Example 7-22 prints:

I <b>love</b> sweet <div class="fancy
">rice</div> & tea.

The characters that have a special meaning in HTML (<, >, &, and ") have been changed into their entity equivalents:

• < to <
• > to >
• & to &
• " to "

When a browser sees <, it prints out a < character instead of thinking “OK, here comes an HTML tag.” This is the same idea (but with a different syntax) as escaping a " or $ character inside a double-quoted string, as you saw in “Text”. Figure 7-4 shows what the output of Example 7-22 looks like in a web browser.

In most applications, you should use htmlentities() to sanitize external input. This function doesn’t throw away any content, and it also protects against cross-site scripting attacks. A discussion board where users post messages, for example, about HTML (“What does the <div> tag do?”) or algebra (“If x<y, is 2x>z?”) wouldn’t be very useful if those posts were run through strip_tags(). The questions would be printed as “What does the tag do?” and “If xz?”

Figure 7-4. Displaying entity-encoded text

Displaying Default Values

Sometimes, you want to display a form with a value already in a text box or with preselected checkboxes, radio buttons, or <select> menu items. Additionally, when you redisplay a form because of an error, it is helpful to preserve any information that a user has already entered. Example 7-23 shows the code to do this. It belongs at the beginning of show_form() and makes $defaults the array of values to use with the form elements.

if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    $defaults = $_POST;
} else {
    $defaults = array('delivery'  => 'yes',
                      'size'      => 'medium',
                      'main_dish' => array('taro','tripe'),
                      'sweet'     => 'cake');
}

If $_SERVER['REQUEST_METHOD'] is POST, that means the form has been submitted. In that case, the defaults should come from whatever the user submitted. Otherwise, you can set your own defaults. For most form parameters, the default is a string or a number. For form elements that can have more than one value, such as the multivalued <select> menu main_dish, the default value is an array.

After setting the defaults, provide the appropriate value from $defaults when printing out the HTML tag for the form element. Remember to encode the defaults with htmlentities() when necessary in order to prevent cross-site scripting attacks. Because of the structure of the HTML tags, you need to treat text boxes, <select> menus, text areas, and checkboxes/radio buttons differently.

For text boxes, set the value attribute of the <input> tag to the appropriate element of $defaults. Example 7-24 shows how to do this.

print '<input type="text" name="my_name" value="' .
      htmlentities($defaults['my_name']). '">';

For multiline text areas, put the entity-encoded value between the <textarea> and </textarea> tags, as shown in Example 7-25.

print '<textarea name="comments">';
print htmlentities($defaults['comments']);
print '</textarea>';

For <select> menus, add a check to the loop that prints out the <option> tags so that it prints a selected attribute when appropriate. Example 7-26 contains the code to do this for a single-valued <select> menu.

$sweets = array('puff' => 'Sesame Seed Puff',
                'square' => 'Coconut Milk Gelatin Square',
                'cake' => 'Brown Sugar Cake',
                'ricemeat' => 'Sweet Rice and Meat');

print '<select name="sweet">';
// > is the option value, $label is what's displayed
foreach ($sweets as $option => $label) {
    print '<option value="' .$option .'"';
    if ($option == $defaults['sweet']) {
        print ' selected';
    }
    print "> $label</option>\n";
}
print '</select>';

To set defaults for a multivalued <select> menu, you need to convert the array of defaults into an associative array in which each key is a choice that should be selected. Then, print the selected attribute for the options found in that associative array. Example 7-27 demonstrates how to do this.

$main_dishes = array('cuke' => 'Braised Sea Cucumber',
                     'stomach' => "Sauteed Pig's Stomach",
                     'tripe' => 'Sauteed Tripe with Wine Sauce',
                     'taro' => 'Stewed Pork with Taro',
                     'giblets' => 'Baked Giblets with Salt',
                     'abalone' => 'Abalone with Marrow and Duck Feet');

print '<select name="main_dish[]" multiple>';

$selected_options = array();
foreach ($defaults['main_dish'] as $option) {
    $selected_options[$option] = true;
}

// print out the <option> tags
foreach ($main_dishes as $option => $label) {
    print '<option value="' . htmlentities($option) . '"';
    if (array_key_exists($option, $selected_options)) {
        print ' selected';
    }
    print '>' . htmlentities($label) . '</option>';
    print "\n";
}
print '</select>';

For checkboxes and radio buttons, add a checked attribute to the <input> tag. The syntax for checkboxes and radio buttons is identical except for the type attribute. Example 7-28 prints a default-aware checkbox named delivery and three default-aware radio buttons, each named size and each with a different value.

print '<input type="checkbox" name="delivery" value="yes"';
if ($defaults['delivery'] == 'yes') { print ' checked'; }
print '> Delivery?';

$checkbox_options = array('small' => 'Small',
                          'medium' => 'Medium',
                          'large' => 'Large');

foreach ($checkbox_options as $value => $label) {
    print '<input type="radio" name="size" value="'.$value.'"';
    if ($defaults['size'] == $value) { print ' checked'; }
    print "> $label ";
}

Putting It All Together

Turning the humble web form into a feature-packed application with data validation, printing default values, and processing the submitted results might seem like an intimidating task. To ease your burden, this section contains a complete example of a program that does it all:

• Displaying a form, including default values
• Validating the submitted data
• Redisplaying the form with error messages and preserved user input if the submitted data isn’t valid
• Processing the submitted data if it is valid

The do-it-all example relies on a class containing some helper functions to simplify form element display and processing. This class is listed in Example 7-29.

class FormHelper {
    protected $values = array();

    public function __construct($values = array()) {
        if ($_SERVER['REQUEST_METHOD'] == 'POST') {
            $this->values = $_POST;
        } else {
            $this->values = $values;
        }
    }

    public function input($type, $attributes = array(), $isMultiple = false) {
        $attributes['type'] = $type;
        if (($type == 'radio') || ($type == 'checkbox')) {
            if ($this->isOptionSelected($attributes['name'] ?? null,
                                        $attributes['value'] ?? null)) {
                $attributes['checked'] = true;
            }
        }
        return $this->tag('input', $attributes, $isMultiple);
    }

    public function select($options, $attributes = array()) {
        $multiple = $attributes['multiple'] ?? false;
        return
            $this->start('select', $attributes, $multiple) .
            $this->options($attributes['name'] ?? null, $options) .
            $this->end('select');
    }

    public function textarea($attributes = array()) {
        $name = $attributes['name'] ?? null;
        $value = $this->values[$name] ?? '';
        return $this->start('textarea', $attributes) .
               htmlentities($value) .
               $this->end('textarea');
    }

    public function tag($tag, $attributes = array(), $isMultiple = false) {
        return "<$tag {$this->attributes($attributes, $isMultiple)} />";
    }
    public function start($tag, $attributes = array(), $isMultiple = false) {
        // <select> and <textarea> tags don't get value attributes on them
        $valueAttribute = (! (($tag == 'select')||($tag == 'textarea')));
        $attrs = $this->attributes($attributes, $isMultiple, $valueAttribute);
        return "<$tag $attrs>";
    }
    public function end($tag) {
        return "</$tag>";
    }

    protected function attributes($attributes, $isMultiple,
                                  $valueAttribute = true) {
        $tmp = array();
        // If this tag could include a value attribute and it
        // has a name and there's an entry for the name
        // in the values array, then set a value attribute
        if ($valueAttribute && isset($attributes['name']) &&
            array_key_exists($attributes['name'], $this->values)) {
            $attributes['value'] = $this->values[$attributes['name']];
        }
        foreach ($attributes as $k => $v) {
            // True boolean value means boolean attribute
            if (is_bool($v)) {
                if ($v) { $tmp[] = $this->encode($k); }
            }
            // Otherwise k=v
            else {
                $value = $this->encode($v);
                // If this is an element that might have multiple values,
                // tack [] onto its name
                if ($isMultiple && ($k == 'name')) {
                    $value .= '[]';
                }
                $tmp[] = "$k=\"$value\"";
            }
        }
        return implode(' ', $tmp);
    }

    protected function options($name, $options) {
        $tmp = array();
        foreach ($options as $k => $v) {
            $s = "<option  value=\"{$this->encode($k)}\"";
            if ($this->isOptionSelected($name, $k)) {
                $s .= ' selected';
            }
            $s .= ">{$this->encode($v)}</option>";
            $tmp[] = $s;
        }
        return implode('', $tmp);
    }

    protected function isOptionSelected($name, $value) {
        // If there's no entry for $name in the values array,
        // then this option can't be selected
        if (! isset($this->values[$name])) {
            return false;
        }
        // If the entry for $name in the values array is itself
        // an array, check if $value is in that array
        else if (is_array($this->values[$name])) {
            return in_array($value, $this->values[$name]);
        }
        // Otherwise, compare $value to the entry for $name
        // in the values array
        else {
            return $value == $this->values[$name];
        }
    }

    public function encode($s) {
        return htmlentities($s);
    }
}

Methods in Example 7-29 incorporate the appropriate logic discussed in “Displaying Default Values” for particular kinds of form elements. Because the form code in Example 7-30 has a number of different elements, it’s easier to put the element display code in functions that are called repeatedly than to duplicate the code each time you need to print a particular element.

The FormHelper constructor should be passed an associative array of default values for arguments. If the request method is not POST, it uses this array to figure out appropriate defaults. Otherwise, it uses the submitted data as the basis for defaults.

FormHelper’s input() method generates appropriate HTML for any <input/> element. Its required first argument is the type of the element (such as submit, radio, or text). The optional second argument is an associative array of element attributes (such as ['name' => 'meal']). The optional third argument should be true if you’re generating HTML for an element that can have multiple values, such as a checkbox.

The select() method generates HTML for a <select> menu. Its first argument is an array of options for the menu and its optional second argument is an associative array of attributes for the <select> tag. For a multivalued <select> menu, make sure to include 'multiple' => true in the array of attributes passed as the second argument.

The textarea() method generates HTML for a <textarea>. It just takes a single argument: an associative array of attributes for the tag.

Those three methods should take care of the majority of your form display needs, but in case you need other tags or special treatment, you can use the tag(), start(), and end() methods.

The tag() method produces HTML for an entire self-closing HTML tag such as <input/>. Its arguments are the name of the tag, an optional array of attributes, and true if the tag can accept multiple values. The input() method uses tag() to actually generate the proper HTML.

The start() and end() methods are for elements with separate start and end tags. The start() method generates the element start tag, accepting the familiar trio of tag name, attributes, and multiple flag as arguments. The end() method just accepts a tag name for an argument and returns the closing tag HTML. For example, if you’re using an HTML tag such as <fieldset>, you could call start('fieldset',['name' => 'adjustments']), then emit HTML that should be inside the field set, then call end('fieldset').

The rest of the class is devoted to methods that help to generate the HTML and are not meant to be called from outside the class. The attributes() method formats a set of attributes to be appropriately included inside an HTML tag. Using the defaults set up in the object, it inserts an appropriate value attribute when necessary. It also takes care of appending [] to the element name if the element can accept multiple values and assures that all attribute values are appropriately encoded with HTML entities.

The options() method handles formatting the <option> tags for a <select> menu. With the help of isOptionSelected(), it figures out which options should be marked as selected and does proper HTML entity encoding.

The encode() method is a wrapper for PHP’s built-in htmlentities() method. It’s public so that other code can use it to make your entity encoding consistent.

The code in Example 7-30 relies on the FormHelper class and displays a short food-ordering form. When the form is submitted correctly, it shows the results in the browser and emails them to an address defined in process_form() (presumably to the chef, so he can start preparing your order). Because the code jumps in and out of PHP mode, it includes the <?php start tag at the beginning of the example and the ?> closing tag at the end to make things clearer.

<?php

// This assumes FormHelper.php is in the same directory as
// this file.
require 'FormHelper.php';

// Set up the arrays of choices in the select menus.
// These are needed in display_form(), validate_form(),
// and process_form(), so they are declared in the global scope.
$sweets = array('puff' => 'Sesame Seed Puff',
                'square' => 'Coconut Milk Gelatin Square',
                'cake' => 'Brown Sugar Cake',
                'ricemeat' => 'Sweet Rice and Meat');

$main_dishes = array('cuke' => 'Braised Sea Cucumber',
                     'stomach' => "Sauteed Pig's Stomach",
                     'tripe' => 'Sauteed Tripe with Wine Sauce',
                     'taro' => 'Stewed Pork with Taro',
                     'giblets' => 'Baked Giblets with Salt',
                     'abalone' => 'Abalone with Marrow and Duck Feet');

// The main page logic:
// - If the form is submitted, validate and then process or redisplay
// - If it's not submitted, display
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    // If validate_form() returns errors, pass them to show_form()
    list($errors, $input) = validate_form();
    if ($errors) {
        show_form($errors);
    } else {
        // The submitted data is valid, so process it
        process_form($input);
    }
} else {
    // The form wasn't submitted, so display
    show_form();
}

function show_form($errors = array()) {
    $defaults = array('delivery' => 'yes',
                      'size'     => 'medium');
    // Set up the $form object with proper defaults
    $form = new FormHelper($defaults);

    // All the HTML and form display is in a separate file for clarity
    include 'complete-form.php';
}

function validate_form() {
    $input = array();
    $errors = array();

    // name is required
    $input['name'] = trim($_POST['name'] ?? '');
    if (! strlen($input['name'])) {
        $errors[] = 'Please enter your name.';
    }
    // size is required
    $input['size'] = $_POST['size'] ?? '';
    if (! in_array($input['size'], ['small','medium','large'])) {
        $errors[] = 'Please select a size.';
    }
    // sweet is required
    $input['sweet'] = $_POST['sweet'] ?? '';
    if (! array_key_exists($input['sweet'], $GLOBALS['sweets'])) {
        $errors[] = 'Please select a valid sweet item.';
    }
    // exactly two main dishes required
    $input['main_dish'] = $_POST['main_dish'] ?? array();
    if (count($input['main_dish']) != 2) {
        $errors[] = 'Please select exactly two main dishes.';
    } else {
        // we know there are two main dishes selected, so make sure they are
        // both valid
        if (! (array_key_exists($input['main_dish'][0], $GLOBALS['main_dishes']) &&
               array_key_exists($input['main_dish'][1], $GLOBALS['main_dishes']))) {
            $errors[] = 'Please select exactly two valid main dishes.';
        }
    }
    // if delivery is checked, then comments must contain something
    $input['delivery'] = $_POST['delivery'] ?? 'no';
    $input['comments'] = trim($_POST['comments'] ?? '');
    if (($input['delivery'] == 'yes') && (! strlen($input['comments']))) {
        $errors[] = 'Please enter your address for delivery.';
    }

    return array($errors, $input);
}

function process_form($input) {
    // look up the full names of the sweet and the main dishes in
    // the $GLOBALS['sweets'] and $GLOBALS['main_dishes'] arrays
    $sweet = $GLOBALS['sweets'][ $input['sweet'] ];
    $main_dish_1 = $GLOBALS['main_dishes'][ $input['main_dish'][0] ];
    $main_dish_2 = $GLOBALS['main_dishes'][ $input['main_dish'][1] ];
    if (isset($input['delivery']) && ($input['delivery'] == 'yes')) {
        $delivery = 'do';
    } else {
        $delivery = 'do not';
    }
    // build up the text of the order message
    $message=<<<_ORDER_
Thank you for your order, {$input['name']}.
You requested the {$input['size']} size of $sweet, $main_dish_1, and $main_dish_2.
You $delivery want delivery.
_ORDER_;
    if (strlen(trim($input['comments']))) {
        $message .= 'Your comments: '.$input['comments'];
    }

    // send the message to the chef
    mail('chef@restaurant.example.com', 'New Order', $message);
    // print the message, but encode any HTML entities
    // and turn newlines into <br/> tags
    print nl2br(htmlentities($message, ENT_HTML5));
}
?>

There are four parts to the code in Example 7-30: the code in the global scope at the top of the example, the show_form() function, the validate_form() function, and the process_form() function.

The global scope code does three things. The first is that it loads the FormHelper class from its separate file. Then, it sets up two arrays that describe the choices in the form’s two <select> menus. Because these arrays are used by each of the show_form(), validate_form(), and process_form() functions, they need to be defined in the global scope. The global code’s last task is to process the if() statement that decides what to do: display, validate, or process the form.

Displaying the form is accomplished by show_form(). First, the function makes $defaults an array of default values. This array is passed to FormHelper’s constructor, so the $form object uses the right default values. Then, show_form() hands off control to another file, complete-form.php, which contains the actual HTML and PHP code to display the form. Putting the HTML in a separate file for a big program like this makes it easier to digest everything and also easier for the two files to be changed independently. The contents of complete-form.php are shown in Example 7-31.

<form method="POST" action="<?= $form->encode($_SERVER['PHP_SELF']) ?>">
<table>
    <?php if ($errors) { ?>
        <tr>
            <td>You need to correct the following errors:</td>
            <td><ul>
                <?php foreach ($errors as $error) { ?>
                    <li><?= $form->encode($error) ?></li>
                <?php } ?>
            </ul></td>
    <?php }  ?>

    <tr><td>Your Name:</td><td><?= $form->input('text', ['name' => 'name']) ?>
    </td></tr>

    <tr><td>Size:</td>
        <td><?= $form->input('radio',['name' => 'size', 'value' => 'small']) ?>
        Small <br/>
            <?= $form->input('radio',['name' => 'size', 'value' => 'medium']) ?>
            Medium <br/>
            <?= $form->input('radio',['name' => 'size', 'value' => 'large']) ?> 
            Large <br/>
        </td></tr>

    <tr><td>Pick one sweet item:</td>
        <td><?= $form->select($GLOBALS['sweets'], ['name' => 'sweet']) ?></td>
    </tr>

    <tr><td>Pick two main dishes:</td>
        <td><?= $form->select($GLOBALS['main_dishes'], ['name' => 'main_dish',
                                                        'multiple' => true]) ?></td>
    </tr>

    <tr><td>Do you want your order delivered?</td>
        <td><?= $form->input('checkbox',['name' => 'delivery', 
                                                     'value' => 'yes'])
        ?> Yes </td></tr>

    <tr><td>Enter any special instructions.<br/>
        If you want your order delivered, put your address here:</td>
        <td><?= $form->textarea(['name' => 'comments']) ?></td></tr>

    <tr><td colspan="2" align="center">
    <?=$form->input('submit', ['value' => 'Order']) ?>
    </td></tr>

</table>
</form>

The code in complete-form.php executes as if it were part of the show_form() function. This means that local variables in the function, such as $errors and $form, are available in complete-form.php. Like all included files, complete-form.php starts outside of any PHP tags, so it can print some plain HTML and then jump into PHP mode when it needs to call methods or use PHP logic. The code here uses the special short echo tag (<?=) as a concise way to display the results of various method calls. Starting a PHP block with <?= means exactly the same thing as starting a PHP block with <php echo. Since our various FormHelper methods return HTML that should be displayed, this makes a handy way to build up the HTML for the form.

Back in the main file, the validate_form() function builds an array of error messages if the submitted form data doesn’t meet appropriate criteria. Note that the checks for size, sweet, and main_dish don’t just look to see whether something was submitted for those parameters, but also that what was submitted is a valid value for the particular parameter. For size, this means that the submitted value must be small, medium, or large. For sweet and main_dish, this means that the submitted values must be keys in the global $sweets or $main_dishes arrays. Even though the form contains default values, it’s still a good idea to validate the input. Someone trying to break into your website could bypass a regular web browser and construct a request with an arbitrary value that isn’t a legitimate choice for the <select> menu or radio button set.

Lastly, process_form() takes action when the form is submitted with valid data. It builds a string, $message, that contains a description of the submitted order. Then it emails $message to chef@restaurant.example.com and prints it. The built-in mail() function sends the email message. Before printing $message, process_form() passes it through two functions. The first is htmlentities(), which, as you’ve already seen, encodes any special characters as HTML entities. The second is nl2br(), which turns any newlines in $message into HTML <br> tags. Turning newlines into <br> tags makes the line breaks in the message display properly in a web browser.

Chapter Summary

This chapter covered:

• Understanding the conversation between the web browser and web server that displays a form, processes the submitted form parameters, and then displays a result
• Making the connection between the <form> tag’s action attribute and the URL to which form parameters are submitted
• Using values from the $_SERVER auto-global array
• Accessing submitted form parameters in the $_GET and $_POST auto-global arrays
• Accessing multivalued submitted form parameters
• Using the show_form(), validate_form(), and process_form() functions to modularize form handling
• Displaying error messages with a form
• Validating form elements: required elements, integers, floating-point numbers, strings, date ranges, email addresses, and <select> menus
• Defanging or removing submitted HTML and JavaScript before displaying it
• Displaying default values for form elements
• Using helper functions to display form elements

Exercises

1. What does $_POST look like when the following form is submitted with the third option in the Braised Noodles menu selected, the first and last options in the Sweet menu selected, and 4 entered into the text box?

   <form method="POST" action="order.php">
   Braised Noodles with: <select name="noodle">
   <option>crab meat</option>
   <option>mushroom</option>
   <option>barbecued pork</option>
   <option>shredded ginger and green onion</option>
   </select>
   <br/>
   Sweet: <select name="sweet[]" multiple>
   <option value="puff"> Sesame Seed Puff
   <option value="square"> Coconut Milk Gelatin Square
   <option value="cake"> Brown Sugar Cake
   <option value="ricemeat"> Sweet Rice and Meat
   </select>
   <br/>
   Sweet Quantity: <input type="text" name="sweet_q">
   <br/>
   <input type="submit" name="submit" value="Order">
   </form>
   

2. Write a process_form() function that prints out all submitted form parameters and their values. You can assume that form parameters have only scalar values.
3. Write a program that does basic arithmetic. Display a form with text box inputs for two operands and a <select> menu to choose an operation: addition, subtraction, multiplication, or division. Validate the inputs to make sure that they are numeric and appropriate for the chosen operation. The processing function should display the operands, the operator, and the result. For example, if the operands are 4 and 2 and the operation is multiplication, the processing function should display something like 4 * 2 = 8.
4. Write a program that displays, validates, and processes a form for entering information about a package to be shipped. The form should contain inputs for the from and to addresses for the package, dimensions of the package, and weight of the package. The validation should check (at least) that the package weighs no more than 150 pounds and that no dimension of the package is more than 36 inches. You can assume that the addresses entered on the form are both US addresses, but you should check that a valid state and a zip code with valid syntax are entered. The processing function in your program should print out the information about the package in an organized, formatted report.
5. (Optional) Modify your process_form() function that enumerates all submitted form parameters and their values so that it correctly handles submitted form parameters that have array values. Remember, those array values could themselves contain arrays.