Defining your own functions

PHP comes with a lot of functions, and also you can develop your own functions to do exactly what is convenient for you.
To define a function, you use the keword function, followed by the pair of ( ), with "dummy" arguments inside. These stand for whatever values are given as actual arguments when the function is called.
Then follows the body of the function -- what it does, in {curly brackets}.

Function arguments are normaly copied to the "dummy" names. A function may return a result. We have seen that htmlspecialchars takes a string argument, and returns a modified string as a result. Here is a function that returns the sales tax on a purchase:

function salestax ($purchase)
{	$gst = $purchase * 0.05;
	$tvq = ($purchase + $gst) * 0.095;	// Quebec tax
	return $gst + $tvq;
}

The variables $purchase, $gst, and $tvq have local scope. They cease to exist when the function returns.

Modifiable arguments

Sometimes we may want a function to change the value of an actual argument. In this case, a copy won't do, as the changed copy would be lost. So it is possible to ask that a reference (or address) be used to connect the function to the desired argument. To indicate this, put an ampersand (&) in front of the "dummy" argument, in the definition.
Note that the actual argument must be a variable.
Here, the "badnews" function changes the cost from what is marked by the store, to what you actually end up paying:

function badnews( & $cost)
{	$cost = $cost + salestax($cost);
}		
$toothbrush = 1.99;
badnews($toothbrush);
print "You must pay $toothbrush for your toothbrush";

Suppose you want to accumulate lines of text, perhaps to write them all to a file. Here is a function that will do this, note that the (first) argument is modified by adding the $moretext and a newline to the end:

function add_plain ( & $lines, $moretext)
{
	$lines = "$lines$moretext\n";
}

Optional arguments

You may have noticed that many functions have optional arguments. These must come at the end of the list. If a value is not given, the definition supplies a default value. Suppose we normally give a 2% discount, but occasionally want to give more (or none)

function discount (& $price, $percent = 2.0)
{
 $price = $price - $price * $percent/100;  
}

A function example:

The purpose of these functions is to accumulate lines of text, by taking some more text (last argument), converting it to html encoding, and adding it to the end of some existing text, given as the first argument.
When you are all done, you can print (echo) all the form data thus accumulated.

Having your HTML, and plain text too:

So this will make it "easy" to echo back your form results to the submitter. But you'll have to keep a plain text copy for writing to a log file, or sending in an email. So I have included an optional last argument, which would be the variable for accumulating a plain text version. This should make it simple to add to your log. Generally, each call ends a line in the $plain value, if it is passed.

You may use any of these functions simply by including them with the require() function. You do not have to copy them to your directory or into your file.

add_html(& $html, $moretext [, & $plain])

The intended use is to produce a mult-line message that has safely escaped all the dangerous characters, and added <br> tags where there were newlines. This message may then be used more than once, perhaps echoed back, written to a log, or sent as a mail message. You will get a safe html version, and optionally a plain text version. In the example

require('/home/jensen/addhtml.php');
add_tag_html	($mess, 'h3','example of add_html & "escaping"', $logtext);  // see below
add_html ($mess, "<pre> tags are red\n<strong> tags are blue\n& so are you\n", $logtext);
add_html ($mess, "Your email $email will not appear in our log\n");
add_plain ($mess, "Text <em>as is </em>");

it escapes the special characters and then adds <br> tags, using the functions we saw in the last chapter. The third argument, if present, is added to just like add_plain. [If no third argument, NULL means do nothing.]

function add_html ( & $html, $moretext, & $plain = NULL)
{
	$h = nl2br( htmlspecialchars($moretext) );
	$html .= "$h\n";
	$plain .= "$moretext\n";  // ignored if no third arg!
}

See full code of all these functions

add_tag_html(& $html, $tag, $moretext [, & $plain])

Does the same thing and additionally adds a pair of html tags around the new text. If $plain is present, it only gets the unmodified $moretext and a newline

	add_tag_html	($mess, 'h3','example of add_html & "escaping"');

add_tag(& $html, $tag [, & $plain])

Adds a single html tag to $html. If $plain is present, it just gets a newline.

	add_tag	($mess, 'table border=2');
	add_tag	($mess, 'tr', $plain);

add_plain(& $plain, $moretext)

This only adds a plain text line, with a newline character at the end. You could use it for something, you only want on your log file, such as the date.

	add_plain ($somelog, date ("j M Y H:i");
	add_plain ($mess, "Text <em>as is </em>");

Finally, here is the result of executing the example, $mess as seen by "view source"

  <h3>example of add_html &amp; &quot;escaping&quot;
  </h3>
&lt;pre&gt; tags are red<br />
&lt;strong&gt; tags are blue<br />
&amp; so are you<br />

Your email me@here.ca will not appear in our log<br />

Text <em>as is </em>

Which is rendered in HTML as follows:

example of add_html & "escaping"

<pre> tags are red
<strong> tags are blue
& so are you
Your email me@here.ca will not appear in our log
Text as is

And $logtext will contain as plain text:

example of add_html & "escaping"
<pre> tags are red
<strong> tags are blue
& so are you