Chapter 6: Writing and Editing

Functions

What the heck is a function? I'm glad you asked that; it shows you're paying attention. A function is a block of code that is treated as if it were a single object. For instance, if you have a function that writes data to a database, it would look something like this:

function write_data {
    # code to actually write to the database goes here
    # if you want the function to send back some value
    # when it finishes, use a return statement like this:
    # return ($success);
}

This line would make the function run:

write_data();

If a function will return some value, that value can be saved in a variable for later use, as in this line:

$result = write_data();

Functions can be reused! Once you've written or found a really useful function you can use it in another program just by copying and pasting it in. Add the code to your script and call it using either one of the methods shown above.

You'll see examples of scripts with functions and calls to them later in the book. When you put a script together, the functions are nearly always listed after the main body.

Built-in functions

PHP makes your life easier by providing a huge number of built-in functions. The great thing about that is that you don't have to write your own functions for a lot of common jobs. This makes the code you write shorter and easier to understand. You'll see a lot of these functions used in the examples in this book.

Before we go any farther, let's look at a couple of the really important built-in functions. The header( ) function lets you load a web page, call another script and more. Anything you can locate with a URL can be called up with header( ). Here's the definition:

boolean header(string http_header)

First, it's a boolean function because it can only return a value of TRUE(1) or FALSE(0). Boolen refers to logic functions that only understand ones and zeroes. Second, it's capable of sending any type of header. The most common header is a Location: which send the user to a web page or another script. Here's an example of that:

header("Location: http://www.anothersite.com");

Sometimes the location where you want the user to go isn't always the same. Sometimes it's the same page or script but with a query string that may have different items or values from time to time. Not a problem! You can call header() with a variable in place of the URL, like this:

$url = "http://www.anothersite.com";

# before your code calls header(), you can add a query string if you want to
$url .= "?id=$aff_id";

# notice that I used a variable to hold the value I wanted id to have
$url .= "&email=$email;

# now I've added another item to the query string. You can do it in one step
# but I wanted you to see how it can be broken down in case you're not using
# exactly the same items every time. Don't forget the & if you're putting
# more than one item in the query string. Each item after the first one will
# be preceded by an &
header("Location: $url");

You'll learn a lot more about query strings in Chapter 9 but for now just remember that a query string is just a ? followed by one or more item=value pairs. The items are separated by an & so that PHP can figure out where one pair ends and another pair starts.

What if you wanted to call a function of the operating system itself (Linux, Windows, etc.)? Suppose you wanted to give a system command to change file permissions, delete a file, lock or unlock a file, etc. There's a built-in function for that. It's:

string system(string command, integer return)

The system( ) function normally returns a string, so it's type is string. The command argument is the command you're giving the system to perform. If you've ever used Run->cmd on a Windows computer, you've seen a small window open that will accept system commands. The system() function lets you do that from inside a script or program.

The return argument is optional. When used, the value returned by the system() function is whatever value the command returned. If you don't want anything to be sent to the browser, don't use system(). There's another function called exec( ) that defaults to no output. It also lets you send all the output to the screen if that's what you want to do.

Let's take a simple example first. Suppose you wanted to list all the files in a folder with a complete set of file details and show the line for the very last file. The Unix/Linux command ls -l would look up all the details on every file in a folder and show you all of it. ls is the Unix command for "list all files in this folder" and the -l switch means "display the long, detailed format and not just the filenames."

Here's how that would look in PHP:

system("ls-l");

In this example, the command is inside double-quotes and then enclosed in parentheses. No return argument was given so we will display the last line of the folder listing on the screen. That's how you normally use system().

Be very careful when using system() in your code! If there's any data supplied by a user that could be passed to this function, you web server will act on it. The best defense is to assume that this could happen and that it could be a disaster. You can pass user-supplied data to the escapeshellcmd( ) function before it gets to system() and that will prevent users from running system commands on your server. Here's that function:

string escapeshellcmd(string command)

The escapeshellcmd( ) function expects to get a string, disable any system(or shell) commands and return a safe string. Here's an example:

# Our intention is to print "Mike" on the screen but someone has tried
# to slip in the command that would delete all the files in this folder
# Notice that the echo() requires quotes so that it knows its argument is
# a string and that the assignment of the whole command string to $cmd also
# requires quotes. That's why we have single-quotes inside of double-quotes.

$cmd = "echo 'Mike; rm *'";

# we defend our web server by passing the contents of $cmd through escapeshellcmd()

$cmd = escapeshellcmd($cmd);

Making decisions: control structures

Software doesn't always go directly from point A to point B to point C, etc. Many times decisions must be made and actions taken based on the result. So we have a variety of ways to make a decision between two or more paths to follow. Here are the most common ways of making decisions.

Copyright © 2004 Steve Humphrey