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.
- file_create_url($path)
- file_create_path($dest = 0)
- file_check_directory(&$directory, $mode = 0, $form_item = NULL)
- file_check_path(&$path)
- file_check_location($source, $directory = '')
- file_create_filename($basename, $directory)
- file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $callback = 0, $recurse = TRUE, $key = 'filename', $min_depth = 0, $depth = 0)
- file_destination($destination, $replace)
- file_transfer($source, $headers)
- file_download()
- file_save_upload($source, $validators = array(), $dest = FALSE, $replace = FILE_EXISTS_RENAME)
- file_save_data($data, $dest, $replace = FILE_EXISTS_RENAME)
- file_set_status(&$file, $status)
- file_directory_temp()
- file_directory_path()
- file_upload_max_size()
- file_munge_filename($filename, $extensions, $alerts = TRUE)
- file_unmunge_filename($filename)
- file_space_used($uid = NULL)
- 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)
- file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME)
- file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME)
- file_delete($path)
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
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?
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
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
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) ?
For modules implementing local file caching features (google analytics, xmlsitemap, simpletest, etc.) it would be very helpful if we have a
rmdirfunctionality 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
I just read the docs a few days ago, so my score may be a bit better.