aboutsummaryrefslogtreecommitdiffstats
path: root/include/derivative.inc.php
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2013-11-29 13:48:55 +0000
committermistic100 <mistic@piwigo.org>2013-11-29 13:48:55 +0000
commit7297e1cfae7ffe7cbf62d047fc3b16e2757df09d (patch)
tree916f8a127083a04f317a0cf7b7569209fe047af3 /include/derivative.inc.php
parent91b6a0137dc6b703604f9c2720ee887b13b08020 (diff)
feature 2999 : Documentation of multisize classes
git-svn-id: http://piwigo.org/svn/trunk@25754 68402e56-0260-453c-a942-63ccdbb3a9ee
Diffstat (limited to '')
-rw-r--r--include/derivative.inc.php138
1 files changed, 117 insertions, 21 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;