Guess what the File API functions do!

drewish's picture

As part of the Media/Files Code Sprint we're trying to re-evaluate the mess of badly named functions in file.inc. When we were discussing it on IRC, clouseau pointed out that it's been a popular drinking game at DrupalCon for a few years.

Take a look at each item in the list and make a guess about what you think each function does based solely on the name--to make this a fair fight I'm even giving you the parameter names--then look at the documentation and see how you did.

Please leave comments telling us which were the easiest to guess and which functions totally puzzled you. This is a big list so feel free to comment even if you don't make it all the way through.

What's that? Okay you got me... It's true, I stacked the deck so all the worst offenders made their way to the top of the list. So if you got them all right and you're name isn't chx then I'll buy you a cheap beer at DrupalConSzeged.

Comments

I'll give it a try

andreiashu's picture

I'm probably among the best possible subjects for this: i'm still new to drupal :)
I'll try to express exactly what the name of the functions suggest.
Here it goes, prepare to laugh:
- file_create_url($path) - create a file at the specified $path ???
- file_create_path($dest = 0) - create the directory path to the specified destination
- file_check_directory(&$directory, $mode = 0, $form_item = NULL) - check a directory for specified attributes and $mode should represent the directory permissions
- file_check_path(&$path) – check if path exists ?
- file_check_location($source, $directory = '') – i have no ideea
- file_create_filename($basename, $directory) – create a file in a specified $directory
- file_scan_directory – scan a directory for a specified file
- file_destination($destination, $replace) – save file at the specified $destination; $replace is a boolean type saying whether to replace the file or not in case it already exists at $destination
- file_transfer($source, $headers) – I already knew what this function does from the docs;
- file_download() – i know it is silly but from the name itself this function should do the same as the file_transfer function
- file_save_upload($source, $validators = array(), $dest = FALSE, $replace = FILE_EXISTS_RENAME) – save an already uploaded file (i.e. from temp directory to your $dest)
- file_save_data($data, $dest, $replace = FILE_EXISTS_RENAME) – save text (or binary) data to a file
- file_set_status(&$file, $status) – set the status of a file
- file_directory_temp() – get the temporary upload directory ?
- file_directory_path() – get the upload path
- file_upload_max_size() – get the max size in bytes for an upload
- file_munge_filename($filename, $extensions, $alerts = TRUE) – no ideea.
- file_unmunge_filename($filename) – undo the action taken above
- file_space_used($uid = NULL) – how much space (in bytes??) is the user with $uid using
- file_validate_name_length($file) – check to see if the filename length is valid
- file_validate_extensions($file, $extensions) – check to see if file has one of the extensions in the $extensions array or object (there should be a way so you can suggest what $extensions is: array, object)
- file_validate_size($file, $file_limit = 0, $user_limit = 0) – see whether the file exceeds the file_limit or user_limit size
- file_validate_is_image(&$file) – see wether $file is an image (jpg, png, tiff, gif ?)
- file_validate_image_resolution(&$file, $maximum_dimensions = 0, $minimum_dimensions = 0) – validate the res of the image against the max and min dimensions (again: arrays or objects???)
- file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) – copy the file from $source to $destination
- file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) – move
- file_delete($path) – delete the file

What's my score?

floretan's picture

Here's my attempt. I haven't looked at the previous comment yet. I've used a few of these functions before, but I won't look at the API for the sake of this game.
* file_create_url($path): create http://example.com/node/3 from node/3
* file_create_path($dest = 0): create a path from a destination? that doesn't make sense.
* file_check_directory(&$directory, $mode = 0, $form_item = NULL): I've used that one, it checks a directory for various accesses, and then some. No idea what that $form_item parameter could be though.
* file_check_path(&$path): check that a path is valid. Given the parameter by reference I'll guess that it also "makes" the path valid.
* file_check_location($source, $directory = ''): errr...
* file_create_filename($basename, $directory): ok, that's easy. I have flower.png in files/images, so I want files/images/flower.png
* file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0): wow wow wow... do we need a gazillion parameters just to get a list of files?
* file_destination($destination, $replace): I'm guessing... maybe check that a file doesn't already exist. Wait, no file_create_filename() creates alternates filenames if a file already exists.
* file_transfer($source, $headers): that's probably to set the headers for a file download
* file_download(): download a file... which file? (I don't see a parameter)
* file_save_upload($source, $validators = array(), $dest = FALSE, $replace = FILE_EXISTS_RENAME): Save a file once it has been uploaded. It's been a while since I used it, but I remember having a hard time with this one.
* file_save_data($data, $dest, $replace = FILE_EXISTS_RENAME): write the $data to the specified file.
* file_set_status(&$file, $status): I'm guessing this is related to the "list" option of the upload module... or something like that.
* file_directory_temp(): get the path to the temp directory
* file_directory_path(): get the path to the files directory
* file_upload_max_size(): get the maximum upload size, probably a wrapper around the upload_max_size php setting.
* file_munge_filename($filename, $extensions, $alerts = TRUE): munge? If it's english, I'll guess it's related to the french word "manger" (to eat), but I'm not sure what it could mean in this context.
* file_unmunge_filename($filename): easy! it's just the opposite of the previous munging thingy.
* file_space_used($uid = NULL): the function name would make me think "space used by a file", the function signature "space used by a user's files".
* file_validate_name_length($file): make sure that the name of the file is not too long (for the underlying filesystem?).
* file_validate_extensions($file, $extensions): check that the file has one of the specified extensions.
* file_validate_size($file, $file_limit = 0, $user_limit = 0): check that the file isn't too big according to various parameters (per file, per user).
* file_validate_is_image(&$file): check that the file is an image.
* file_validate_image_resolution(&$file, $maximum_dimensions = 0, $minimum_dimensions = 0): check that the image has a certain size. Shouldn't this function be related to images rather than files?
* file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME): copy a file from one location to another, with some control on whether to ovewrite existing files.
* file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME): move a file from one location to another, with some control on whether to ovewrite existing files.
* file_delete($path): delete a file.

Wow, that was fun. We do have some nice refactoring waiting to be done.

So, I'll give it a try as

Frando's picture

So, I'll give it a try as well. Even if I worked with some (few) of the functions here in the past, I'm ignoring this knowledge and just writing what I'd expect when reading the function names.

file_create_url($path)
Pass in a filesystem path to a file, get out the URL to use in HTML code

file_create_path($dest = 0)
This is quite unclear, one could think of creating a path for a just uploaded file, or of passing in a file object and returning its full path.

file_check_directory(&$directory, $mode = 0, $form_item = NULL)
Check if the directory is writeable

file_check_path(&$path)
Check if the path is a valid filesystem path

file_check_location($source, $directory = '')
Check if $source can safely be moved to $directory?

file_create_filename($basename, $directory)
Create the full filename including it's filesystem path from its name and directory

file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0)
Get a list of all files in $dir matching $mask, optionally recursing through subdirectories

file_destination($destination, $replace)
unclear

file_transfer($source, $headers)
Init a file transfer, optionally set $headers to switch between displaying the file in the browser or downloading it?

file_download()
Unclear what's the difference to file_transfer

file_save_upload($source, $validators = array(), $dest = FALSE, $replace = FILE_EXISTS_RENAME)
Save the file that was just uploaded to $dest

file_save_data($data, $dest, $replace = FILE_EXISTS_RENAME)
One could think of saving $data as the contents of the $dest file (so, a wrapper for file_put_contents)

file_set_status(&$file, $status)
Set a status flag - unclear, though, if operating on the file-object/database layer, or if we're talking about filesystem status like chmod/readable-writeable/etc

file_directory_temp()
Get the file system path to a temp directory

file_directory_path()
Get the file system path to the site's file directory

file_upload_max_size()
Get the max. upload size

file_munge_filename($filename, $extensions, $alerts = TRUE)
Create a valid, save filename from the $filename of the uploaded file

file_unmunge_filename($filename)
Undo file_munge_filenmae, return the original name?

file_space_used($uid = NULL)
Hard disc space used by user $uid

file_validate_name_length($file)
file_validate_extensions($file, $extensions)
file_validate_size($file, $file_limit = 0, $user_limit = 0)
file_validate_is_image(&$file)
file_validate_image_resolution(&$file, $maximum_dimensions = 0, $minimum_dimensions = 0)
These are all quite clear

file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME)
file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME)
file_delete($path)
And these as well

I feel your pain

Dave Cohen's picture

In a moment of frustration I wrote this comment in one of my own modules:

<?php
/**
* What's the difference between file_check_upload and file_save_upload?
*
* Answer: I can't figure that out, but I don't care, because neither one does
* what we want.
*
* ...
*
*/
?>

file_delete_directory($dir, $recurse = TRUE) ?

hass's picture

For modules implementing local file caching features (google analytics, xmlsitemap, simpletest, etc.) it would be very helpful if we have a rmdir functionality that works recursive and OS independent. As PHP does not provide this functionality out of the box you are made to delete every file one by one and then the directory. This should better be done in a core function. Maybe the name of this function could become:

file_delete_directory($dir, $recurse = TRUE)

It should also provide a true/false as return code if the delete failed.

My answers

axyjo@drupal.org's picture
* file_create_url($path) - Adds a file so that it's downloadable?
* file_create_path($dest = 0) - Creates a directory?
* file_check_directory(&$directory, $mode = 0, $form_item = NULL) - Checks if a directory exists?
* file_check_path(&$path) - Check if a path exists?
* file_check_location($source, $directory = '') - Checks if the location is the same of $source and $directory?
* file_create_filename($basename, $directory) - creates a blank file?
* file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0) - returns an array of all files in $dir?
* file_destination($destination, $replace) - moves a file
* file_transfer($source, $headers) - sends a file to the user
* file_download() - sends the file to the user again
* file_save_upload($source, $validators = array(), $dest = FALSE, $replace = FILE_EXISTS_RENAME) - saves form submitted data
* file_save_data($data, $dest, $replace = FILE_EXISTS_RENAME) - saves data to a file? fwrite?!
* file_set_status(&$file, $status) - sets a chmod status
* file_directory_temp() - returns the /tmp directory location
* file_directory_path() returns the sites/default/files location
* file_upload_max_size() - PHP maximum upload size
* file_munge_filename($filename, $extensions, $alerts = TRUE) - WTH?
* file_unmunge_filename($filename) - WTH, part 2.
* file_space_used($uid = NULL) - Disk space usage?
* file_validate_name_length($file) - checks if the file length is below the DB limit
* file_validate_extensions($file, $extensions) - checks extension on file
* file_validate_size($file, $file_limit = 0, $user_limit = 0) - checks file size
* file_validate_is_image(&$file) - checks if the file is an image
* file_validate_image_resolution(&$file, $maximum_dimensions = 0, $minimum_dimensions = 0) - check the resolution of an image
* file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) - copy a file from $source to $dest
* file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) - move...
* file_delete($path) - delete a file.

I just read the docs a few days ago, so my score may be a bit better.

File API

Group organizers

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds: