Chapter 3. Functions
A function is a named block of code that performs a specific task, possibly acting upon a set of values given to it, or parameters, and possibly returning a single value. Functions save on compile time—no matter how many times you call them, functions are compiled only once for the page. They also improve reliability by allowing you to fix any bugs in one place, rather than everywhere you perform a task, and they improve readability by isolating code that performs specific tasks.
This chapter introduces the syntax of function calls and function definitions and discusses how to manage variables in functions and pass values to functions (including pass-by-value and pass-by-reference). It also covers variable functions and anonymous functions.
3.1. Calling a Function
$some_value = function_name( [ parameter, ... ] );
The number of parameters a function requires differs from function to function (and, as we'll see later, may even vary for the same function). The parameters supplied to the function may be any valid expression and should be in the specific order expected by the function. A function's documentation will tell you what parameters the function expects and what values you can expect to be returned.
// strlen( ) is a built-in function that returns the length of a string $length = strlen("PHP"); // $length is now 3 // sin() and asin( ) are the sine and arcsine math functions $result = sin(asin(1)); // $result is the sine of arcsin(1), or 1.0 // unlink( ) deletes a file $result = unlink("functions.txt"); // false if unsuccessful
In the first example, we give an argument, "PHP", to the function strlen( ), which gives us the number of characters in the string it's given. In this case, it returns 3, which is assigned to the variable $length. This is the simplest and most common way to use a function.
The second example passes the result of asin(1) to the sin( ) function. Since the sine and arcsine functions are reflexive, taking the sine of the arcsine of any value will always return that same value.
In the final example, we give a filename to the unlink( ) function, which attempts to delete the file. Like many functions, it returns false when it fails. This allows you to use another built-in function, die( ), and the short-circuiting property of the logic operators. Thus, this example might be rewritten as:
$result = unlink("functions.txt") or die("Operation failed!");
The unlink( ) function, unlike the other two examples, affects something outside of the parameters given to it. In this case, it deletes a file from the filesystem. All such side effects of a function should be carefully documented.
PHP has a huge array of functions already defined for you to use in your programs. Everything from database access, to creating graphics, to reading and writing XML files, to grabbing files from remote systems can be found in PHP's many extensions. Chapter 14 goes into detail on how to add new extensions to PHP, the built-in functions are described in detail in Appendix A, and an overview of PHP's extensions can be found in Appendix B.
Copyright © 2003 O'Reilly & Associates. All rights reserved.