CHAPTER 14 ■ WORKING WITH FILES

file_validate_name_length($file)

The $file parameter is a file object. It returns an empty array if $file->filename exceeds 255 characters. Otherwise, it returns an array containing an error message instructing the user to use a shorter name. This function is a possible validator for file_save_upload().

file_validate_size($file, $file_limit = 0, $user_limit = 0)

This function checks that a file is below a maximum limit for the file or a cumulative limit for a user. The $file parameter is a file object that must contain $file->filesize, which is the size of the file in bytes. The $file_limit parameter is an integer representing the maximum file size in bytes. The $user_limit parameter is an integer representing the maximum cumulative number of bytes that the current user is allowed to use. A 0 means “no limit.” If validation passes, an empty array will be returned; otherwise, an array containing an error will be returned. This function is a possible validator for file_save_upload().

Getting the URL for a File

If you know the name of a file that has been uploaded and want to tell a client what the URL for that file is, the following function will help.

file_create_url($uri)

This function will return the correct URL for a file no matter whether Drupal is running in public or private download mode. The $uri parameter is the path to the file (e.g., sites/default/files/ pictures/picture-1.jpg or pictures/picture-1.jpg). The resulting URL might be http://example.com/ sites/default/files/pictures/picture-1.jpg. Note that the absolute path name to the file is not used. This makes it easier to move a Drupal site from one location (or server) to another.

Finding Files in a Directory

Drupal provides a powerful function called file_scan_directory(). It looks through a directory for files that match a given pattern.

335

CHAPTER 14 ■ WORKING WITH FILES

file_scan_directory($dir, $mask, $options = array(), $depth = 0)

Let’s walk through the function signature:

•$dir is the base directory or URI to scan, without trailing slash.

•$mask is the pattern to apply to the files that are contained in the directory. This is a regular expression.

•$options is an associative array of additional options, with the following elements:

•nomask: The preg_match() regular express of the files to ignore. This defaults to “/(\.\?|CVS)$/”.

•callback: The callback function to call for each match

•recurse: When TRUE, the directory scan will recurse the entire tree starting at the provided directory. The default is TRUE.

•key: The key to be used for the returned associative array of files. Possible values are “uri”, for the file’s URI; “filename”, for the basename of the file; and “name” for the name of the file without the extension. The default is “uri”.

•min_depth: Minimum depth of directories to return file from. Defaults to 0.

•$depth is the current depth of recursion. This parameter is used only internally and should not be passed in.

The return value is an associative array of objects. The key to the array depends on what is passed in the key parameter, and defaults to filename. Following are some examples.

Scan the themes/seven directory for any files ending with .css:

$found = file_scan_directory('themes/seven, '$css$');

The resulting array of objects is shown in Figure 14-7.

336

CHAPTER 14 ■ WORKING WITH FILES

Figure 14-7. The default result from file_scan_directory() is an array of objects keyed by the full file name.

337

CHAPTER 14 ■ WORKING WITH FILES

Changing the key parameter to the file name changes the keys of the resulting array, as shown in the following code and Figure 14-8.

$options = array ('key' => 'filename');

$found = file_scan_directory('themes/seven', '$css$', $options);

Figure 14-8. The result is now keyed by the file name with the full file path omitted.

338