imageGenerator

gistfile1.aw

<?php
/**
 * image Generator -- see trac ticket #778
 *
 * takes an image and does some magic on it.
 */
/**
 * Resizes an image
 *
 * Once an image has been generated by this function, it is cached and subsequent
 * calls with the same parameters needn't bother regenerating the resized image.
 * Hands the actual image generation off to /images/image.php
 *
 * @param string    $filename file name for image
 * @param array     $options  various resize options:
 *                      If neither width nor height is passed in, the function uses
 *                      the image's existing width and height. If just one is passed in,
 *                      a proportional size is assumed.
 *                          width:    desired image width in pixels.
 *                          height:   desired image height in pixels.
 *
 *                          stretch:  aspect ratio adjustment: defaults to FALSE to resize
 *                                    the image proportionally, (will crop if necessary)
 *                                    or can be set to TRUE to anamorphically "stretch"
 *                                    the image to fit the new size.
 *
 *                      Occasionally a user  might try to scale an image to be larger than its
 *                      source-image, which leads to pixellation / blockiness: 
 *                          upscale:  If passed a value that evaluates to Boolean TRUE the image will
 *                                    be scaled up anyway, otherwise the image will be shown at its
 *                                    native scale.
 *
 *                      Cropping: Only an issue if stretch is FALSE, ignored otherwise.
 *                          crop:     position of crop (if needed)
 *                                    from -1 (left edge) to 1 (right edge) if cropping horizontally,
 *                                    from -1 (top edge) to 1 (bottom edge) if cropping vertically.
 *                                    Defaults to 0 (centre).
 *
 *                      The following options apply HTML attributes to the returned
 *                      HTML string: If empty-string or null, the returned HTML image
 *                      string will not have the relevant attribute.
 *                          class:    HTML class attribute for css hooks.
 *                          id:       HTML id attribute for css hooks.
 *                          alt-text: HTML alt-text for the image.
 *                          title:    HTML title for the image.
 *
 * @return string   HTML string representing the generated image.
 */
function imageGenerator($filename, $options=array()) {
    // double check we're using the right path to the images folder, as whoever is invoking this function may try passing either the image filename, or a full path.
    $filename = HOME . 'images/' . basename($filename);

    if (!file_exists($filename)) {
        $filename = HOME . 'images/1col.png';
        if (!isset($options['alt'])) {
            $options['alt-text'] = 'Placeholder image';
        }
    }

    // Find the current width and height of the image
    list($width, $height) = getimagesize($filename);

    // Force all height/width into integer values. No fractional pixels!

    // It's possible that the user pass in neither width nor height...
    if (!isset($options['width']) && !isset($options['height'])) {
        // will already be integers...
        $dst_w = $width; // Short for "Destination Width", but $dst_w is used in the php documentation.
        $dst_h = $height; // Destination Height as above
    }
    // ...but it's far more likely that at least one of them is passed in...
    elseif (!isset($options['width'])) {
        $dst_w = (int)round($width * $options['height'] / $height);
        $dst_h = (int)$options['height'];
    }
    elseif (!isset($options['height'])) {
        $dst_w = (int)$options['width'];
        $dst_h = (int)round($height * $options['width'] / $width);
    }
    // ... and they might even pass both in.
    else {
        $dst_w = (int)$options['width'];
        $dst_h = (int)$options['height'];
    }

	// Don't allow upscaling *unless* upscale option is set and true:
	$upscale_flag_is_true = isset($options['upscale']) && $options['upscale'] == TRUE; // (use == to allow anything that evaluates to TRUE, e.g. 1, "yes", etc.)
    if (!$upscale_flag_is_true && ($dst_w > $width || $dst_h > $height)) {
	    $dst_w = $width;
		$dst_h = $height;
		$options['crop'] = 0;
		$options['stretch'] = FALSE;
    }

    // have crop, stretch been passed in? If not, set them up; if so clean them up.
    // It's probably not entirely necessary to sanitise inputs, but even if someone
    // passes insane values in, we want some output.
    $options['crop']    = (!isset($options['crop']))    ? 0     : 1.0 * $options['crop'];
    $options['stretch'] = (!isset($options['stretch'])) ? false : (bool)$options['stretch'];

    // We want a filename for the cached and resized version of the file.
    $filename_query = '/site/custom_scripts/image.php?' . http_build_query(array(
        'w' => $dst_w,
        'h' => $dst_h,
        'crop' => $options['crop'],
        'stretch' => $options['stretch'],
        'filename' => basename($filename),
    ));
    return imageGeneratorToHtml($filename_query, $options['class'], $options['id'], $options['alt-text'], $options['title']);
}

/**
 * HTML helper for previous function
 *
 * @param string    $filename   file name for image
 * @param string    $class      HTML class attribute for css hooks.
 * @param string    $id         HTML id attribute for css hooks.
 * @param string    $alt_text   HTML alt-text for the image.
 * @param string    $title      HTML title for the image.
 */
function imageGeneratorToHtml($filename, $class='', $id='', $alt_text='', $title='') {
    $output = "<img src=\"{$filename}\"";
    if ($class != '') $output .= " class=\"{$class}\"";
    if ($id != '') $output .= " id=\"{$id}\"";
    if ($alt_text != '') $output .= " alt=\"{$alt_text}\"";
    if ($title != '') $output .= " title=\"{$title}\"";
    $output .= '>';
    return $output;
}
?>