Changeset 25754


Ignore:
Timestamp:
Nov 29, 2013, 2:48:55 PM (11 years ago)
Author:
mistic100
Message:

feature 2999 : Documentation of multisize classes

Location:
trunk/include
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/derivative.inc.php

    r25504 r25754  
    2020// +-----------------------------------------------------------------------+
    2121
    22 /*A source image is used to get a derivative image. A source image is either the original file for a jpg or a
    23 'representative' image of a non image file or a standard icon for the non-image file.*/
     22/**
     23 * @package Derivatives
     24 */
     25
     26
     27/**
     28 * A source image is used to get a derivative image. It is either
     29 * the original file for a jpg/png/... or a 'representative' image
     30 * of a  non image file or a standard icon for the non-image file.
     31 */
    2432final class SrcImage
    2533{
    … …  
    2836  const DIM_NOT_GIVEN = 0x04;
    2937
     38  /** @var int */
    3039  public $id;
     40  /** @var string */
    3141  public $rel_path;
     42  /** @var int */
    3243  public $rotation = 0;
    33 
     44  /** @var int[] */
    3445  private $size=null;
     46  /** @var int */
    3547  private $flags=0;
    3648
    37   /*@param infos assoc array of data from images table*/
     49  /**
     50   * @param array $infos assoc array of data from images table
     51   */
    3852  function __construct($infos)
    3953  {
    … …  
    89103  }
    90104
     105  /**
     106   * @return bool
     107   */
    91108  function is_original()
    92109  {
    … …  
    94111  }
    95112
     113  /**
     114   * @return bool
     115   */
    96116  function is_mimetype()
    97117  {
    … …  
    99119  }
    100120
     121  /**
     122   * @return string
     123   */
    101124  function get_path()
    102125  {
    … …  
    104127  }
    105128
     129  /**
     130   * @return string
     131   */
    106132  function get_url()
    107133  {
    … …  
    114140  }
    115141
     142  /**
     143   * @return bool
     144   */
    116145  function has_size()
    117146  {
    … …  
    119148  }
    120149
    121   /* @return a 2-element array containing width/height or null if dimensions are not available*/
     150  /**
     151   * @return int[]|null 0=width, 1=height or null if fail to compute size
     152   */
    122153  function get_size()
    123154  {
    … …  
    138169
    139170
    140 /*Holds information (path, url, dimensions) about a derivative image. A derivative image is constructed from a source
    141 image (SrcImage class) and derivative parameters (DerivativeParams class).
    142 */
     171/**
     172 * Holds information (path, url, dimensions) about a derivative image.
     173 * A derivative image is constructed from a source image (SrcImage class)
     174 * and derivative parameters (DerivativeParams class).
     175 */
    143176final class DerivativeImage
    144177{
     178  /** @var SrcImage */
    145179  public $src_image;
    146 
     180  /** @var array */
    147181  private $params;
    148   private $rel_path, $rel_url, $is_cached=true;
    149 
    150   /*
    151   @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object
    152   @param src_image the source image of this derivative*/
     182  /** @var string */
     183  private $rel_path;
     184  /** @var string */
     185  private $rel_url;
     186  /** @var bool */
     187  private $is_cached=true;
     188
     189  /**
     190   * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*)
     191   *    or a DerivativeParams object
     192   * @param SrcImage $src_image the source image of this derivative
     193   */
    153194  function __construct($type, SrcImage $src_image)
    154195  {
    … …  
    166207  }
    167208
     209  /**
     210   * Generates the url of a thumbnail.
     211   *
     212   * @param array|SrcImage $infos array of info from db or SrcImage
     213   * @return string
     214   */
    168215  static function thumb_url($infos)
    169216  {
    … …  
    172219
    173220  /**
    174   @return derivative image url
    175   @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object
    176   @param infos assoc array of data from images table or a SrcImage object
    177   */
     221   * Generates the url for a particular photo size.
     222   *
     223   * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*)
     224   *    or a DerivativeParams object
     225   * @param array|SrcImage $infos array of info from db or SrcImage
     226   * @return string
     227   */
    178228  static function url($type, $infos)
    179229  {
    … …  
    194244  /**
    195245   * Return associative an array of all DerivativeImage for a specific image.
    196    * Disabled derivative types can be still found in the return mapped to an
     246   * Disabled derivative types can be still found in the return, mapped to an
    197247   * enabled derivative (e.g. the values are not unique in the return array).
    198248   * This is useful for any plugin/theme to just use $deriv[IMG_XLARGE] even if
    … …  
    229279   * Disabled derivatives fallback to an enabled derivative.
    230280   *
    231    * @param string $type
     281   * @param string $type standard derivative param type (e.g. IMG_*)
    232282   * @param array|SrcImage $src_image array of info from db or SrcImage
    233283   * @return DerivativeImage|null null if $type not found
    … …  
    255305  }
    256306
     307  /**
     308   * @todo : documentation of DerivativeImage::build
     309   */
    257310  private static function build($src, &$params, &$rel_path, &$rel_url, &$is_cached=null)
    258311  {
    … …  
    335388  }
    336389
     390  /**
     391   * @return string
     392   */
    337393  function get_path()
    338394  {
    … …  
    340396  }
    341397
     398  /**
     399   * @return string
     400   */
    342401  function get_url()
    343402  {
    … …  
    353412  }
    354413
     414  /**
     415   * @return bool
     416   */
    355417  function same_as_source()
    356418  {
    … …  
    358420  }
    359421
    360 
     422  /**
     423   * @return string one if IMG_* or 'Original'
     424   */
    361425  function get_type()
    362426  {
    … …  
    366430  }
    367431
    368   /* returns the size of the derivative image*/
     432  /**
     433   * @return int[]
     434   */
    369435  function get_size()
    370436  {
    … …  
    376442  }
    377443
     444  /**
     445   * Returns the size as CSS rule.
     446   *
     447   * @return string
     448   */
    378449  function get_size_css()
    379450  {
    … …  
    385456  }
    386457
     458  /**
     459   * Returns the size as HTML attributes.
     460   *
     461   * @return string
     462   */
    387463  function get_size_htm()
    388464  {
    … …  
    394470  }
    395471
     472  /**
     473   * Returns literal size: $widthx$height.
     474   *
     475   * @return string
     476   */
    396477  function get_size_hr()
    397478  {
    … …  
    403484  }
    404485
     486  /**
     487   * @param int $maxw
     488   * @param int $mawh
     489   * @return int[]
     490   */
    405491  function get_scaled_size($maxw, $maxh)
    406492  {
    … …  
    427513  }
    428514
     515  /**
     516   * Returns the scaled size as HTML attributes.
     517   *
     518   * @param int $maxw
     519   * @param int $mawh
     520   * @return string
     521   */
    429522  function get_scaled_size_htm($maxw=9999, $maxh=9999)
    430523  {
    … …  
    436529  }
    437530
     531  /**
     532   * @return bool
     533   */
    438534  function is_cached()
    439535  {

  • trunk/include/derivative_params.inc.php

    r20335 r25754  
    2020// +-----------------------------------------------------------------------+
    2121
     22/**
     23 * @package Derivatives
     24 */
     25
     26
     27/**
     28 * Formats a size name into a 2 chars identifier usable in filename.
     29 *
     30 * @param string $t one of IMG_*
     31 * @return string
     32 */
    2233function derivative_to_url($t)
    2334{
    … …  
    2536}
    2637
     38/**
     39 * Formats a size array into a identifier usable in filename.
     40 *
     41 * @param int[] $s
     42 * @return string
     43 */
    2744function size_to_url($s)
    2845{
    … …  
    3451}
    3552
     53/**
     54 * @param int[] $s1
     55 * @param int[] $s2
     56 * @return bool
     57 */
    3658function size_equals($s1, $s2)
    3759{
    … …  
    3961}
    4062
     63/**
     64 * Converts a char a-z into a float.
     65 *
     66 * @param string
     67 * @return float
     68 */
    4169function char_to_fraction($c)
    4270{
    … …  
    4472}
    4573
     74/**
     75 * Converts a float into a char a-z.
     76 *
     77 * @param float
     78 * @return string
     79 */
    4680function fraction_to_char($f)
    4781{
    … …  
    4983}
    5084
    51 /** small utility to manipulate a 'rectangle'*/
     85
     86/**
     87 * Small utility to manipulate a 'rectangle'.
     88 */
    5289final class ImageRect
    5390{
     91  /**
     92   * @var int $l
     93   * @var int $t
     94   * @var int $r
     95   * @var int $b
     96   */
    5497  public $l,$t,$r,$b;
    5598
     99  /**
     100   * @param int[] $l width and height
     101   */
    56102  function __construct($l)
    57103  {
    … …  
    61107  }
    62108
     109  /**
     110   * @return int
     111   */
    63112  function width()
    64113  {
    … …  
    66115  }
    67116
     117  /**
     118   * @return int
     119   */
    68120  function height()
    69121  {
    … …  
    71123  }
    72124
    73   /** crops horizontally this rectangle by increasing left side and/or reducing the right side.
    74   @param pixels the amount to substract from the width
    75   @param coi a 4 character string (or null) containing the center of interest*/
     125  /**
     126   * Crops horizontally this rectangle by increasing left side and/or reducing the right side.
     127   *
     128   * @param int $pixels - the amount to substract from the width
     129   * @param stirng $coi - a 4 character string (or null) containing the center of interest
     130   */
    76131  function crop_h($pixels, $coi)
    77132  {
    … …  
    102157  }
    103158
    104   /** crops vertically this rectangle by increasing top side and/or reducing the bottom side.
    105   @param pixels the amount to substract from the height
    106   @param coi a 4 character string (or null) containing the center of interest*/
     159  /**
     160   * Crops vertically this rectangle by increasing top side and/or reducing the bottom side.
     161   *
     162   * @param int $pixels - the amount to substract from the height
     163   * @param string $coi - a 4 character string (or null) containing the center of interest
     164   */
    107165  function crop_v($pixels, $coi)
    108166  {
    … …  
    132190    $this->b -= $pixels - $tlcrop;
    133191  }
    134 
    135 }
    136 
    137 
    138 /** Paramaters for derivative scaling and cropping. Instance of this class contained by DerivativeParams class.*/
     192}
     193
     194
     195/**
     196 * Paramaters for derivative scaling and cropping.
     197 * Instance of this class contained by DerivativeParams class.
     198 */
    139199final class SizingParams
    140200{
    141   /**
    142   @param ideal_size two element array of maximum output dimensions (width, height)
    143   @param max_crop range 0=no cropping ... 1= max cropping (100% of width/height); expressed as a factor of the input width/height
    144   @param min_size used only if max_crop != 0 - two element array of output dimensions (width, height)
    145   */
    146   function __construct($ideal_size, $max_crop = 0, $min_size = null)
     201  /** @var int[] */
     202  var $ideal_size;
     203  /** @var float */
     204  var $max_crop;
     205  /** @var int[] */
     206  var $min_size;
     207
     208  /**
     209   * @param int[] $ideal_size - two element array of maximum output dimensions (width, height)
     210   * @param float $max_crop - from 0=no cropping to 1= max cropping (100% of width/height);
     211   *    expressed as a factor of the input width/height
     212   * @param int[] $min_size - (used only if _$max_crop_ !=0) two element array of output dimensions (width, height)
     213   */
     214  function __construct($ideal_size, $max_crop=0, $min_size=null)
    147215  {
    148216    $this->ideal_size = $ideal_size;
    149     $this->max_crop = $max_crop; // range 0=no cropping ... 1= max cropping (100% of width/height)
     217    $this->max_crop = $max_crop;
    150218    $this->min_size = $min_size;
    151219  }
    152220
     221  /**
     222   * Returns a simple SizingParams object.
     223   *
     224   * @param int $w
     225   * @param int $h
     226   * @return SizingParams
     227   */
    153228  static function classic($w, $h)
    154229  {
    … …  
    156231  }
    157232
     233  /**
     234   * Returns a square SizingParams object.
     235   *
     236   * @param int $x
     237   * @return SizingParams
     238   */
    158239  static function square($w)
    159240  {
    … …  
    161242  }
    162243
     244  /**
     245   * Adds tokens depending on sizing configuration.
     246   *
     247   * @param array &$tokens
     248   */
    163249  function add_url_tokens(&$tokens)
    164250  {
    … …  
    179265  }
    180266
    181   /* calculate the cropping rectangle and the scaled size for an input image size
    182   @param in_size two element array of input dimensions (width, height)
    183   @param coi empty or a four character encoded string containing the center of interest (unused if max_crop=0)
    184   @param crop_rect output ImageRect containing the cropping rectangle or null if cropping is not required
    185   @param scale_size output two element array containing width and height of the scaled image
    186   */
     267  /**
     268   * Calculates the cropping rectangle and the scaled size for an input image size.
     269   *
     270   * @param int[] $in_size - two element array of input dimensions (width, height)
     271   * @param string $coi - four character encoded string containing the center of interest (unused if max_crop=0)
     272   * @param ImageRect &$crop_rect - ImageRect containing the cropping rectangle or null if cropping is not required
     273   * @param int[] &$scale_size - two element array containing width and height of the scaled image
     274   */
    187275  function compute($in_size, $coi, &$crop_rect, &$scale_size)
    188276  {
    … …  
    246334    }
    247335  }
    248 
    249 }
    250 
    251 
    252 /** All needed parameters to generate a derivative image.*/
     336}
     337
     338
     339/**
     340 * All needed parameters to generate a derivative image.
     341 */
    253342final class DerivativeParams
    254343{
    255   public $type = IMG_CUSTOM; // string IMG_xxx
    256   public $last_mod_time = 0; // used for non-custom images to regenerate the cached files
     344  /** @var SizingParams */
     345  public $sizing;
     346  /** @var string among IMG_* */
     347  public $type = IMG_CUSTOM;
     348  /** @var int used for non-custom images to regenerate the cached files */
     349  public $last_mod_time = 0;
     350  /** @var bool */
    257351  public $use_watermark = false;
    258   public $sizing; // of type SizingParams
    259   public $sharpen = 0; // range 0= no sharpening ... 1= max sharpening
    260 
     352  /** @var float from 0=no sharpening to 1=max sharpening */
     353  public $sharpen = 0;
     354
     355  /**
     356   * @param SizingParams $sizing
     357   */
    261358  function __construct($sizing)
    262359  {
    … …  
    264361  }
    265362
     363  /**
     364   * @return array
     365   */
    266366  public function __sleep()
    267367  {
    268       return array('last_mod_time', 'sizing', 'sharpen');
    269   }
    270 
     368    return array('last_mod_time', 'sizing', 'sharpen');
     369  }
     370
     371  /**
     372   * Adds tokens depending on sizing configuration.
     373   *
     374   * @param array &$tokens
     375   */
    271376  function add_url_tokens(&$tokens)
    272377  {
    … …  
    274379  }
    275380
     381  /**
     382   * @return int[]
     383   */
    276384  function compute_final_size($in_size)
    277385  {
    … …  
    280388  }
    281389
     390  /**
     391   * @return int
     392   */
    282393  function max_width()
    283394  {
    … …  
    285396  }
    286397
     398  /**
     399   * @return int
     400   */
    287401  function max_height()
    288402  {
    … …  
    290404  }
    291405
     406  /**
     407   * @todo : description of DerivativeParams::is_identity
     408   *
     409   * @return bool
     410   */
    292411  function is_identity($in_size)
    293412  {
    … …  
    300419  }
    301420
     421  /**
     422   * @return bool
     423   */
    302424  function will_watermark($out_size)
    303425  {
    … …  
    311433  }
    312434}
     435
    313436?>

  • trunk/include/derivative_std_params.inc.php

    r19703 r25754  
    2020// +-----------------------------------------------------------------------+
    2121
     22/**
     23 * @package Derivatives
     24 */
     25
     26
    2227define('IMG_SQUARE', 'square');
    2328define('IMG_THUMB', 'thumb');
    … …  
    3136define('IMG_CUSTOM', 'custom');
    3237
     38
     39/**
     40 * Container for watermark configuration.
     41 */
    3342final class WatermarkParams
    3443{
     44  /** @var string */
    3545  public $file = '';
     46  /** @var int[] */
    3647  public $min_size = array(500,500);
     48  /** @var int */
    3749  public $xpos = 50;
     50  /** @var int */
    3851  public $ypos = 50;
     52  /** @var int */
    3953  public $xrepeat = 0;
     54  /** @var int */
    4055  public $opacity = 100;
    4156}
    4257
    4358
     59/**
     60 * Container for standard derivatives parameters.
     61 */
    4462final class ImageStdParams
    4563{
     64  /** @var string[] */
    4665  private static $all_types = array(
    47     IMG_SQUARE,IMG_THUMB,IMG_XXSMALL,IMG_XSMALL,IMG_SMALL,IMG_MEDIUM,IMG_LARGE,IMG_XLARGE,IMG_XXLARGE
     66    IMG_SQUARE, IMG_THUMB, IMG_XXSMALL, IMG_XSMALL, IMG_SMALL,
     67    IMG_MEDIUM, IMG_LARGE, IMG_XLARGE, IMG_XXLARGE
    4868    );
     69  /** @var DerivativeParams[] */
    4970  private static $all_type_map = array();
     71  /** @var DerivativeParams[] */
    5072  private static $type_map = array();
     73  /** @var DerivativeParams[] */
    5174  private static $undefined_type_map = array();
     75  /** @var WatermarkParams */
    5276  private static $watermark;
     77  /** @var array */
    5378  public static $custom = array();
     79  /** @var int */
    5480  public static $quality=95;
    5581
     82  /**
     83   * @return string[]
     84   */
    5685  static function get_all_types()
    5786  {
    … …  
    5988  }
    6089
     90  /**
     91   * @return DerivativeParams[]
     92   */
    6193  static function get_all_type_map()
    6294  {
    … …  
    6496  }
    6597
     98  /**
     99   * @return DerivativeParams[]
     100   */
    66101  static function get_defined_type_map()
    67102  {
    … …  
    69104  }
    70105
     106  /**
     107   * @return DerivativeParams[]
     108   */
    71109  static function get_undefined_type_map()
    72110  {
    … …  
    74112  }
    75113
     114  /**
     115   * @return DerivativeParams
     116   */
    76117  static function get_by_type($type)
    77118  {
    … …  
    79120  }
    80121
     122  /**
     123   * @param int $w
     124   * @param int $h
     125   * @param float $crop
     126   * @param int $minw
     127   * @param int $minh
     128   * @return DerivativeParams
     129   */
    81130  static function get_custom($w, $h, $crop=0, $minw=null, $minh=null)
    82131  {
    … …  
    95144  }
    96145
     146  /**
     147   * @return WatermarkParams
     148   */
    97149  static function get_watermark()
    98150  {
    … …  
    100152  }
    101153
     154  /**
     155   * Loads derivative configuration from database or initializes it.
     156   */
    102157  static function load_from_db()
    103158  {
    … …  
    122177  }
    123178
     179  /**
     180   * @param WatermarkParams $watermark
     181   */
    124182  static function set_watermark($watermark)
    125183  {
    … …  
    127185  }
    128186
     187  /**
     188   * @see ImageStdParams::save()
     189   *
     190   * @param DerivativeParams[] $map
     191   */
    129192  static function set_and_save($map)
    130193  {
    … …  
    134197  }
    135198
     199  /**
     200   * Saves the configuration in database.
     201   */
    136202  static function save()
    137203  {
    … …  
    147213  }
    148214
     215  /**
     216   * @return DerivativeParams[]
     217   */
    149218  static function get_default_sizes()
    150219  {
    … …  
    160229      IMG_XXLARGE => new DerivativeParams( SizingParams::classic(1656,1242) ),
    161230    );
     231    $now = time();
    162232    foreach($arr as $params)
    163233    {
    164       $params->last_mod_time = time();
     234      $params->last_mod_time = $now;
    165235    }
    166236    return $arr;
    167237  }
    168238
     239  /**
     240   * Compute 'apply_watermark'
     241   *
     242   * @param DerivativeParams $params
     243   */
    169244  static function apply_global($params)
    170245  {
    … …  
    174249  }
    175250
     251  /**
     252   * Build 'type_map', 'all_type_map' and 'undefined_type_map'.
     253   */
    176254  private static function build_maps()
    177255  {
    … …  
    201279    }
    202280  }
    203 
    204281}
    205282
Note: See TracChangeset for help on using the changeset viewer.