The fi rst two elements of the array will always be . and .. signifying this directory and the parent directory, respectively. The remaining elements are the names of the fi les and directories in the specifi ed directory in ascending alphabetical order. Note that fi les and directories are not distinguished. Also note that only the 'top-level' of directories are shown. The sub-directories of 'members' and 'buildings' are not listed.
7.9 Summary of Functions
This is a reference list of the functions described in this chapter. There are other less important functions which can be found in PHP reference material if they are needed.
Type
returned Function name and arguments Description
logical* chdir(dir) Change to new current directory (returns TRUE for success or FALSE for failure) logical* chmod(fi le/dir,mode) Change protection mode of specifi ed fi le or
directory (returns TRUE for success or FALSE for failure)
string dirname(fi le/dir) Return path of fi le or directory
array explode(string1,string2) Divides up string2 into parts separated by substring string1 and converts them into the elements of an array
logical is_dir(fi le/dir) Exists and is a directory logical is_fi le(fi le/dir) Exists and is a fi le
logical is_readable(fi le/dir) File or directory exists and is readable logical is_writable(fi le/dir) File or directory exists and is writeable logical is_writeable(fi le/dir) File or directory exists and is writeable logical* fclose(fi lepointer) Closes fi le (returns TRUE for success or
FALSE for failure) array fi le(fi le) Convert text fi le to array logical fi le_exists(fi le/dir) File or directory exists
integer fi lesize(fi le) Returns size of fi le in bytes (i.e. characters) of
110
Type
returned Function name and arguments Description integer* fprintf(fi lepointer,format
specifi er, var1, var2, …)
Prints a string in formatted form. (Returns the number of bytes written.)
string fread(fi lepointer,integer) Read specifi ed number of characters from a text fi le or up to the end of fi le, whichever is less
integer* fwrite(fi lepointer,string) Write to specifi ed text fi le
(Returns number of bytes written or FALSE on error)
string getcwd() Returns the absolute address of the working directory
string implode(string,array) Combines the elements of the array into a string separated by substring string1 logical* mkdir(dir,mode) Create directory with specifi ed name and path
with specifi ed protection mode (returns TRUE for success or FALSE for failure)
array pathinfo(fi le/dir) Return associative array of components logical* rename(fi le/dir,fi le/dir) Rename fi le or a directory (including its
contents). This can involve moving the fi le or directory to a different parent directory (returns TRUE for success or FALSE for failure) logical* rmdir(dir) Delete directory with specifi ed name and path
(returns TRUE for success or FALSE for failure)
array scandir(dir) Return indexed array of directory contents (top-level only)
* Function generally used in 'standalone' mode fi le: address of a fi le, relative to the current directory dir: address of a directory, relative to the current directory
fi le/dir: address of either a fi le or a directory, relative to the current directory
Note: absolute addresses such as /public_html/buildings/main.php are also permitted, but using these is not recommended.
Chapter Summary
This chapter introduces the idea of a website as a collection of fi les organised in a hierarchical structure of directories and sub-directories. The use of rela-tive and absolute addresses is explained and the path to a fi le or directory is defi ned. Functions for writing data to text fi les and reading data stored in that form are described. The use of the explode and implode functions to change a string such as a record in a text fi le to the elements of an array or vice versa is illustrated. The topic of fi le and directory protections is introduced and func-tions for testing the existence and protection status of fi les are described. The chapter ends with descriptions of other functions that can be applied to fi les and directories and functions for decomposing a relative fi le or directory name into its component parts and for fi nding all the contents of a directory.
7 Using Files
Practical Exercise 7
Using the scandir function write a PHP script which takes a variable $path contain-ing the path to a directory from the current directory and displays the names of all the fi les and (top-level) sub-directories in that directory in alphabetical order. The entries . and .. should be omitted. To distinguish between fi les and directories dis-play the name of the latter in bold. For both types of entry disdis-play after the name the letter R and/or W indicating that it is readable and/or writeable.
113
© Springer International Publishing Switzerland 2015 M. Bramer, Web Programming with PHP and MySQL, DOI 10.1007/978-3-319-22659-0_8
Chapter 8
User-Defi ned Functions
1 To avoid any possible confusion, the term 'user' here refers to the PHP programmer, i.e. the person who writes the PHP script. Elsewhere in this book we use the term 'user' to refer to the 'end user' of a script, i.e. the person looking at a web page in a browser.
Chapter Aims
After reading this chapter you should be able to:
• create and use your own user-defi ned functions1
• create and use a personal function library
• understand the difference between passing arguments by value and by reference
• understand how to give an argument of a function a default value.
8.1 Introduction
As will no doubt be clear from previous chapters, much of the power of PHP comes from the use of system functions to perform a wide variety of operations. It is also possible for PHP programmers to defi ne their own functions as part of a script, and then to use them (possibly several times) in that script.
As an example the PHP statements shown in Chap. 7 to copy the contents of a text fi le to a new text fi le with the fi rst line removed can be made into a function removeHeader , defi ned as follows.
Then to copy a fi le fi le1.txt to a new fi le fi le2.txt with its fi rst line removed, all we need to write is:
The fi rst line of a function defi nition comprises four elements:
• The word function
• The name of the function
Function names follow the same rules as variable names. They comprise the characters a to z, A to Z, 0 to 9 and underscore, but may not begin with a digit.
Unlike variable names a function name may not begin with a $ sign. Also unlike variable names, function names are not case-sensitive, so the function names removeHeader and reMOVEheader are effectively the same.
• An argument list enclosed in parentheses. This will generally consist of one or more variable names separated by commas. However some functions may have no parameters in which case an empty pair of parentheses () is required.
• An opening brace character, signifying the start of the defi nition of the function.
The fi nal line of a function defi nition is always a closing brace character. In the above example we have added a comment giving the name of the function, but that is solely in the interest of readability.
Between the opening and closing braces we can place any number of PHP state-ments with the exception of another function defi nition. User-defi ned functions can call other user-defi ned functions but their defi nitions may not be nested.
Function defi nitions can be placed almost anywhere in a PHP script. It is proba-bly good practice to place all of them together either at the beginning or at the end of the script but they can also be placed between 'normal' PHP statements if you wish. (The system will not be confused if you do this, although you may fi nd it harder to understand your own scripts if you do.) Although the PHP system gener-ally works through a script from top to bottom, function defi nitions are not executed when they are encountered. A function is only executed when it is 'called', in the same way as a system function might be. Except in very early versions of PHP it is not necessary for a function to be defi ned in a script before it is used there.
The following example shows the removeHeader function being used from two parts of the same script.
115
Note that the presence of two lines of HTML between the two blocks of PHP does not prevent the second use of removeHeader. Wherever it is placed in one of the PHP parts of the fi le, the function defi nition is available for use throughout that and all the other PHP parts of the fi le.
Function removeHeader is an example of a type of function that is permitted in PHP but would not be allowed in many other languages. It does not return any value and is executed purely for what it does. To call it we simply use a function call such as
Functions of this kind can include a RETURN statement which indicates that execution of the function should immediately stop. To illustrate this here is a revised version of function removeHeader.
8.1 Introduction
Here we start by checking whether the fi le passed as the fi rst argument of remove-Header2 is readable. If it is not we print out an error message and then execute the return statement which immediately terminates the execution of the statements in the function defi nition. Otherwise we copy the contents (less the fi rst line) to $fi leB as before. In both cases, when function execution ends the line saying 'This line will always be reached' will be the next to be executed.
There can be return statements at several different places in a function defi nition if required. On the other hand, for functions that do not return values it is often pos-sible to avoid using a return statement altogether. Thus the previous defi nition of function removeHeader2 can be simplifi ed to
The next example shows a function which returns a value. In practice this is likely to be the more common kind of function defi ned (and the only kind permitted by many other languages).
The function printout defi ned below starts by testing whether a fi le passed to it as its only argument is readable. If it is not readable, a value of zero is returned, but no error message is output. If it is readable, its contents are printed out line by line and the value returned is the number of lines of text in the fi le.
As before, executing a return statement causes the function to cease execution immediately. The value of the function (in the form of a variable name, a constant or an expression) follows the word return, separated from it by at least one space.
To call the function we need to use a statement such as
117
which assigns the function value to a variable.
As for system functions, when a user-defi ned function is called the arguments of the calling function can be variables, constants or expressions that evaluate to con-stants. They are matched against the variables listed in the argument list of the func-tion defi nifunc-tion, so in the above example variable $thisfi le in funcfunc-tion printout is given the value "docs/fi le99.txt".