diff options
| -rw-r--r-- | include/derivative.inc.php | 138 | ||||
| -rw-r--r-- | include/derivative_params.inc.php | 179 | ||||
| -rw-r--r-- | include/derivative_std_params.inc.php | 83 |
3 files changed, 348 insertions, 52 deletions
diff --git a/include/derivative.inc.php b/include/derivative.inc.php index 6821817fe..cb368ac69 100644 --- a/include/derivative.inc.php +++ b/include/derivative.inc.php @@ -19,22 +19,36 @@ // | USA. | // +-----------------------------------------------------------------------+ -/*A source image is used to get a derivative image. A source image is either the original file for a jpg or a -'representative' image of a non image file or a standard icon for the non-image file.*/ +/** + * @package Derivatives + */ + + +/** + * A source image is used to get a derivative image. It is either + * the original file for a jpg/png/... or a 'representative' image + * of a non image file or a standard icon for the non-image file. + */ final class SrcImage { const IS_ORIGINAL = 0x01; const IS_MIMETYPE = 0x02; const DIM_NOT_GIVEN = 0x04; + /** @var int */ public $id; + /** @var string */ public $rel_path; + /** @var int */ public $rotation = 0; - + /** @var int[] */ private $size=null; + /** @var int */ private $flags=0; - /*@param infos assoc array of data from images table*/ + /** + * @param array $infos assoc array of data from images table + */ function __construct($infos) { global $conf; @@ -88,21 +102,33 @@ final class SrcImage } } + /** + * @return bool + */ function is_original() { return $this->flags & self::IS_ORIGINAL; } + /** + * @return bool + */ function is_mimetype() { return $this->flags & self::IS_MIMETYPE; } + /** + * @return string + */ function get_path() { return PHPWG_ROOT_PATH.$this->rel_path; } + /** + * @return string + */ function get_url() { $url = get_root_url().$this->rel_path; @@ -113,12 +139,17 @@ final class SrcImage return embellish_url($url); } + /** + * @return bool + */ function has_size() { return $this->size != null; } - /* @return a 2-element array containing width/height or null if dimensions are not available*/ + /** + * @return int[]|null 0=width, 1=height or null if fail to compute size + */ function get_size() { if ($this->size == null) @@ -137,19 +168,29 @@ final class SrcImage } -/*Holds information (path, url, dimensions) about a derivative image. A derivative image is constructed from a source -image (SrcImage class) and derivative parameters (DerivativeParams class). -*/ +/** + * Holds information (path, url, dimensions) about a derivative image. + * A derivative image is constructed from a source image (SrcImage class) + * and derivative parameters (DerivativeParams class). + */ final class DerivativeImage { + /** @var SrcImage */ public $src_image; - + /** @var array */ private $params; - private $rel_path, $rel_url, $is_cached=true; + /** @var string */ + private $rel_path; + /** @var string */ + private $rel_url; + /** @var bool */ + private $is_cached=true; - /* - @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object - @param src_image the source image of this derivative*/ + /** + * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*) + * or a DerivativeParams object + * @param SrcImage $src_image the source image of this derivative + */ function __construct($type, SrcImage $src_image) { $this->src_image = $src_image; @@ -165,16 +206,25 @@ final class DerivativeImage self::build($src_image, $this->params, $this->rel_path, $this->rel_url, $this->is_cached); } + /** + * Generates the url of a thumbnail. + * + * @param array|SrcImage $infos array of info from db or SrcImage + * @return string + */ static function thumb_url($infos) { return self::url(IMG_THUMB, $infos); } /** - @return derivative image url - @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object - @param infos assoc array of data from images table or a SrcImage object - */ + * Generates the url for a particular photo size. + * + * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*) + * or a DerivativeParams object + * @param array|SrcImage $infos array of info from db or SrcImage + * @return string + */ static function url($type, $infos) { $src_image = is_object($infos) ? $infos : new SrcImage($infos); @@ -193,7 +243,7 @@ final class DerivativeImage /** * Return associative an array of all DerivativeImage for a specific image. - * Disabled derivative types can be still found in the return mapped to an + * Disabled derivative types can be still found in the return, mapped to an * enabled derivative (e.g. the values are not unique in the return array). * This is useful for any plugin/theme to just use $deriv[IMG_XLARGE] even if * the XLARGE is disabled. @@ -228,7 +278,7 @@ final class DerivativeImage * Returns an instance of DerivativeImage for a specific image and size. * Disabled derivatives fallback to an enabled derivative. * - * @param string $type + * @param string $type standard derivative param type (e.g. IMG_*) * @param array|SrcImage $src_image array of info from db or SrcImage * @return DerivativeImage|null null if $type not found */ @@ -254,6 +304,9 @@ final class DerivativeImage return null; } + /** + * @todo : documentation of DerivativeImage::build + */ private static function build($src, &$params, &$rel_path, &$rel_url, &$is_cached=null) { if ( $src->has_size() && $params->is_identity( $src->get_size() ) ) @@ -334,11 +387,17 @@ final class DerivativeImage } } + /** + * @return string + */ function get_path() { return PHPWG_ROOT_PATH.$this->rel_path; } + /** + * @return string + */ function get_url() { if ($this->params == null) @@ -352,12 +411,17 @@ final class DerivativeImage ) ); } + /** + * @return bool + */ function same_as_source() { return $this->params == null; } - + /** + * @return string one if IMG_* or 'Original' + */ function get_type() { if ($this->params == null) @@ -365,7 +429,9 @@ final class DerivativeImage return $this->params->type; } - /* returns the size of the derivative image*/ + /** + * @return int[] + */ function get_size() { if ($this->params == null) @@ -375,6 +441,11 @@ final class DerivativeImage return $this->params->compute_final_size($this->src_image->get_size()); } + /** + * Returns the size as CSS rule. + * + * @return string + */ function get_size_css() { $size = $this->get_size(); @@ -384,6 +455,11 @@ final class DerivativeImage } } + /** + * Returns the size as HTML attributes. + * + * @return string + */ function get_size_htm() { $size = $this->get_size(); @@ -393,6 +469,11 @@ final class DerivativeImage } } + /** + * Returns literal size: $widthx$height. + * + * @return string + */ function get_size_hr() { $size = $this->get_size(); @@ -402,6 +483,11 @@ final class DerivativeImage } } + /** + * @param int $maxw + * @param int $mawh + * @return int[] + */ function get_scaled_size($maxw, $maxh) { $size = $this->get_size(); @@ -426,6 +512,13 @@ final class DerivativeImage return $size; } + /** + * Returns the scaled size as HTML attributes. + * + * @param int $maxw + * @param int $mawh + * @return string + */ function get_scaled_size_htm($maxw=9999, $maxh=9999) { $size = $this->get_scaled_size($maxw, $maxh); @@ -435,6 +528,9 @@ final class DerivativeImage } } + /** + * @return bool + */ function is_cached() { return $this->is_cached; diff --git a/include/derivative_params.inc.php b/include/derivative_params.inc.php index 31c76bed7..b0b9d67e3 100644 --- a/include/derivative_params.inc.php +++ b/include/derivative_params.inc.php @@ -19,11 +19,28 @@ // | USA. | // +-----------------------------------------------------------------------+ +/** + * @package Derivatives + */ + + +/** + * Formats a size name into a 2 chars identifier usable in filename. + * + * @param string $t one of IMG_* + * @return string + */ function derivative_to_url($t) { return substr($t, 0, 2); } +/** + * Formats a size array into a identifier usable in filename. + * + * @param int[] $s + * @return string + */ function size_to_url($s) { if ($s[0]==$s[1]) @@ -33,26 +50,55 @@ function size_to_url($s) return $s[0].'x'.$s[1]; } +/** + * @param int[] $s1 + * @param int[] $s2 + * @return bool + */ function size_equals($s1, $s2) { return ($s1[0]==$s2[0] && $s1[1]==$s2[1]); } +/** + * Converts a char a-z into a float. + * + * @param string + * @return float + */ function char_to_fraction($c) { return (ord($c) - ord('a'))/25; } +/** + * Converts a float into a char a-z. + * + * @param float + * @return string + */ function fraction_to_char($f) { return chr(ord('a') + round($f*25)); } -/** small utility to manipulate a 'rectangle'*/ + +/** + * Small utility to manipulate a 'rectangle'. + */ final class ImageRect { + /** + * @var int $l + * @var int $t + * @var int $r + * @var int $b + */ public $l,$t,$r,$b; + /** + * @param int[] $l width and height + */ function __construct($l) { $this->l = $this->t = 0; @@ -60,19 +106,28 @@ final class ImageRect $this->b = $l[1]; } + /** + * @return int + */ function width() { return $this->r - $this->l; } + /** + * @return int + */ function height() { return $this->b - $this->t; } - /** crops horizontally this rectangle by increasing left side and/or reducing the right side. - @param pixels the amount to substract from the width - @param coi a 4 character string (or null) containing the center of interest*/ + /** + * Crops horizontally this rectangle by increasing left side and/or reducing the right side. + * + * @param int $pixels - the amount to substract from the width + * @param stirng $coi - a 4 character string (or null) containing the center of interest + */ function crop_h($pixels, $coi) { if ($this->width() <= $pixels) @@ -101,9 +156,12 @@ final class ImageRect $this->r -= $pixels - $tlcrop; } - /** crops vertically this rectangle by increasing top side and/or reducing the bottom side. - @param pixels the amount to substract from the height - @param coi a 4 character string (or null) containing the center of interest*/ + /** + * Crops vertically this rectangle by increasing top side and/or reducing the bottom side. + * + * @param int $pixels - the amount to substract from the height + * @param string $coi - a 4 character string (or null) containing the center of interest + */ function crop_v($pixels, $coi) { if ($this->height() <= $pixels) @@ -131,35 +189,63 @@ final class ImageRect $this->t += $tlcrop; $this->b -= $pixels - $tlcrop; } - } -/** Paramaters for derivative scaling and cropping. Instance of this class contained by DerivativeParams class.*/ +/** + * Paramaters for derivative scaling and cropping. + * Instance of this class contained by DerivativeParams class. + */ final class SizingParams { + /** @var int[] */ + var $ideal_size; + /** @var float */ + var $max_crop; + /** @var int[] */ + var $min_size; + /** - @param ideal_size two element array of maximum output dimensions (width, height) - @param max_crop range 0=no cropping ... 1= max cropping (100% of width/height); expressed as a factor of the input width/height - @param min_size used only if max_crop != 0 - two element array of output dimensions (width, height) - */ - function __construct($ideal_size, $max_crop = 0, $min_size = null) + * @param int[] $ideal_size - two element array of maximum output dimensions (width, height) + * @param float $max_crop - from 0=no cropping to 1= max cropping (100% of width/height); + * expressed as a factor of the input width/height + * @param int[] $min_size - (used only if _$max_crop_ !=0) two element array of output dimensions (width, height) + */ + function __construct($ideal_size, $max_crop=0, $min_size=null) { $this->ideal_size = $ideal_size; - $this->max_crop = $max_crop; // range 0=no cropping ... 1= max cropping (100% of width/height) + $this->max_crop = $max_crop; $this->min_size = $min_size; } + /** + * Returns a simple SizingParams object. + * + * @param int $w + * @param int $h + * @return SizingParams + */ static function classic($w, $h) { return new SizingParams( array($w,$h) ); } + /** + * Returns a square SizingParams object. + * + * @param int $x + * @return SizingParams + */ static function square($w) { return new SizingParams( array($w,$w), 1, array($w,$w) ); } + /** + * Adds tokens depending on sizing configuration. + * + * @param array &$tokens + */ function add_url_tokens(&$tokens) { if ($this->max_crop == 0) @@ -178,12 +264,14 @@ final class SizingParams } } - /* calculate the cropping rectangle and the scaled size for an input image size - @param in_size two element array of input dimensions (width, height) - @param coi empty or a four character encoded string containing the center of interest (unused if max_crop=0) - @param crop_rect output ImageRect containing the cropping rectangle or null if cropping is not required - @param scale_size output two element array containing width and height of the scaled image - */ + /** + * Calculates the cropping rectangle and the scaled size for an input image size. + * + * @param int[] $in_size - two element array of input dimensions (width, height) + * @param string $coi - four character encoded string containing the center of interest (unused if max_crop=0) + * @param ImageRect &$crop_rect - ImageRect containing the cropping rectangle or null if cropping is not required + * @param int[] &$scale_size - two element array containing width and height of the scaled image + */ function compute($in_size, $coi, &$crop_rect, &$scale_size) { $destCrop = new ImageRect($in_size); @@ -245,50 +333,81 @@ final class SizingParams $crop_rect = $destCrop; } } - } -/** All needed parameters to generate a derivative image.*/ +/** + * All needed parameters to generate a derivative image. + */ final class DerivativeParams { - public $type = IMG_CUSTOM; // string IMG_xxx - public $last_mod_time = 0; // used for non-custom images to regenerate the cached files + /** @var SizingParams */ + public $sizing; + /** @var string among IMG_* */ + public $type = IMG_CUSTOM; + /** @var int used for non-custom images to regenerate the cached files */ + public $last_mod_time = 0; + /** @var bool */ public $use_watermark = false; - public $sizing; // of type SizingParams - public $sharpen = 0; // range 0= no sharpening ... 1= max sharpening + /** @var float from 0=no sharpening to 1=max sharpening */ + public $sharpen = 0; + /** + * @param SizingParams $sizing + */ function __construct($sizing) { $this->sizing = $sizing; } + /** + * @return array + */ public function __sleep() { - return array('last_mod_time', 'sizing', 'sharpen'); + return array('last_mod_time', 'sizing', 'sharpen'); } + /** + * Adds tokens depending on sizing configuration. + * + * @param array &$tokens + */ function add_url_tokens(&$tokens) { $this->sizing->add_url_tokens($tokens); } + /** + * @return int[] + */ function compute_final_size($in_size) { $this->sizing->compute( $in_size, null, $crop_rect, $scale_size ); return $scale_size != null ? $scale_size : $in_size; } + /** + * @return int + */ function max_width() { return $this->sizing->ideal_size[0]; } + /** + * @return int + */ function max_height() { return $this->sizing->ideal_size[1]; } + /** + * @todo : description of DerivativeParams::is_identity + * + * @return bool + */ function is_identity($in_size) { if ($in_size[0] > $this->sizing->ideal_size[0] or @@ -299,6 +418,9 @@ final class DerivativeParams return true; } + /** + * @return bool + */ function will_watermark($out_size) { if ($this->use_watermark) @@ -310,4 +432,5 @@ final class DerivativeParams return false; } } + ?>
\ No newline at end of file diff --git a/include/derivative_std_params.inc.php b/include/derivative_std_params.inc.php index 649120033..e015a7c51 100644 --- a/include/derivative_std_params.inc.php +++ b/include/derivative_std_params.inc.php @@ -19,6 +19,11 @@ // | USA. | // +-----------------------------------------------------------------------+ +/** + * @package Derivatives + */ + + define('IMG_SQUARE', 'square'); define('IMG_THUMB', 'thumb'); define('IMG_XXSMALL', '2small'); @@ -30,54 +35,98 @@ define('IMG_XLARGE', 'xlarge'); define('IMG_XXLARGE', 'xxlarge'); define('IMG_CUSTOM', 'custom'); + +/** + * Container for watermark configuration. + */ final class WatermarkParams { + /** @var string */ public $file = ''; + /** @var int[] */ public $min_size = array(500,500); + /** @var int */ public $xpos = 50; + /** @var int */ public $ypos = 50; + /** @var int */ public $xrepeat = 0; + /** @var int */ public $opacity = 100; } +/** + * Container for standard derivatives parameters. + */ final class ImageStdParams { + /** @var string[] */ private static $all_types = array( - IMG_SQUARE,IMG_THUMB,IMG_XXSMALL,IMG_XSMALL,IMG_SMALL,IMG_MEDIUM,IMG_LARGE,IMG_XLARGE,IMG_XXLARGE + IMG_SQUARE, IMG_THUMB, IMG_XXSMALL, IMG_XSMALL, IMG_SMALL, + IMG_MEDIUM, IMG_LARGE, IMG_XLARGE, IMG_XXLARGE ); + /** @var DerivativeParams[] */ private static $all_type_map = array(); + /** @var DerivativeParams[] */ private static $type_map = array(); + /** @var DerivativeParams[] */ private static $undefined_type_map = array(); + /** @var WatermarkParams */ private static $watermark; + /** @var array */ public static $custom = array(); + /** @var int */ public static $quality=95; + /** + * @return string[] + */ static function get_all_types() { return self::$all_types; } + /** + * @return DerivativeParams[] + */ static function get_all_type_map() { return self::$all_type_map; } + /** + * @return DerivativeParams[] + */ static function get_defined_type_map() { return self::$type_map; } + /** + * @return DerivativeParams[] + */ static function get_undefined_type_map() { return self::$undefined_type_map; } + /** + * @return DerivativeParams + */ static function get_by_type($type) { return self::$all_type_map[$type]; } + /** + * @param int $w + * @param int $h + * @param float $crop + * @param int $minw + * @param int $minh + * @return DerivativeParams + */ static function get_custom($w, $h, $crop=0, $minw=null, $minh=null) { $params = new DerivativeParams( new SizingParams( array($w,$h), $crop, array($minw,$minh)) ); @@ -94,11 +143,17 @@ final class ImageStdParams return $params; } + /** + * @return WatermarkParams + */ static function get_watermark() { return self::$watermark; } + /** + * Loads derivative configuration from database or initializes it. + */ static function load_from_db() { global $conf; @@ -121,11 +176,19 @@ final class ImageStdParams self::build_maps(); } + /** + * @param WatermarkParams $watermark + */ static function set_watermark($watermark) { self::$watermark = $watermark; } + /** + * @see ImageStdParams::save() + * + * @param DerivativeParams[] $map + */ static function set_and_save($map) { self::$type_map = $map; @@ -133,6 +196,9 @@ final class ImageStdParams self::build_maps(); } + /** + * Saves the configuration in database. + */ static function save() { global $conf; @@ -146,6 +212,9 @@ final class ImageStdParams conf_update_param('derivatives', addslashes($ser) ); } + /** + * @return DerivativeParams[] + */ static function get_default_sizes() { $arr = array( @@ -159,13 +228,19 @@ final class ImageStdParams IMG_XLARGE => new DerivativeParams( SizingParams::classic(1224,918) ), IMG_XXLARGE => new DerivativeParams( SizingParams::classic(1656,1242) ), ); + $now = time(); foreach($arr as $params) { - $params->last_mod_time = time(); + $params->last_mod_time = $now; } return $arr; } + /** + * Compute 'apply_watermark' + * + * @param DerivativeParams $params + */ static function apply_global($params) { $params->use_watermark = !empty(self::$watermark->file) && @@ -173,6 +248,9 @@ final class ImageStdParams or self::$watermark->min_size[1]<=$params->sizing->ideal_size[1] ); } + /** + * Build 'type_map', 'all_type_map' and 'undefined_type_map'. + */ private static function build_maps() { foreach (self::$type_map as $type=>$params) @@ -200,7 +278,6 @@ final class ImageStdParams } } } - } ?>
\ No newline at end of file |