CLIL-3-PHP-3. Files - part 1. Once you master the art of working with files, a wider world of PHP web

Transcription

1 Files - part 1 Introduction Once you master the art of working with files, a wider world of PHP web development opens up to you. Files aren't as flexible as databases by any means, but they do offer the chance to easily and permanently store information across scripts, which makes them popular amongst programmers. Files, as you can imagine, can store all sorts of information. However, most file formats (e.g. picture formats such as PNG and JPEG) are binary, and very difficult and/or impossible to write using normal text techniques - in these situations you should use the library designed to cope with each format. One reminder: if you are using an operating system that uses backslash \ as the path separator (e.g. Windows), you need to escape the backslash with another backslash, making \\. Alternatively, just use /, because Windows understands that just fine too. Topics covered in this chapter are: Reading and writing files Temporary files How to make a counter Handling file uploads File permissions 1

2 Note: CPUs work in billions of operations per second - a 3GHz CPU is capable of performing three billion operations every second. RAM access time is measured in nanoseconds (billionths of a second) - you can usually access some data in RAM in about 40 nanoseconds. Hard drive access time, however, is measured in milliseconds (thousandths of a second) - most hard drive have about a 7ms access time. What this means is that hard drives are much, much slower than RAM, so working with files from your hard drive is the slowest part of your computer, excluding your CD ROM. Databases are able to store their data in RAM for much faster access time, whereas storing hard drive data in RAM is tricky. Files are good for storing small bits of information, but it is not recommended that you use them too much for anything other than your PHP scripts themselves - counters are fine in files, as are other little things, but anything larger would almost certainly benefit from using a database. Having said that, please try to avoid the newbie mistake of putting everything into your database - if you find yourself trying to figure out what field type is right to store picture data, please have a rethink! 2

3 readfile() int readfile (string filename [, bool use_include_path [, resource context]]) If you want to output a file to the screen without doing any form of text processing on it whatsoever, readfile() is the easiest function to use. When passed a filename as its only parameter, readfile() will attempt to open it, read it all into memory, then output it without further question. If successful, readfile() will return an integer equal to the number of bytes read from the file. If unsuccessful, readfile() will return false, and there are quite a few reasons why it may file. For example, the file might not exist, or it might exist with the wrong permissions. Here is an example script: readfile("/home/paul/test.txt"); readfile("c:\\boot.ini"); The first example will work on most Unix-like systems, and will attempt to open the file test.txt in /home/paul/ directory - you will almost certainly want to change this to point to somewhere that exists and you have access to. The second example is for Windows systems, and should work in any Windows NT-descended OS, including Windows XP, Vista, 7 and 8. The advantages to using readfile() are clear: there is no fuss, and there is little way for it to go wrong. However, the disadvantage is equally clear: you have got absolutely no control over the text that comes out. You should use readfile() when you just want to print a file out without any further action on your behalf - it is a powerful little one-liner. 3

4 Note that from here on in I will be using the variable $filename to signify a filename you have chosen. This is to avoid having to keep printing separate examples for Windows and Unix. 4

5 file_get_contents() file() string file_get_contents (string filename [, bool use_include_path [, resource context]]) array file (string filename [, bool use_include_path [, resource context]]) The next evolutionary step up from readfile() is just called file_get_contents(), and also takes one parameter for the filename to open. This time, however, it does not output any data - instead, it will return the contents of the file as string, replete with new line characters \n where appropriate Here is file_get_contents() in use: $filestring = file_get_contents($filename); print $filestring; $filename, as mentioned already, is a variable used to represent a file you have chosen already, whether that be on Unix or Windows, which means that file_get_contents() opens that file and places its contents into $filestring. Effectively that piece of code is the same as our call to readfile(), but only because we're not doing anything with $filestring once we have it. Consider this script: $filestring = file_get_contents($filename); $filearray = explode("\n", $filestring); while (list($var, $val) = each($filearray)) { ++$var; $val = trim($val); print "Line $var: $val<br />"; } 5

6 This time we use explode() to turn $filestring into an array, which is then iterated through, outputting one line at a time with line numbers. Remember that array indices start at 0, so we need ++$var to make sure that it starts at line 1 rather than line 0. Also, note that we call trim() on $val - this is because each element in the array still has its new line character \n at the end, and trim() will take that off. File_get_contents() is an excellent general-purpose file-handling function that you will likely find yourself using extensively. As an alternative, if you find yourself always wanting your files inside arrays, you can use the file() function - it works in the same manner as file_get_contents(), with the exception that it returns an array, which each line in the file returned as an element. 6

7 fopen() fread() resource fopen ( string filename, string mode [, bool use_include_path [, resource context]]) string fread ( resource handle, int length) fopen() is, for many, a fiendishly complex function to use. The reason for this is because it is another one of those functions lifted straight from C, and so is not as user-friendly as most PHP functions. On the flip-side, as per usual, is the fact that fopen() is an incredibly versatile function that some people come to love for its ability to manipulate files just as you want it to. fopen() has two key parameters: the file to open, and how you would like it opened. Parameter one is easy - it is just $filename, as with the other examples. Parameter two is what makes fopen() so special: you specify letters in a string that define whether you want to read from ("r"), write to ("w"), or append to ("a") the file specified in parameter one. There is also a fourth option, "b", which opens the file in binary mode. This is not necessary on Unix-based systems, but it is on Windows, so it is best to use it everywhere - it is not detrimental on Unix-based systems at all. Take a look at the following usages: fopen($filename, "r"); fopen($filename, "w"); fopen() returns a file handle resource, which is basically the contents of the file. You cannot output it directly, e.g. "print fopen(...)", but fopen() -related functions all accept file handles as the file to work with, so you should store the return value 7

8 of fopen() in a variable for later use. Therefore, here's a full usage of fopen() : $handle = fopen($filename, "a"); If the file cannot be opened, fopen() returns false. If the file is successfully opened, a file handle is returned and you can proceed. Once the file handle is ready, we can call other functions on the opened file, depending on how the file was opened (the second parameter to fopen() ). To read from a file, the function fread() is used, and to write to a file fwrite() is used. For now we're interested in reading, so you should use "rb" for the second parameter to fopen(). fread() takes two parameters: a file handle to read from (this is the return value from fopen(), remember) and the number of bytes to read. The second parameter might not make sense at first, after all you generally want to read in all of a file, right? Note: Do not worry about specifying a number in parameter two that is larger than the file - PHP will stop reading when it hits the end of the file or the number of bytes in parameter two, whichever comes first. Well, while the chances are that you will indeed want to read in all of a file, doing so requires you have enough memory to be able to read in the entire file at once - if you are working with files of several megabytes or indeed hundreds of megabytes, PHP's resource consumption would balloon. In circumstances such as these you have but two choices: buy more RAM, or parse your data sequentially! 8

9 Luckily, most people will not have to make that choice - most people work with text files under a megabyte in size, and PHP can load a megabyte file all at once in a tiny fraction of a second. To instruct PHP to use fread() to read in the entire contents of a file, you simply need to specify the exact file size in bytes of that file as parameter two to fread(). Sound difficult? PHP comes to the rescue again with the filesize() function, which takes the name of a file to check, and returns its filesize in bytes - precisely what we're looking for. When reading in a file, PHP uses a file pointer to determine which byte it is currently up to - kind of like the array cursor. Each time you read in a byte, PHP advances the array cursor by one place - reading in the entire file at once advances the array cursor to the end of the file. So, to use fread() to read in an entire file, we can use the following line: $contents = fread($handle, filesize($filename)); Notice that fread() 's return value is the text it read in, and in above situation that is the entire file. To finish off using fread() it is simply necessary to close the file as soon as you are done with it. Note: Although PHP automatically closes all files you left open in your script, it is not smart to rely on it to do so - it is a poor use of resources, and it might affect other processes trying to read the file. Always, always, always close your files the minute you are finished with them. To close a file you have opened with fopen(), use fclose() - it takes the file handle we got from fopen(), and returns true if it was able to close the file successfully. 9

10 We have now got enough to use fopen() to fully open and read in a file, then close it. Here is the script: $handle = fopen($filename, "rb"); $contents = fread($handle, filesize($filename)); fclose($handle); print $contents; Firstly, remember that you will need to set $filename to be the location of a file on your system that you have access to. Secondly, notice that fopen() is called with "fb" as the second parameter - read-only, binary-safe. Always use "b" to ensure compatibility with Windows servers. Thirdly, notice that filesize() is being used to fread() in all of $filename's contents. Finally, notice that fclose() is called before $contents is printed - it is closed as soon as $handle is no longer needed. Get into - and stay in - this habit. 10

11 Creating and changing files Like reading files, creating and changing files can also be done in more than one way. Luckily for you, there are just two options this time: file_put_contents() and fwrite(). Both of these functions complement functions we just looked at, which are file_get_contents() and fread() respectively, and they work in mostly the same way. file_put_contents() int file_put_contents ( string filename, string data [, int flags [, resource context]]) This function writes to a file with the equivalent of fopen(), fwrite() (the opposite of fread() ), and fclose() - all in one function, just like file_get_contents. It takes two parameters, the filename to write to and the content to write respectively, with a third optional parameter specifying extra flags which we will get to in a moment. If file_put_contents() is successful it returns the number of bytes written to the file, otherwise it will return false. Using the file_put_contents() function is easy - here's an example: $myarray[] = "This is line one"; $myarray[] = "This is line two"; $myarray[] = "This is line three"; $mystring = implode("\n", $myarray); $numbytes = file_put_contents($filename, $mystring); print "$numbytes bytes written\n"; Remember you will need to set $filename first - other than that the script is straightforward, and should output "52 bytes written", which is the sum total of 11

12 the three lines of text plus the two new line characters used to implode() the array. Remember that the new line character is in fact just one character inside files, whereas PHP represents it using two, \ and n. You can pass in a third parameter to file_put_contents(), which, if set to FILE_APPEND, will act to append the text in your second parameter to the existing text in the file. If you do not use FILE_APPEND the existing text will be wiped and replaced, which is not always the desired behaviour. 12

13 fwrite() int fwrite ( resource handle, string string [, int length]) The opposite to fread() is fwrite() and also works with the file handle returned by fopen(). Fwrite() takes a string to write as a second parameter, and an optional third parameter where you can specify how many bytes to write. If you do not specify the third parameter, all of the second parameter is written out to the file, which is often what you want. Note: as with fread(), PHP will stop writing when it reaches the end of the string or when it has reached the number of bytes specified in this length parameter, whichever comes first - you don't need to worry about specifying more bytes than you have in the string. Here is an example using the variable $mystring from the previous example to save space: $handle = fopen($filename, "wb"); $numbytes = fwrite($handle, $mystring); fclose($handle); print "$numbytes bytes written\n"; If I had added 10 as the third parameter to the fwrite() call, only the first ten bytes of $mystring would have been written out. Note again that fclose() is called immediately after it was finished with, which is always best practice. Fwrite() uses a file pointer in the same way as fread() - as you write bytes out, PHP advances the file pointer appropriately, meaning that, unless you specifically 13

14 move the file pointer yourself, you always write to the end of a file. 14

15 Moving, copying, and deleting files bool rename ( string old_name, string new_name [, resource context]) bool copy ( string source, string dest) bool unlink ( string filename, resource context) PHP has simple functions to handle all moving, copying, and deleting files, and quite rightly - they are all very popular things to do, so there is no point making them difficult. If you are using Unix you will know that there is no command for "rename", because renaming a file is essentially the same as moving it, so you use the move (mv) command - it is the same in PHP. Files are moved using rename(), copied using copy(), and deleted using unlink(). Unlink() might seem like an odd choice of word at first, but Unix systems consider filenames to be "hard links" to the actual files themselves, so to unlink a file is to delete it. Note: all three functions will operate without further input from you. If you choose to pass an existing file to the second parameter of rename(), it will rename the file in parameter one to the file in parameter two, overwriting the original file. The same applies to copy() - you will overwrite all files without question as long as you have the correct permissions. 15

16 Moving files with rename() Use for both renaming and moving files, rename() takes two parameters: the original filename and the new filename you wish to use. Rename() can rename/move files across directories and drives, and will return true on success or false otherwise. Here is an example: $filename2 = $filename. '.old'; rename($filename, $filename2); If you had $filename set to c:\\windows\\myfile.txt, the above script would move that file to c:\\windows\\myfile.txt.old. Note: rename() should be used to move ordinary files, and not files uploaded through a form. The reason for this is because there is a special function, called move_uploaded_file(), which checks to make sure the file has indeed been uploaded before moving it - this stops people trying to hack your server into making private files visible. You can perform this check yourself if you like by calling the is_uploaded_file() function. 16

17 Copying files with copy() Like rename(), copy() also takes two parameters - the filename you wish to copy from, and the filename you wish to copy to. The difference between rename() and copy() is that calling rename() results in the file being in only one place, the destination, whereas copy() leaves the file in the source location as well as placing a new copy of the file into the destination. $filename2 = $filename. '.old'; copy($filename, $filename2); The result of that script is that there will be a file $filename and also a $filename.old, e.g. c:\\windows\\myfile.txt and c:\\windows\\myfile.txt.old. Note: this function will not copy empty (zero-length) files - to do that, you need to use the function touch(). 17

18 Deleting files with unlink() To delete files, simply pass a filename string as the only parameter to unlink(). Note that unlink deals only with files - to delete directories you need rmdir(). if (unlink($filename)) { print "Deleted $filename!\n"; } else { print "Delete of $filename failed!\n"; } Note: if you have a file opened with fopen(), you need to fclose() it before you call unlink() 18

19 Temporary files resource tmpfile ( void ) Very often you will find you want to work with a file as if it were a "scratchpad" - a holding area where you can write out temporary data for later use. To make this as easy as possible, PHP has a function called tmpfile() which takes no parameters, but will create a temporary file on the system, fopen() it for you, and send back the file handle as its return value. That file is then yours to read from and write to all you wish, and is deleted as soon as you fclose() the file handle or the script ends. Here is an example of tmpfile() in use: $handle = tmpfile(); $numbytes = fwrite($handle, $mystring); fclose($handle); print "$numbytes bytes written\n"; As you can see, tmpfile() is a drop-in replacement for fopen()ing a known file, so it is easy to make use of. If you want to know where these temp files are being saved, use the sys_get_temp_dir() function - it's new in PHP 5.2.1, but returns a string containing the directory used for creating temporary files. 19