WordPress File and Image Utility

Over the course of the past few months, I have put together a nice utility that has many functions to work with files and images in WordPress. After discussing the idea with Cory, we have decided to release this code to the public. Our hope is that plugin developers and theme designers can spend their time producing great plugins and themes rather than being bogged down in the details of working with files and images.

The Code

You can download the latest version of the utility below:

Chris Jean’s File Utility version 1.4.1

Simply unzip the contained file anywhere you’d like to use it or to your plugins directory to activate it as a plugin.

I have added the ability for this code to work as a plugin to make it easy for developers and designers to quickly try out the functions; however, the code really should be used as a library and use require or include to load the code for use. The plugin is called “Chris Jean’s File Utility”. I know that it’s narcissistic of me to name it after myself, but I couldn’t think of anything else to call it.

The code definitely could be improved. Toward the top is a TODO section where I have included some ideas of what I think could be added or changed to improve the functionality. I’d love to hear ideas that you have. You can leave a comment here or contact me directly on my site.

Features

The utility has a variety of features. The following list details what the utility is currently capable of.

• Easy file uploading complete with adding the file to the media library
• Image resizing with the following options and features:
  • max width/height
  • option to crop image to match resize dimensions
  • easily defined destination
  • set jpeg quality
  • set format (you can convert the image from a jpg to a gif)
  • resizes png images while preserving transparency
  • resizes animated images
  • the resized image doesn’t replace the original
  • new images are only produced as needed
• Convert a file URL to a file path
• Convert a file path to a file URL
• Determine MIME type
• Easily get file attachment data
• Delete file attachments and their files
• Determine if a file is an animated gif

Examples

I always hope to produce self-explanitory code, but I’m sure that some explanation through examples would be helpful.

Uploading Files

You have a form that has a file input, but you aren’t sure how to handle the file once it has been sent to your code. The upload_file function can handle this situation easily.

The file will be uploaded to the site’s upload destination in the same way that the WordPress core uploads files in the “Add an Image” dialog. The file will also be added to the Media library so that the site user can find the file for other uses.

So, if the form has been submitted with a file input with a name of “uploaded_file”, the following code will handle the upload for you:

// Assuming that the library is in the same directory.
require_once( 'chris-jean-file-utility.php' );

$file = CJFileUtility::upload_file( 'uploaded_file' );

The resulting $file variable is an array that contains the upload’s details

• $file['url'] – URL location of the file
• $file['file'] – Absolute path location for the file
• $file['id'] – ID of the media attachment for the file
• $file['type'] – MIME type of the file
• $file['title'] – Title of the attachment for the file
• $file['caption'] – Content of the attachment for the file

Resizing an Image

There are two features of the resize_image function that are important to know. First, the original image is never replaced; rather, new images that have the resize details in the name are created. Second, new image files are only produced if a resized image file doesn’t already exist or if the existing file has a modified date older than the source file (resized images will be recreated if the source image file is updated).

The resize_image function accepts the following attributes, in order:

• file
• max_w (default 0)
• max_h (default 0)
• crop (default true)
• suffix (default null)
• dest_path (default null)
• jpeg_quality (default 90)
• format (default null)

On success, an array with the following details is returned:

• file – Absolute path of the resized file
• url – URL location of the resized file
• name – The file name without the path

If an error occurs, an instance of WP_Error is returned with the error details.

The following is a quick example of how to use the resize_image function:

// Assuming that the library is in the same directory.
require_once( 'chris-jean-file-utility.php' );

$thumbnail = CJFileUtility::resize_image( "/path/to/file.jpg", 100, 100, true );

if ( is_wp_error( $thumbnail ) )
    echo "<!-- Resize Error: " . $thumbnail->get_error_message() . " -->";
else
    echo "<img src='${thumbnail['name']}' title='${thumbnail['url']}'
        alt='' width='100' height='100' />";

More Examples to Come