// // Scry - Simple PHP Photo Album // Copyright 2004 James Byers // http://scry.org // // Scry is distributed under a BSD License. See LICENSE for details. // // $Id: DESIGN,v 1.8 2004/10/02 01:20:57 jbyers Exp $ // Structure ------------------------------------------------------------------------------ index.php controller functions.php common functions setup.php configuration views/ views list.php directory, thumbnail list view.php picture details image.php image loader templates/ PHP + XHTML template files Control Flow ------------------------------------------------------------------------------ Scry has three views: list renders a listing of subdirectories and image thumbnails in the current directory with optional pagination view renders a single image with links to previous and next image loads and resizes the target image, optionally caching to disk index.php is the controller. The view is selected based on the URL as described below. index.php sets up any global variables and then delegates control to the view. Security ------------------------------------------------------------------------------ All filesystem calls (reads, writes, and Scry functions) are marked with "FS [TYPE]". Each file also contains a security header comment denoting critical path variables. These variables are scrubbed and tested via the path_security_check function, verifying the resolved paths (actual path when considering multiple slashes, ., and ..) are within the configured image paths. If $CFG_resize_external is set, scry will attempt to use this as an external command for resizing images. Before executing this command, Scry scrubs it to remove shell metacharacters. This feature is purely optional and the exec call is marked with EXEC. Scry does not use any PHP network functions. Variables ------------------------------------------------------------------------------ Configuration variables are all contained in setup.php and prefixed with 'CFG'. Scry assumes that register_globals is off, and references only the $_SERVER and $_GET superglobals. URLs ------------------------------------------------------------------------------ Scry can operate in two variable modes, "get" and "path", as set by $CFG_variable_mode. In GET mode, the controller parses three variables for use by the views: name description value ----- ------------ ------ i index integer offset or image size WxH p path [relative path to image] v view (list|view|image) A get mode URL might look like: http://[server]/[scry_path]/index.php?v=[view]&i=[index]&p=[image_path] Path mode uses slash-separated values instead of HTTP GET values. This mode offers a cleaner URL layout - at least aesthetically. http://[server]/[scry_path]/index.php/[view]/[index]/[image_path] Path mode requires either Apache 1.3 or Apache 2.0 with the AcceptPathInfo directive set to On in httpd.conf or .htaccess. Because of this restriction, Scry defaults to get mode. Examples: list http://scry.org/photos/index.php?a=list&i=2&p=/path/to/images/ http://scry.org/photos/index.php/list/2/path/to/images/ view http://scry.org/photos/index.php?a=view&i=12&p=/path/to/images/00024601.jpg http://scry.org/photos/index.php/view/12/path/to/images/00024601.jpg image http://scry.org/photos/index.php?a=image&i=800x600&p=path/to/images/00024601.jpg http://scry.org/photos/index.php/image/800x600/path/to/images/00024601.jpg Global Variables ----------------------------------------------------------------------------- name description ---- ----------- T template variable array VIEW view name INDEX index variable (offset or image dimension) IMAGE_FILE image filename ('IMG20040201.jpg') IMAGE_DIR image directory under $CFG_path_images ('Family/2003') PATH full filesystem path to directory / image PATH_BASEDIR filesystem path to directory / image without filename Caching ----------------------------------------------------------------------------- If $CFG_cache_enable is true, Scry will cache resized images. Caching is highly recommended. If caching is off, or if you are viewing the page for the first time, the page will render at a speed proprotional to the processing speed of your webserver and the number of images on the page. Only two sizes of images will be cached: thumbnail size or view size, as set by $CFG_thumb_(width|height) and $CFG_view_(width|height). Images Outside Docroot ------------------------------------------------------------------------------ By default, Scry sends Location: headers to the browser to load cached images directly from the cache directory within the webserver's docroot. However, both the cache directory and the image directory can be located outside the docroot if desired. In this case, Scry will pass image loads through readfile() in the image.php view. See README for instructions on how to set up images outside the docroot. Resizing ------------------------------------------------------------------------------ Scry attempts to intelligently resize images for thumbnails and viewing, based on the bounds set by $CFG_thumb_(width|height) and $CFG_image_(width|height). Resized images will maintain their original aspect ratio but will not exceed the bounds above. Templates ------------------------------------------------------------------------------ Templates are simple XHTML files with looping, control, and variable blocks. 'default' is a good example of the variables Scry provides. Note that templates should only refer to variables in the $T global. Debugging ------------------------------------------------------------------------------ There are two methods for debugging Scry. The first is to use the 'debug' template by changing $CFG_path_template and $CFG_url_template variables to point to 'debug' instead of 'default'. This template dumps the value of all Scry variables. You can navigate through the views but the debug template will not display images. To debug images.php, set the $CFG_debug_image variable to true. The image view will print text debugging output. Note that if this flag is set, images in other views will appear to be broken unless you load the image view directly.