Changeset 25754


Ignore:
Timestamp:
11/29/13 14:48:55 (6 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.