Object.Event

PhotoFolder

JSON Image Gallery API + Automatic Thumbnails

Tutorial
API

What it Does

PhotoFolder scans a given folder for JPEG files with any number of thumbnail sizes per image. If the resized images do not yet exist, it will automatically create the thumbnails for you. It then returns a JSON or PHP array of sizes and dimensions for all images in the folder. The result is that your workflow for adding new images to an application built with PhotoFolder is a simple as putting named JPEG files in any directory.

PhotoFolder is not a fully fledged gallery system. It does the heavy lifting for you and exposes an API via PHP or JSON for integration with any Ajax application, or other system that can parse JSON.

Demo

Below is a link to my personal photography portfolio. The Ajax front end makes calls to PhotoFolder when you select a new category. Some of the photos are just snapshots of friends and family. Most of the abstract or landscape photos are available for sale. If you are interested contact me. Note that the demo is not PhotoFolder itself, but my own application written on top of PhotoFolder. Feel free to use my code in the gallery, but note that it is not supported or available for download.

Click to Enter PhotoFolder Sample Gallery

Requirements

PhotoFolder requires PHP 5+ with the GD image library, and some programming knowledge. For multilingual support you are better off using PHP 5.2+ since it will do the JSON encoding natively.

Any files that end in .jpg inside a folder that is scanned by PhotoFolder will be resized. File names must not already contain the size name preceded by a period. i.e. don't name anything "large.jpg", "picture.large.jpg". "my_large_picture.jpg" would not cause a conflict however

Installation & Configuration

Download the photo_folder.php via the link in the upper right hander corner of this page, then upload it on your webserver of choice. Then open the photo_folder.php file and find these configuration values near the top of the file:


class PhotoFolder {
    const EXPOSE_API = true;
    const BASE_DIR = 'photos/';
    const JPEG_QUALITY = 95;
    static protected $sizes = array(
        'large' => array(900,false),
        'medium' => array(400,false),
        'small' => array(75,true)
    );

The first three values are hopefully self explanatory. The sizes array can contain as many sizes as you would like. The sizes array consists of the name of the size as the key, and array(maximum_dimension,is_square) as the key. Given the $sizes array above, if an image in a folder was named "My_Picture.jpg", the following files will be created (and "My_Picture.jpg" will remain untouched):

My_Picture.large.jpg - (aspect ratio preserved, maximum dimension 900px)
My_Picture.medium.jpg - (aspect ratio preserved, maximum dimension 400px)
My_Picture.small.jpg - (75px x 75px square)

Sample Calls


//javascript
new Ajax.Request('path/to/photo_folder.php?dir=' + dir,{
    onComplete: function(request){
        var files = request.responseText.evalJSON();
        //...
    }
});
//php
require 'photo_folder.php';
foreach(PhotoFolder::getFileList($dir) as $base_name => $sizes){
	//...
}

Return Value Format

Wether using it in another PHP script, or with an Ajax request as JSON, a folder with the various sizes of "My_Picture.jpg" would return something like this:

{
    'My_Picture': { 
        'original': {'height': 900, 'width': 600},
        'large': {'height': 900, 'width': 600},
        'medium': {'height': 400, 'width': 266},
        'small': {'height': 75, 'width': 75}
    }
}

The file extensions and full names are intentionally not included to allow you to easily construct the URLs as nessecary, as opposed to calling replace() a bunch of times.

PhotoFolder Class Properties

Return	Name	Default	Description
boolean	const EXPOSE_API	true	Wether or not to allow GET calls to the script by default.
string	const BASE_DIR	'photos/'	The directory relative to the photo_folder.php file to start from.
int	const JPEG_QUALITY	95	Quality 1 - 100
array	static protected $sizes	array(...)	Array of sizes in 'name' => array(max_dimension,is_square) format

PhotoFolder Class Methods

Return	Name	Description
mixed	static public getDirectoryList($json = false)	Returns a list of directories as an array or a JSON string.
mixed	static public getFileList($directory,$json = false)	Returns a list of image files and dimensions in a given directory.

PhotoFolder GET / REST API

photo_folder.php?dirs - returns PhotoFolder::getDirectoryList(true)
photo_folder.php?dir=[DIR] - returns PhotoFolder::getFileList([DIR],true)

LivePipe™