Docbook2Wiki: Initial conversion from Docbook

2008-03-06T22:28:45Z

Initial conversion from Docbook

New page

{{PHP Cookbook/TOC}}

== Introduction ==

A filesystem stores a lot of additional information about files aside from their actual contents. This information includes such particulars as the file's size, what directory it's in, and access permissions for the file. If you're working with files, you may also need to manipulate this metadata. PHP gives you a variety of functions to read and manipulate directories, directory entries, and file attributes. Like other file-related parts of PHP, the functions are similar to the C functions that accomplish the same tasks, with some simplifications.

Files are organized with ''inodes'' . Each file (and other parts of the filesystem, such as directories, devices, and links) has its own inode. That inode contains a pointer to where the file's data blocks are as well as all the metadata about the file. The data blocks for a directory hold the names of the files in that directory and the inode of each file.

PHP provides two ways to look in a directory to see what files it holds. The first way is to use <tt>opendir( )</tt> to get a directory handle, <tt>readdir( )</tt> to iterate through the files, and <tt>closedir( )</tt> to close the directory handle:

$d = opendir('/usr/local/images') or die($php_errormsg);
while (false !== ($f = readdir($d))) {
// process file
}
closedir($d);

The second method is to use the directory class. Instantiate the class with <tt>dir( )</tt>, read each filename with the <tt>read( )</tt> method, and close the directory with <tt>close( )</tt> :

$d = dir('/usr/local/images') or die($php_errormsg);
while (false !== ($f = $d->read())) {
// process file
}
$d->close();

[[PHP Cookbook/Directories#Processing All Files in a Directory Recursively|Recipe 19.8]] shows how to use <tt>opendir( )</tt> or <tt>dir( )</tt> to process each file in a directory. Making new directories is covered in [[PHP Cookbook/Directories#Making New Directories|Recipe 19.11]] and removing directories in [[PHP Cookbook/Directories#Removing a Directory and Its Contents|Recipe 19.12]].

The filesystem holds more than just files and directories. On Unix, it can also hold symbolic links. These are special files whose contents are a pointer to another file. You can delete the link without affecting the file it points to. To create a symbolic link, use <tt>symlink( )</tt>:

symlink('/usr/local/images','/www/docroot/images') or die($php_errormsg);

This creates a symbolic link called ''images'' in ''/www/docroot'' that points to ''/usr/local/images''.

To find information about a file, directory, or link you must examine its inode. The function <tt>stat( )</tt> retrieves the metadata in an inode for you. [[PHP Cookbook/Directories#Getting File Information|Recipe 19.3]] discusses <tt>stat( )</tt>. PHP also has many functions that use <tt>stat( )</tt> internally to give you a specific piece of information about a file. These are listed in [[PHP Cookbook/Directories#phpckbk-CHP-19-TABLE-1|Table 19-1]].

<div id="phpckbk-CHP-19-TABLE-1">
'''Table 19-1. File information functions'''

{| border="1"
|-
! Function name !! What file information does the function provide?
|-
| <tt>file_exists( )</tt> || Does the file exist?
|-
| <tt>fileatime( )</tt> || Last access time
|-
| <tt>filectime( )</tt> || Last metadata change time
|-
| <tt>filegroup( )</tt> || Group (numeric)
|-
| <tt>fileinode( )</tt> || Inode number
|-
| <tt>filemtime( )</tt> || Last change time of contents
|-
| <tt>fileowner( )</tt> || Owner (numeric)
|-
| <tt>fileperms( )</tt> || Permissions (decimal, numeric)
|-
| <tt>filesize( )</tt> || Size
|-
| <tt>filetype( )</tt> || Type (fifo, char, dir, block, link, file, unknown)
|-
| <tt>is_dir( )</tt> || Is it a directory?
|-
| <tt>is_executable( )</tt> || Is it executable?
|-
| <tt>is_file( )</tt> || Is it a regular file?
|-
| <tt>is_link( )</tt> || Is it a symbolic link?
|-
| <tt>is_readable( )</tt> || Is it readable?
|-
| <tt>is_writable( )</tt> || Is it writeable?
|}
</div>

On Unix, the file permissions indicate what operations the file's owner, users in the file's group, and all users can perform on the file. The operations are reading, writing, and executing. For programs, executing means the ability to run the program; for directories, it's the ability to search through the directory and see the files in it.

Unix permissions can also contain a setuid bit, a setgid bit, and a sticky bit. The setuid bit means that when a program is run, it runs with the user ID of its owner. The setgid bit means that a program runs with the group ID of its group. For a directory, the setgid bit means that new files in the directory are created by default in the same group as the directory. The sticky bit is useful for directories in which people share files because it prevents nonsuperusers with write permission in a directory from deleting files in that directory unless they own the file or the directory.

When setting permissions with <tt>chmod( )</tt> (see [[PHP Cookbook/Directories#Changing File Permissions or Ownership|Recipe 19.4]]), they must be expressed as an octal number. This number has four digits. The first digit is any special setting for the file (such as setuid or setgid). The second digit is the user permissions — what the file's owner can do. The third digit is the group permissions — what users in the file's group can do. The fourth digit is the world permissions — what all other users can do. To compute the appropriate value for each digit, add together the permissions you want for that digit using the values in [[PHP Cookbook/Directories#phpckbk-CHP-19-TABLE-2|Table 19-2]]. For example, a permission value of <tt>0644</tt> means that there are no special settings (the <tt>0</tt>), the file's owner can read and write the file (the <tt>6</tt>, which is <tt>4</tt> (read) + <tt>2</tt> (write)), users in the file's group can read the file (the first <tt>4</tt>), and all other users can also read the file (the second <tt>4</tt>). A permission value of <tt>4644</tt> is the same, except that the file is also setuid.

<div id="phpckbk-CHP-19-TABLE-2">
'''Table 19-2. File permission values'''

{| border="1"
|-
! Value !! Permission meaning !! Special setting meaning
|-
| 4 || Read || setuid
|-
| 2 || Write || setgid
|-
| 1 || Execute || sticky
|}
</div>

The permissions of newly created files and directories are affected by a setting called the ''umask'' , which is a permission value that is removed, or masked out, from the initial permissions of a file (<tt>0666</tt> or directory (<tt>0777</tt>). For example, if the umask is <tt>0022</tt>, the default permissions for a new file created with <tt>touch( )</tt> or <tt>fopen( )</tt> are <tt>0644</tt> and the default permissions for a new directory created with <tt>mkdir( )</tt> are <tt>0755</tt>. You can get and set the umask with the function <tt>umask( )</tt> . It returns the current umask and, if an argument is supplied to it, changes the umask to the value of that argument. For example, here's how to make the permissions on newly created files prevent anyone but the file's owner (and the superuser) from accessing the file:

$old_umask = umask(0077);
touch('secret-file.txt');
umask($old_umask);

The first call to <tt>umask( )</tt> masks out all permissions for group and world. After the file is created, the second call to <tt>umask( )</tt> restores the umask to the previous setting. When PHP is run as a server module, it restores the umask to its default value at the end of each request. Like other permissions-related functions, <tt>umask( )</tt> doesn't work on Windows.

== Getting and Setting File Timestamps ==

=== Problem ===

You want to know when a file was last accessed or changed, or you want to update a file's access or change time; for example, you want each page on your web site to display when it was last modified.

=== Solution ===

The <tt>fileatime( )</tt> , <tt>filemtime( )</tt>, and <tt>filectime( )</tt> functions return the time of last access, modification, and metadata change of a file:

$last_access = fileatime('larry.php');
$last_modification = filemtime('moe.php');
$last_change = filectime('curly.php');

The <tt>touch( )</tt> function changes a file's modification time:

touch('shemp.php'); // set modification time to now
touch('joe.php',$timestamp); // set modification time to $timestamp

=== Discussion ===

The <tt>fileatime( )</tt> function returns the last time a file was opened for reading or writing. The <tt>filemtime( )</tt> function returns the last time a file's contents were changed. The <tt>filectime( )</tt> function returns the last time a file's contents or metadata (such as owner or permissions) were changed. Each function returns the time as an epoch timestamp.

A file's modification time can be updated with <tt>touch( )</tt>. Without a second argument, <tt>touch( )</tt> sets the modification time to the current date and time. To set a file's modification time to a specific value, pass that value as an epoch timestamp to <tt>touch( )</tt> as a second argument.

This code prints the time a page on your web site was last updated:

print "Last Modified: ".strftime('%c',filemtime($_SERVER['SCRIPT_FILENAME']));

=== See Also ===

Documentation on <tt>fileatime( )</tt> at ''http://www.php.net/fileatime'', <tt>filemtime( )</tt> at ''http://www.php.net/filemtime'', and <tt>filectime( )</tt> at ''http://www.php.net/filectime''.

== Getting File Information ==

=== Problem ===

You want to read a file's metadata; for example, permissions and ownership.

=== Solution ===

Use <tt>stat( )</tt> , which returns an array of information about a file:

$info = stat('harpo.php');

=== Discussion ===

The function <tt>stat( )</tt> returns an array with both numeric and string indexes with information about a file. The elements of this array are in [[PHP Cookbook/Directories#phpckbk-CHP-19-TABLE-3|Table 19-3]].

<div id="phpckbk-CHP-19-TABLE-3">
'''Table 19-3. Information returned by stat( )'''

{| border="1"
|-
! Numeric index !! String index !! Value
|-
| <tt>0</tt> || <tt>dev</tt> || Device
|-
| <tt>1</tt> || <tt>ino</tt> || Inode
|-
| <tt>2</tt> || <tt>mode</tt> || Permissions
|-
| <tt>3</tt> || <tt>nlink</tt> || Link count
|-
| <tt>4</tt> || <tt>uid</tt> || Owner's user ID
|-
| <tt>5</tt> || <tt>gid</tt> || Group's group ID
|-
| <tt>6</tt> || <tt>rdev</tt> || Device type for inode devices (-1 on Windows)
|-
| <tt>7</tt> || <tt>size</tt> || Size (in bytes)
|-
| <tt>8</tt> || <tt>atime</tt> || Last access time (epoch timestamp)
|-
| <tt>9</tt> || <tt>mtime</tt> || Last change time of contents (epoch timestamp)
|-
| <tt>10</tt> || <tt>ctime</tt> || Last change time of contents or metadata (epoch timestamp)
|-
| <tt>11</tt> || <tt>blksize</tt> || Block size for I/O (-1 on Windows)
|-
| <tt>12</tt> || <tt>blocks</tt> || Number of block allocated to this file
|}
</div>

The mode element of the returned array contains the permissions expressed as a base 10 integer. This is confusing since permissions are usually either expressed symbolically (e.g., ''ls'''s <tt>-rw-r--r--</tt> output) or as an octal integer (e.g., <tt>0644</tt>). To convert the permissions to a more understandable format, use <tt>base_convert( )</tt> to change the permissions to octal:

$file_info = stat('/tmp/session.txt');
$permissions = base_convert($file_info['mode'],10,8);

This results in a six-digit octal number. For example, if ''ls'' displays the following about ''/tmp/session.txt'':

-rw-rw-r-- 1 sklar sklar 12 Oct 23 17:55 /tmp/session.txt

Then <tt>$file_info['mode']</tt> is <tt>33204</tt> and <tt>$permissions</tt> is <tt>100664</tt>. The last three digits (<tt>664</tt>) are the user (read and write), group (read and write), and other (read) permissions for the file. The third digit, <tt>0</tt>, means that the file is not setuid or setgid. The leftmost <tt>10</tt> means that the file is a regular file (and not a socket, symbolic link, or other special file).

Because <tt>stat( )</tt> returns an array with both numeric and string indexes, using <tt>foreach</tt> to iterate through the returned array produces two copies of each value. Instead, use a <tt>for</tt> loop from element 0 to element 12 of the returned array.

Calling <tt>stat( )</tt> on a symbolic link returns information about the file the symbolic link points to. To get information about the symbolic link itself, use <tt>lstat( )</tt> .

Similar to <tt>stat( )</tt> is <tt>fstat( )</tt> , which takes a file handle (returned from <tt>fopen( )</tt> or <tt>popen( )</tt>) as an argument. You can use <tt>fstat( )</tt> only on local files, however, not URLs passed to <tt>fopen( )</tt>.

PHP's <tt>stat( )</tt> function uses the underlying ''stat(2)'' system call, which is expensive. To minimize overhead, PHP caches the result of calling ''stat(2)''. So, if you call <tt>stat( )</tt> on a file, change its permissions, and call <tt>stat( )</tt> on the same file again, you get the same results. To force PHP to reload the file's metadata, call <tt>clearstatcache( )</tt> , which flushes PHP's cached information. PHP also uses this cache for the other functions that return file metadata: <tt>file_exists( )</tt>, <tt>fileatime( )</tt>, <tt>filectime( )</tt>, <tt>filegroup( )</tt>, <tt>fileinode( )</tt>, <tt>filemtime( )</tt>, <tt>fileowner( )</tt>, <tt>fileperms( )</tt>, <tt>filesize( )</tt>, <tt>filetype( )</tt>, <tt>fstat( )</tt>, <tt>is_dir( )</tt>, <tt>is_executable( )</tt>, <tt>is_file( )</tt>, <tt>is_link( )</tt>, <tt>is_readable( )</tt>, <tt>is_writable( )</tt>, and <tt>lstat( )</tt>.

=== See Also ===

Documentation on <tt>stat( )</tt> at ''http://www.php.net/stat'', <tt>lstat( )</tt> at ''http://www.php.net/lstat'', <tt>fstat( )</tt> at ''http://www.php.net/fstat'', and <tt>clearstatcache( )</tt> at ''http://www.php.net/clearstatcache''.

== Changing File Permissions or Ownership ==

=== Problem ===

You want to change a file's permissions or ownership; for example, you want to prevent other users from being able to look at a file of sensitive data.

=== Solution ===

Use <tt>chmod( )</tt> to change the permissions of a file:

chmod('/home/user/secrets.txt',0400);

Use <tt>chown( )</tt> to change a file's owner and <tt>chgrp( )</tt> to change a file's group:

chown('/tmp/myfile.txt','sklar'); // specify user by name
chgrp('/home/sklar/schedule.txt','soccer'); // specify group by name

chown('/tmp/myfile.txt',5001); // specify user by uid
chgrp('/home/sklar/schedule.txt',102); // specify group by gid

=== Discussion ===

The permissions passed to <tt>chmod( )</tt> must be specified as an octal number.

The superuser can change the permissions, owner, and group of any file. Other users are restricted. They can change only the permissions and group of files that they own, and can't change the owner at all. Nonsuperusers can also change only the group of a file to a group they belong to.

The functions <tt>chmod( )</tt>, <tt>chgrp( )</tt>, and <tt>chown( )</tt> don't work on Windows.

=== See Also ===

Documentation on <tt>chmod( )</tt> at ''http://www.php.net/chmod'', <tt>chown( )</tt> at ''http://www.php.net/chown'', and <tt>chgrp( )</tt> at ''http://www.php.net/chgrp''.

== Splitting a Filename into Its Component Parts ==

=== Problem ===

You want to find a file's path and filename; for example, you want to create a file in the same directory as an existing file.

=== Solution ===

Use <tt>basename( )</tt> to get the filename and <tt>dirname( )</tt> to get the path:

$full_name = '/usr/local/php/php.ini';
$base = basename($full_name); // $base is php.ini
$dir = dirname($full_name); // $dir is /usr/local/php

Use <tt>pathinfo( )</tt> to get the directory name, base name, and extension in an associative array:

$info = pathinfo('/usr/local/php/php.ini');

=== Discussion ===

To create a temporary file in the same directory as an existing file, use <tt>dirname( )</tt> to find the directory, and pass that directory to <tt>tempnam( )</tt> :

$dir = dirname($existing_file);
$temp = tempnam($dir,'temp');
$temp_fh = fopen($temp,'w');

The elements in the associative array returned by <tt>pathinfo( )</tt> are <tt>dirname</tt>, <tt>basename</tt>, and <tt>extension</tt>:

$info = pathinfo('/usr/local/php/php.ini');
print_r($info);
'''Array'''
'''('''
''' [dirname] => /usr/local/php'''
''' [basename] => php.ini'''
''' [extension] => ini'''
''')'''

You can also pass <tt>basename( )</tt> an optional suffix to remove it from the filename. This sets <tt>$base</tt> to ''php'':

$base = basename('/usr/local/php/php.ini','.ini');

Using functions such as <tt>basename( )</tt>, <tt>dirname( )</tt>, and <tt>pathinfo( )</tt> is more portable than just separating a full filename on <tt>/</tt> because they use an operating-system appropriate separator. On Windows, these functions treat both <tt>/</tt> and <tt>\</tt> as file and directory separators. On other platforms, only <tt>/</tt> is used.

There's no built-in PHP function to combine the parts produced by <tt>basename( )</tt>, <tt>dirname( )</tt>, and <tt>pathinfo( )</tt> back into a full filename. To do this you have to combine the parts with . and <tt>/</tt>:

$dirname = '/usr/local/php';
$basename = 'php';
$extension = 'ini';

$full_name = $dirname . '/' . $basename . '.' . $extension;

You can pass a full filename produced like this to other PHP file functions on Windows, because PHP accepts <tt>/</tt> as a directory separator on Windows.

=== See Also ===

Documentation on <tt>basename( )</tt> at ''http://www.php.net/basename'', <tt>dirname( )</tt> at ''http://www.php.net/dirname'', and <tt>pathinfo( )</tt> at ''http://www.php.net/pathinfo''.

== Deleting a File ==

=== Problem ===

You want to delete a file.

=== Solution ===

Use <tt>unlink( )</tt> :

unlink($file) or die ("can't delete $file: $php_errormsg");

=== Discussion ===

The function <tt>unlink( )</tt> is only able to delete files that the user of the PHP process is able to delete. If you're having trouble getting <tt>unlink( )</tt> to work, check the permissions on the file and how you're running PHP.

=== See Also ===

Documentation on <tt>unlink( )</tt> at ''http://www.php.net/unlink''.

== Copying or Moving a File ==

=== Problem ===

You want to copy or move a file.

=== Solution ===

Use <tt>copy( )</tt> to copy a file:

copy($old,$new) or die("couldn't copy $old to $new: $php_errormsg");

Use <tt>rename( )</tt> to move a file:

rename($old,$new) or die("couldn't move $old to $new: $php_errormsg");

=== Discussion ===

On Unix, <tt>rename( )</tt> can't move files across filesystems. To do so, copy the file to the new location and then delete the old file:

if (copy("/tmp/code.c","/usr/local/src/code.c")) {
unlink("/tmp/code.c");
}

If you have multiple files to copy or move, call <tt>copy( )</tt> or <tt>rename( )</tt> in a loop. You can operate only on one file each time you call these functions.

=== See Also ===

Documentation on <tt>copy( )</tt> at ''http://www.php.net/copy'' and <tt>rename( )</tt> at ''http://www.php.net/rename''.

== Processing All Files in a Directory Recursively ==

=== Problem ===

You want to iterate over all files in a directory. For example, you want to create a <tt>select</tt> box in a form that lists all the files in a directory.

=== Solution ===

Get a directory handle with <tt>opendir( )</tt> and then retrieve each filename with <tt>readdir( )</tt>:

$d = opendir('/tmp') or die($php_errormsg);
while (false !== ($f = readdir($d))) {
print "$f\n";
}
closedir($d);

=== Discussion ===

The code in the solution tests the return value of <tt>readdir( )</tt> with the nonidentity operator (<tt>!==</tt>) so that the code works properly with filenames that evaluate to <tt>false</tt>, such as a file named ''0''.

The function <tt>readdir( )</tt> returns each entry in a directory, whether it is a file, directory, or something else (such as a link or a socket). This includes the metaentries "." (current directory) and ".." (parent directory). To just return files, use the <tt>is_file( )</tt> function as well:

print '<select name="files">';
$d = opendir('/usr/local/upload') or die($php_errormsg);
while (false !== ($f = readdir($d))) {
if (is_file("/usr/local/upload/$f")) {
print '<option> ' . $f . '</option>';
}
}
closedir($d);
print '</select>';

Because <tt>readdir( )</tt> returns only the filename of each directory entry, not a full pathname, you have to prepend the directory name to <tt>$f</tt> before you pass it to <tt>is_file( )</tt>.

PHP also has an object-oriented interface to directory information. The <tt>dir( )</tt> function returns an object on which you can call <tt>read( )</tt>, <tt>rewind( )</tt>, and <tt>close( )</tt> methods, which act like the <tt>readdir( )</tt>, <tt>rewinddir( )</tt>, and <tt>closedir( )</tt> functions. There's also a <tt>$path</tt> property that contains the full path of the opened directory.

Here's how to iterate through files with the object-oriented interface:

print '<select name="files">';
$d = dir('/usr/local/upload') or die($php_errormsg);
while (false !== ($f = $d->read())) {
if (is_file($d->path.'/'.$f)) {
print '<option> ' . $f . '</option>';
}
}
$d->close();

In this example, <tt>$d->path</tt> is ''/usr/local/upload''.

=== See Also ===

Documentation on <tt>opendir( )</tt> at ''http://www.php.net/opendir'', <tt>readdir( )</tt> at ''http://www.php.net/readdir'', and the directory class at ''http://www.php.net/class.dir''.

== Getting a List of Filenames Matching a Pattern ==

=== Problem ===

You want to find all filenames that match a pattern.

=== Solution ===

If your pattern is a regular expression, read each file from the directory and test the name with <tt>preg_match( )</tt> :

$d = dir('/tmp') or die($php_errormsg);
while (false !== ($f = $d->read())) {
// only match alphabetic names
if (preg_match('/^[a-zA-Z]+$/',$f)) {
print "$f\n";
}
}
$d->close();

=== Discussion ===

If your pattern is a shell glob (e.g., <tt>*.*</tt>), use the backtick operator with ''ls'' (Unix) or ''dir'' (Windows) to get the matching filenames. For Unix:

$files = explode("\n",`ls -1 *.gif`);
foreach ($files as $file) {
print "$b\n";
}

For Windows:

$files = explode("\n",`dir /b *.gif`);
foreach ($files as $file) {
print "$b\n";
}

=== See Also ===

[[PHP Cookbook/Directories#Processing All Files in a Directory Recursively|Recipe 19.8]] details on iterating through each file in a directory; information about shell pattern matching is available at ''http://www.gnu.org/manual/bash/html_node/bashref_35.html''.

== Processing All Files in a Directory ==

=== Problem ===

You want to do something to all the files in a directory and in any subdirectories.

=== Solution ===

Use the <tt>pc_process_dir( )</tt> function, shown in [[PHP Cookbook/Directories#phpckbk-CHP-19-EX-1|Example 19-1]], which returns a list of all files in and beneath a given directory.

<div id="phpckbk-CHP-19-EX-1">
'''Example 19-1. pc_process_dir( )'''

function pc_process_dir($dir_name,$max_depth = 10,$depth = 0) {
if ($depth >= $max_depth) {
error_log("Reached max depth $max_depth in $dir_name.");
return false;
}
$subdirectories = array();
$files = array();
if (is_dir($dir_name) && is_readable($dir_name)) {
$d = dir($dir_name);
while (false !== ($f = $d->read())) {
// skip . and ..
if (('.' == $f) || ('..' == $f)) {
continue;
}
if (is_dir("$dir_name/$f")) {
array_push($subdirectories,"$dir_name/$f");
} else {
array_push($files,"$dir_name/$f");
}
}
$d->close();
foreach ($subdirectories as $subdirectory) {
$files = array_merge($files,pc_process_dir($subdirectory,$max_depth,$depth+1));
}
}
return $files;
}
</div>

=== Discussion ===

Here's an example: if ''/tmp'' contains the files ''a'' and ''b'', as well as the directory ''c'', and ''/tmp/c'' contains files ''d'' and ''e'', <tt>pc_process_dir('/tmp')</tt> returns an array with elements ''/tmp/a'', ''/tmp/b'', ''/tmp/c/d'', and ''/tmp/c/e''. To perform an operation on each file, iterate through the array:

$files = pc_process_dir('/tmp');
foreach ($files as $file) {
print "$file was last accessed at ".strftime('%c',fileatime($file))."\n";
}

Instead of returning an array of files, you can also write a function that processes them as it finds them. The <tt>pc_process_dir2( )</tt> function, shown in [[PHP Cookbook/Directories#phpckbk-CHP-19-EX-2|Example 19-2]], does this by taking an additional argument, the name of the function to call on each file found.

<div id="phpckbk-CHP-19-EX-2">
'''Example 19-2. pc_process_dir2( )'''

function pc_process_dir2($dir_name,$func_name,$max_depth = 10,$depth = 0) {
if ($depth >= $max_depth) {
error_log("Reached max depth $max_depth in $dir_name.");
return false;
}
$subdirectories = array();
$files = array();
if (is_dir($dir_name) && is_readable($dir_name)) {
$d = dir($dir_name);
while (false !== ($f = $d->read())) {
// skip . and ..
if (('.' == $f) || ('..' == $f)) {
continue;
}
if (is_dir("$dir_name/$f")) {
array_push($subdirectories,"$dir_name/$f");
} else {
$func_name("$dir_name/$f");
}
}
$d->close();
foreach ($subdirectories as $subdirectory) {
pc_process_dir2($subdirectory,$func_name,$max_depth,$depth+1);
}
}
}
</div>

The <tt>pc_process_dir2( )</tt> function doesn't return a list of directories; instead, the function <tt>$func_name</tt> is called with the file as its argument. Here's how to print out the last access times:

function printatime($file) {
print "$file was last accessed at ".strftime('%c',fileatime($file))."\n";
}

pc_process_dir2('/tmp','printatime');

Although the two functions produce the same results, the second version uses less memory because potentially large arrays of files aren't passed around.

The <tt>pc_process_dir( )</tt> and <tt>pc_process_dir2( )</tt> functions use a ''breadth-first search'' . In this type of search, the functions handle all the files in the current directory; then they recurse into each subdirectory. In a ''depth-first search'' , they recurse into a subdirectory as soon as the subdirectory is found, whether or not there are files remaining in the current directory. The breadth-first search is more memory efficient; each pointer to the current directory is closed (with <tt>$d->close( )</tt>) before the function recurses into subdirectories, so there's only one directory pointer open at a time.

Because <tt>is_dir( )</tt> returns <tt>true</tt> when passed a symbolic link that points to a directory, both versions of the function follow symbolic links as they traverse down the directory tree. If you don't want to follow links, change the line:

if (is_dir("$dir_name/$f")) {

to:

if (is_dir("$dir_name/$f") && (! is_link("$dir_name/$f"))) {

=== See Also ===

[[PHP Cookbook/Functions#Returning Failure|Recipe 6.10]] for a discussion of variable functions; documentation on <tt>is_dir( )</tt> at ''http://www.php.net/is-dir'' and <tt>is_link( )</tt> at ''http://www.php.net/is-link''.

== Making New Directories ==

=== Problem ===

You want to create a directory.

=== Solution ===

Use <tt>mkdir( )</tt> :

mkdir('/tmp/apples',0777) or die($php_errormsg);

=== Discussion ===

The second argument to <tt>mkdir( )</tt> is the permission mode for the new directory, which must be an octal number. The current umask is taken away from this permission value to create the permissions for the new directory. So, if the current umask is <tt>0002</tt>, calling <tt>mkdir('/tmp/apples',0777)</tt> sets the permissions on the resulting directory to <tt>0775</tt> (user and group can read, write, and execute; others can only read and execute).

PHP's built-in <tt>mkdir( )</tt> can make a directory only if its parent exists. For example, if ''/tmp/a'' doesn't exist, you can't create ''/tmp/a/b'' until ''/tmp/a'' is created. To create a directory and its parents, you have two choices: you can call your system's <tt>mkdir</tt> program, or you can use the <tt>pc_mkdir_parents( )</tt> function, shown in [[PHP Cookbook/Directories#phpckbk-CHP-19-EX-3|Example 19-3]]. To use your system's ''mkdir'' program, on Unix, use this:

system('/bin/mkdir -p '.escapeshellarg($directory));

On Windows do:

system('mkdir '.escapeshellarg($directory));

You can also use the <tt>pc_mkdir_parents( )</tt> function shown in [[PHP Cookbook/Directories#phpckbk-CHP-19-EX-3|Example 19-3]].

<div id="phpckbk-CHP-19-EX-3">
'''Example 19-3. pc_mkdir_parents( )'''

<nowiki>function pc_mkdir_parents($d,$umask = 0777) {
$dirs = array($d);
$d = dirname($d);
$last_dirname = '';
while($last_dirname != $d) {
array_unshift($dirs,$d);
$last_dirname = $d;
$d = dirname($d);
}

foreach ($dirs as $dir) {
if (! file_exists($dir)) {
if (! mkdir($dir,$umask)) {
error_log("Can't make directory: $dir");
return false;
}
} elseif (! is_dir($dir)) {
error_log("$dir is not a directory");
return false;
}
}
return true;
}</nowiki>
</div>

For example:

pc_mkdir_parents('/usr/local/upload/test',0777);

=== See Also ===

Documentation on <tt>mkdir( )</tt> at ''http://www.php.net/mkdir''; your system's ''mkdir'' documentation, such as the Unix ''mkdir(1)'' man page or the Windows ''mkdir /?'' help text.

== Removing a Directory and Its Contents ==

=== Problem ===

You want to remove a directory and all of its contents, including subdirectories and their contents.

=== Solution ===

On Unix, use ''rm'':

$directory = escapeshellarg($directory);
exec("rm -rf $directory");

On Windows, use ''rmdir'':

$directory = escapeshellarg($directory);
exec("rmdir /s /q $directory");

=== Discussion ===

Removing files, obviously, can be dangerous. Be sure to escape <tt>$directory</tt> with <tt>escapeshellarg( )</tt> so that you don't delete unintended files.

Because PHP's built-in directory removal function, <tt>rmdir( )</tt> , works only on empty directories, and <tt>unlink( )</tt> can't accept shell wildcards, calling a system program is much easier than recursively looping through all files in a directory, removing them, and then removing each directory. If an external utility isn't available, however, you can modify the <tt>pc_process_dir( )</tt> function from [[PHP Cookbook/Directories#Processing All Files in a Directory|Recipe 19.10]] to remove each subdirectory.

=== See Also ===

Documentation on <tt>rmdir( )</tt> at ''http://www.php.net/rmdir''; your system's ''rm'' or ''rmdir'' documentation, such as the Unix ''rm(1)'' manpage or the Windows ''rmdir /?'' help text.

== Program: Web Server Directory Listing ==

The ''web-ls.php'' program shown in [[PHP Cookbook/Directories#phpckbk-CHP-19-EX-4|Example 19-4]] provides a view of the files inside your web server's document root, formatted like the output of the Unix command ''ls''. Filenames are linked so that you can download each file, and directory names are linked so that you can browse in each directory, as shown in [[PHP Cookbook/Directories#phpckbk-CHP-19-FIG-1|Figure 19-1]].

<div id="phpckbk-CHP-19-FIG-1">
'''Figure 19-1. Web listing'''

[[Image:PHP Cookbook_I_19_tt1117.png|Web listing]]
</div>

Most lines in [[PHP Cookbook/Directories#phpckbk-CHP-19-EX-4|Example 19-4]] are devoted to building an easy-to-read representation of the file's permissions, but the guts of the program are in the <tt>while</tt> loop at the end. The <tt>$d->read( )</tt> method gets the name of each file in the directory. Then, <tt>lstat( )</tt> retrieves information about that file, and <tt>printf( )</tt> prints out the formatted information about that file.

The <tt>mode_string( )</tt> functions and the constants it uses turn the octal representation of a file's mode (e.g., <tt>35316</tt>) into an easier-to-read string (e.g., <tt>-rwsrw-r--</tt>).

<div id="phpckbk-CHP-19-EX-4">
'''Example 19-4. web-ls.php'''

<nowiki>/* Bit masks for determining file permissions and type. The names and values
* listed below are POSIX-compliant, individual systems may have their own
* extensions.
*/

define('S_IFMT',0170000); // mask for all types
define('S_IFSOCK',0140000); // type: socket
define('S_IFLNK',0120000); // type: symbolic link
define('S_IFREG',0100000); // type: regular file
define('S_IFBLK',0060000); // type: block device
define('S_IFDIR',0040000); // type: directory
define('S_IFCHR',0020000); // type: character device
define('S_IFIFO',0010000); // type: fifo
define('S_ISUID',0004000); // set-uid bit
define('S_ISGID',0002000); // set-gid bit
define('S_ISVTX',0001000); // sticky bit
define('S_IRWXU',00700); // mask for owner permissions
define('S_IRUSR',00400); // owner: read permission
define('S_IWUSR',00200); // owner: write permission
define('S_IXUSR',00100); // owner: execute permission
define('S_IRWXG',00070); // mask for group permissions
define('S_IRGRP',00040); // group: read permission
define('S_IWGRP',00020); // group: write permission
define('S_IXGRP',00010); // group: execute permission
define('S_IRWXO',00007); // mask for others permissions
define('S_IROTH',00004); // others: read permission
define('S_IWOTH',00002); // others: write permission
define('S_IXOTH',00001); // others: execute permission

/* mode_string() is a helper function that takes an octal mode and returns
* a ten character string representing the file type and permissions that
* correspond to the octal mode. This is a PHP version of the mode_string()
* function in the GNU fileutils package.
*/
function mode_string($mode) {
$s = array();

// set type letter
if (($mode & S_IFMT) == S_IFBLK) {
$s[0] = 'b';
} elseif (($mode & S_IFMT) == S_IFCHR) {
$s[0] = 'c';
} elseif (($mode & S_IFMT) == S_IFDIR) {
$s[0] = 'd';
} elseif (($mode & S_IFMT) == S_IFREG) {
$s[0] = '-';
} elseif (($mode & S_IFMT) == S_IFIFO) {
$s[0] = 'p';
} elseif (($mode & S_IFMT) == S_IFLNK) {
$s[0] = 'l';
} elseif (($mode & S_IFMT) == S_IFSOCK) {
$s[0] = 's';
}

// set user permissions
$s[1] = $mode & S_IRUSR ? 'r' : '-';
$s[2] = $mode & S_IWUSR ? 'w' : '-';
$s[3] = $mode & S_IXUSR ? 'x' : '-';

// set group permissions
$s[4] = $mode & S_IRGRP ? 'r' : '-';
$s[5] = $mode & S_IWGRP ? 'w' : '-';
$s[6] = $mode & S_IXGRP ? 'x' : '-';

// set other permissions
$s[7] = $mode & S_IROTH ? 'r' : '-';
$s[8] = $mode & S_IWOTH ? 'w' : '-';
$s[9] = $mode & S_IXOTH ? 'x' : '-';

// adjust execute letters for set-uid, set-gid, and sticky
if ($mode & S_ISUID) {
if ($s[3] != 'x') {
// set-uid but not executable by owner
$s[3] = 'S';
} else {
$s[3] = 's';
}
}

if ($mode & S_ISGID) {
if ($s[6] != 'x') {
// set-gid but not executable by group
$s[6] = 'S';
} else {
$s[6] = 's';
}
}

if ($mode & S_ISVTX) {
if ($s[9] != 'x') {
// sticky but not executable by others
$s[9] = 'T';
} else {
$s[9] = 't';
}
}

// return formatted string
return join('',$s);

}

// Start at the document root if not specified
if (isset($_REQUEST['dir'])) {
$dir = $_REQUEST['dir'];
} else {
$dir = '';
}

// locate $dir in the filesystem
$real_dir = realpath($_SERVER['DOCUMENT_ROOT'].$dir);

// make sure $real_dir is inside document root
if (! preg_match('/^'.preg_quote($_SERVER['DOCUMENT_ROOT'],'/').'/',
$real_dir)) {
die("$dir is not inside the document root");
}

// canonicalize $dir by removing the document root from its beginning
$dir = substr_replace($real_dir,'',0,strlen($_SERVER['DOCUMENT_ROOT']));

// are we opening a directory?
if (! is_dir($real_dir)) {
die("$real_dir is not a directory");
}

// open the specified directory
$d = dir($real_dir) or die("can't open $real_dir: $php_errormsg");

print '<table>';

// read each entry in the directory
while (false !== ($f = $d->read())) {

// get information about this file
$s = lstat($d->path.'/'.$f);

// translate uid into user name
$user_info = posix_getpwuid($s['uid']);

// translate gid into group name
$group_info = posix_getgrgid($s['gid']);

// format the date for readability
$date = strftime('%b %e %H:%M',$s['mtime']);

// translate the octal mode into a readable string
$mode = mode_string($s['mode']);

$mode_type = substr($mode,0,1);
if (($mode_type == 'c') || ($mode_type == 'b')) {
/* if it's a block or character device, print out the major and
* minor device type instead of the file size */
$major = ($s['rdev'] >> 8) & 0xff;
$minor = $s['rdev'] & 0xff;
$size = sprintf('%3u, %3u',$major,$minor);
} else {
$size = $s['size'];
}

// format the <a href=""> around the filename
// no link for the current directory
if ('.' == $f) {
$href = $f;
} else {
// don't include the ".." in the parent directory link
if ('..' == $f) {
$href = urlencode(dirname($dir));
} else {
$href = urlencode($dir) . '/' . urlencode($f);
}

/* everything but "/" should be urlencoded */
$href = str_replace('%2F','/',$href);

// browse other directories with web-ls
if (is_dir(realpath($d->path . '/' . $f))) {
$href = sprintf('<a href="%s?dir=%s">%s</a>',
$_SERVER['PHP_SELF'],$href,$f);
} else {
// link to files to download them
$href= sprintf('<a href="%s">%s</a>',$href,$f);
}

// if it's a link, show the link target, too
if ('l' == $mode_type) {
$href .= ' -&gt; ' . readlink($d->path.'/'.$f);
}
}

// print out the appropriate info for this file
printf('<tr><td>%s</td><td>%3u</td><td align="right">%s</td>
<td align="right">%s</td><td align="right">%s</td>
<td align="right">%s</td><td>%s</td></tr>',
$mode, // formatted mode string
$s['nlink'], // number of links to this file
$user_info['name'], // owner's user name
$group_info['name'], // group name
$size, // file size (or device numbers)
$date, // last modified date and time
$href); // link to browse or download
}

print '</table>';
</nowiki>
</div>

== Program: Site Search ==

You can use ''site-search.php'', shown in [[PHP Cookbook/Directories#phpckbk-CHP-19-EX-5|Example 19-5]], as a search engine for a small-to-medium size, file-based site.

The program looks for a search term (in <tt>$_REQUEST['term']</tt>) in all files within a specified set of directories under the document root. Those directories are set in <tt>$search_dirs</tt>. It also recurses into subdirectories and follows symbolic links but keeps track of which files and directories it has seen so that it doesn't get caught in an endless loop.

If any pages are found that contain the search term, it prints list of links to those pages, alphabetically ordered by each page's title. If a page doesn't have a title (between the <tt><title></tt> and <tt></title></tt> tags), the page's relative URI from the document root is used.

The program looks for the search term between the <tt><body></tt> and <tt></body></tt> tags in each file. If you have a lot of text in your pages inside <tt><body></tt> tags that you want to exclude from the search, surround the text that should be searched with specific HTML comments and then modify <tt>$body_regex</tt> to look for those tags instead. Say, for example, if your page looks like this:

<body>

// Some HTML for menus, headers, etc.



<h1>Aliens Invade Earth</h1>

<h3>by H.G. Wells</h3>

<p>Aliens invaded earth today. Uh Oh.</p>

// More of the story



// Some HTML for footers, etc.

</body>

To match the search term against just the title, author, and story inside the HTML comments, change <tt>$body_regex</tt> to:

$body_regex = '#(.*' . preg_quote($_REQUEST['term'],'#').
'.*)#Sis';

If you don't want the search term to match text that's inside HTML or PHP tags in your pages, add a call to <tt>strip_tags( )</tt> to the code that loads the contents of the file for searching:

<nowiki>// load the contents of the file into $file
$file = strip_tags(join('',file($path)));</nowiki>

<div id="phpckbk-CHP-19-EX-5">
'''Example 19-5. site-search.php'''

<nowiki>function pc_search_dir($dir) {
global $body_regex,$title_regex,$seen;

// array to hold pages that match
$pages = array();

// array to hold directories to recurse into
$dirs = array();

// mark this directory as seen so we don't look in it again
$seen[realpath($dir)] = true;

// if we can get a directory handle for this directory
if (is_readable($dir) && ($d = dir($dir))) {
// get each file name in the directory
while (false !== ($f = $d->read())) {
// build the full path of the file
$path = $d->path.'/'.$f;
// if it's a regular file and we can read it
if (is_file($path) && is_readable($path)) {

$realpath = realpath($path);
// if we've seen this file already,
if ($seen[$realpath]) {
// then skip it
continue;
} else {
// otherwise, mark it as seen so we skip it
// if we come to it again
$seen[$realpath] = true;
}

// load the contents of the file into $file
$file = join('',file($path));

// if the search term is inside the body delimiters
if (preg_match($body_regex,$file)) {

// construct the relative URI of the file by removing
// the document root from the full path
$uri = substr_replace($path,'',0,strlen($_SERVER['DOCUMENT_ROOT']));

// If the page has a title, find it
if (preg_match('#<title>(.*?)</title>#Sis',$file,$match)) {
// and add the title and URI to $pages
array_push($pages,array($uri,$match[1]));
} else {
// otherwise use the URI as the title
array_push($pages,array($uri,$uri));
}
}
} else {
// if the directory entry is a valid subdirectory
if (is_dir($path) && ('.' != $f) && ('..' != $f)) {
// add it to the list of directories to recurse into
array_push($dirs,$path);
}
}
}
$d->close();
}

/* look through each file in each subdirectory of this one, and add
the matching pages in those directories to $pages. only look in
a subdirectory if we haven't seen it yet.
*/
foreach ($dirs as $subdir) {
$realdir = realpath($subdir);
if (! $seen[$realdir]) {
$seen[$realdir] = true;
$pages = array_merge($pages,pc_search_dir($subdir));
}
}

return $pages;
}

// helper function to sort matched pages alphabetically by title
function pc_page_sort($a,$b) {
if ($a[1] == $b[1]) {
return strcmp($a[0],$b[0]);
} else {
return ($a[1] > $b[1]);
}
}

// array to hold the pages that match the search term
$matching_pages = array();
// array to hold pages seen while scanning for the search term
$seen = array();
// directories underneath the document root to search
$search_dirs = array('sports','movies','food');
// regular expression to use in searching files. The "S" pattern
// modifier tells the PCRE engine to "study" the regex for greater
// efficiency.
$body_regex = '#<body>(.*' . preg_quote($_REQUEST['term'],'#').
'.*)</body>#Sis';

// add the files that match in each directory to $matching pages
foreach ($search_dirs as $dir) {
$matching_pages = array_merge($matching_pages,
pc_search_dir($_SERVER['DOCUMENT_ROOT'].'/'.$dir));
}

if (count($matching_pages)) {
// sort the matching pages by title
usort($matching_pages,'pc_page_sort');
print '<ul>';
// print out each title with a link to the page
foreach ($matching_pages as $k => $v) {
print sprintf('<li> <a href="%s">%s</a>',$v[0],$v[1]);
}
print '</ul>';
} else {
print 'No pages found.';
}

</nowiki>
</div>

←Older revision		Revision as of 06:25, 11 August 2010
Line 191:		Line 191:


-	The mode element of the returned array contains the permissions expressed as a base 10 integer. This is confusing since permissions are usually either expressed symbolically (e.g., ''ls'''s <tt>-rw-r--r--</tt> output) or as an octal integer (e.g., <tt>0644</tt>). To convert the permissions to a more understandable format, use <tt>~~base_convert~~( )</tt> to change the permissions to octal:	+	The mode element of the returned array contains the permissions expressed as a base 10 integer. This is confusing since permissions are usually either expressed symbolically (e.g., ''ls'''s <tt>-rw-r--r--</tt> output) or as an octal integer (e.g., <tt>0644</tt>). To convert the permissions to a more understandable format, use <tt>decoct( )</tt> to change the permissions to octal:

	$file_info = stat('/tmp/session.txt');		$file_info = stat('/tmp/session.txt');
-	$permissions = ~~base_convert~~($file_info['mode']~~,10,8~~);	+	$permissions = decoct($file_info['mode']);

	This results in a six-digit octal number. For example, if ''ls'' displays the following about ''/tmp/session.txt'':		This results in a six-digit octal number. For example, if ''ls'' displays the following about ''/tmp/session.txt'':

PHP Cookbook/Directories - Revision history

Newacct at 06:25, 11 August 2010

Docbook2Wiki: Initial conversion from Docbook

Evanlenz: 1 revision(s)

Docbook2Wiki: Initial conversion from Docbook