switch version to 1.5 and update CHANGELOG, README and UPDATE
[phpfspot.git] / phpfspot.class.php
index 3b4a62e9166abc2a420de0780bcd9b4fea7cb60f..bae4ae74dbc40ce34899bb4270397a3860000abf 100644 (file)
@@ -2,8 +2,9 @@
 
 /***************************************************************************
  *
- * Copyright (c) by Andreas Unterkircher, unki@netshadow.at
- * All rights reserved
+ * phpfspot, presents your F-Spot photo collection in Web browsers.
+ *
+ * Copyright (c) by Andreas Unterkircher
  *
  *  This program is free software; you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
 require_once "phpfspot_cfg.php";
 require_once "phpfspot_db.php";
 
+/**
+ * PHPFSPOT main class
+ *
+ * this class contains the most functions which will to the major
+ * work for phpfspot.
+ *
+ * @package phpfspot
+ */
 class PHPFSPOT {
 
+   /**
+     * phpfspot configuration
+     * @access public
+     * @see PHPFSPOT_CFG()
+     * @var PHPFSPOT_CFG
+     */
    var $cfg;
+
+   /**
+     * SQLite database handle to f-spot database
+     * @see PHPFSPOT_DB()
+     * @access public
+     * @var PHPFSPOT_DB
+     */
    var $db;
+
+   /**
+     * SQLite database handle to phpfspot database
+     * @see PHPFSPOT_DB()
+     * @access public
+     * @var PHPFSPOT_DB
+     */
    var $cfg_db;
+
+   /**
+    * Smarty template engine
+    * @link http://smarty.php.net smarty.php.net
+    * @see PHPFSPOT_TMPL()
+    * @access public
+    * @var PHPFSPOT_TMPL
+    */
    var $tmpl;
+
+   /**
+    * full tag - list
+    * @access public
+    * @var array
+    */
    var $tags;
+
+   /**
+    * list of available, not-selected, tags
+    * @access public
+    * @var array
+    */
    var $avail_tags;
 
+   /**
+    * true if runtime error occued
+    * @access private
+    * @var boolean
+    */
    private $runtime_error = false;
+
+   /**
+    * F-Spot database version
+    * @access private
+    * @var integer
+    */
    private $dbver;
 
    /**
-    * class constructor
+    * class constructor ($cfg, $db, $cfg_db, $tmpl, $db_ver)
     *
     * this function will be called on class construct
     * and will check requirements, loads configuration,
@@ -45,6 +105,14 @@ class PHPFSPOT {
     */
    public function __construct()
    {
+      /**
+       * register PHPFSPOT class global
+       *
+       * @global PHPFSPOT $GLOBALS['phpfspot']
+       * @name $phpfspot
+       */
+      $GLOBALS['phpfspot'] =& $this;
+
       $this->cfg = new PHPFSPOT_CFG;
 
       /* verify config settings */
@@ -54,7 +122,7 @@ class PHPFSPOT {
 
       /* set application name and version information */
       $this->cfg->product = "phpfspot";
-      $this->cfg->version = "1.4";
+      $this->cfg->version = "1.5";
 
       $this->sort_orders= array(
          'date_asc' => 'Date ↑',
@@ -131,7 +199,7 @@ class PHPFSPOT {
 
       /* overload Smarty class with our own template handler */
       require_once "phpfspot_tmpl.php";
-      $this->tmpl = new PHPFSPOT_TMPL($this);
+      $this->tmpl = new PHPFSPOT_TMPL();
 
       /* check if all necessary indices exist */
       $this->checkDbIndices();
@@ -321,6 +389,8 @@ class PHPFSPOT {
     * 
     * retrieve all available details from f-spot's
     * database and return them as object
+    * @param integer $idx
+    * @return object|null
     */
    public function get_photo_details($idx)
    {
@@ -377,6 +447,9 @@ class PHPFSPOT {
     * this function returns aligned (length) names for
     * an specific photo. If the length of the name exceeds
     * $limit the name will be shrinked (...)
+    * @param integer $idx
+    * @param integer $limit
+    * @return string|null
     */
    public function getPhotoName($idx, $limit = 0)
    {
@@ -397,6 +470,9 @@ class PHPFSPOT {
     * If the length of the name exceeds $limit the
     * text will be shortend and some content in between
     * will be replaced with "..." 
+    * @param string $ext
+    * @param integer $limit
+    * @return string
     */
    private function shrink_text($text, $limit)
    {
@@ -414,8 +490,10 @@ class PHPFSPOT {
     * as the full-qualified path recorded in the f-spot database
     * is usally not the same as on the webserver, this function
     * will replace the path with that one specified in the cfg
+    * @param string $path
+    * @return string
     */
-   public function translate_path($path, $width = 0)
+   public function translate_path($path)
    {  
       return str_replace($this->cfg->path_replace_from, $this->cfg->path_replace_to, $path);
 
@@ -426,6 +504,7 @@ class PHPFSPOT {
     *
     * this function provides all the necessary information
     * for the single photo template.
+    * @param integer photo
     */
    public function showPhoto($photo)
    {
@@ -483,8 +562,11 @@ class PHPFSPOT {
          $thumb_path = $this->get_thumb_path($this->cfg->photo_width, $photo);
       }
 
+      /* get mime-type, height and width from the original photo */
+      $info = getimagesize($orig_path);
+
       /* get EXIF information if JPEG */
-      if($details['mime'] == "image/jpeg") {
+      if($info['mime'] == "image/jpeg") {
          $meta = $this->get_meta_informations($orig_path);
       }
 
@@ -492,7 +574,6 @@ class PHPFSPOT {
       if(isset($meta['ExifImageWidth'])) {
          $meta_res = $meta['ExifImageWidth'] ."x". $meta['ExifImageLength'];
       } else {
-         $info = getimagesize($orig_path);
          $meta_res = $info[0] ."x". $info[1]; 
       }
 
@@ -516,13 +597,13 @@ class PHPFSPOT {
          return;
       }
 
-      $info = getimagesize($thumb_path);
+      $info_thumb = getimagesize($thumb_path);
 
       $this->tmpl->assign('description', $details['description']);
       $this->tmpl->assign('image_name', $this->parse_uri($details['uri'], 'filename'));
 
-      $this->tmpl->assign('width', $info[0]);
-      $this->tmpl->assign('height', $info[1]);
+      $this->tmpl->assign('width', $info_thumb[0]);
+      $this->tmpl->assign('height', $info_thumb[1]);
       $this->tmpl->assign('ExifMadeOn', $meta_date);
       $this->tmpl->assign('ExifMadeWith', $meta_make);
       $this->tmpl->assign('ExifOrigResolution', $meta_res);
@@ -643,6 +724,7 @@ class PHPFSPOT {
     * this function output all tags which have been selected
     * by the user. the selected tags are stored in the 
     * session-variable $_SESSION['selected_tags']
+    * @return string
     */
    public function getSelectedTags()
    {
@@ -675,6 +757,7 @@ class PHPFSPOT {
     * this function will add the specified to users current
     * tag selection. if a date search has been made before
     * it will be now cleared
+    * @return string
     */
    public function addTag($tag)
    {
@@ -684,10 +767,15 @@ class PHPFSPOT {
       if(isset($_SESSION['searchfor_tag']))
          unset($_SESSION['searchfor_tag']);
 
+      // has the user requested to hide this tag, and still someone,
+      // somehow tries to add it, don't allow this.
+      if(!isset($this->cfg->hide_tags) &&
+         in_array($this->get_tag_name($tag), $this->cfg->hide_tags))
+         return "ok";
+
       if(!in_array($tag, $_SESSION['selected_tags']))
          array_push($_SESSION['selected_tags'], $tag);
 
-
       return "ok";
    
    } // addTag()
@@ -697,6 +785,8 @@ class PHPFSPOT {
     *
     * this function removes the specified tag from
     * users current tag selection
+    * @param string $tag
+    * @return string
     */
    public function delTag($tag)
    {
@@ -728,6 +818,7 @@ class PHPFSPOT {
 
    /**
     * returns the value for the autocomplet tag-search
+    * @return string
     */
    public function get_xml_tag_list()
    {
@@ -836,6 +927,7 @@ class PHPFSPOT {
     * the tag-selection, tag- or date-search.
     * the tag-search also has to take care of AND
     * and OR conjunctions
+    * @return array
     */
    public function getPhotoSelection()
    {  
@@ -1250,12 +1342,16 @@ class PHPFSPOT {
    } // showCredits()
 
    /**
-    * create_thumbnails for the requested width
+    * create thumbnails for the requested width
     *
     * this function creates image thumbnails of $orig_image
     * stored as $thumb_image. It will check if the image is
     * in a supported format, if necessary rotate the image
     * (based on EXIF orientation meta headers) and re-sizing.
+    * @param string $orig_image
+    * @param string $thumb_image
+    * @param integer $width
+    * @return boolean
     */
    public function create_thumbnail($orig_image, $thumb_image, $width)
    {  
@@ -1263,13 +1359,13 @@ class PHPFSPOT {
          return false;
       }
 
-      $details = getimagesize($orig_image);
-      
+      $mime = $this->get_mime_info($orig_image);
+
       /* check if original photo is a support image type */
-      if(!$this->checkifImageSupported($details['mime']))
+      if(!$this->checkifImageSupported($mime))
          return false;
 
-      switch($details['mime']) {
+      switch($mime) {
 
          case 'image/jpeg':
 
@@ -1299,32 +1395,66 @@ class PHPFSPOT {
             }
 
             $src_img = @imagecreatefromjpeg($orig_image);
+            $handler = "gd";
             break;
 
          case 'image/png':
 
             $src_img = @imagecreatefrompng($orig_image);
+            $handler = "gd";
+            break;
+
+         case 'image/x-portable-pixmap':
+
+            $src_img = new Imagick($orig_image);
+            $handler = "imagick";
             break;
 
       }
 
-      if(!$src_img) {
+      if(!isset($src_img) || empty($src_img)) {
          print "Can't load image from ". $orig_image ."\n";
          return false;
       }
 
-      /* grabs the height and width */
-      $cur_width = imagesx($src_img);
-      $cur_height = imagesy($src_img);
+      switch($handler) {
+
+         case 'gd':
+
+            /* grabs the height and width */
+            $cur_width = imagesx($src_img);
+            $cur_height = imagesy($src_img);
+
+            // If requested width is more then the actual image width,
+            // do not generate a thumbnail, instead safe the original
+            // as thumbnail but with lower quality. But if the image
+            // is to heigh too, then we still have to resize it.
+            if($width >= $cur_width && $cur_height < $this->cfg->thumb_height) {
+               $result = imagejpeg($src_img, $thumb_image, 75);
+               imagedestroy($src_img);
+               return true;
+            }
+            break;
+
+         case 'imagick':
+
+            $cur_width = $src_img->getImageWidth();
+            $cur_height = $src_img->getImageHeight();
+
+            // If requested width is more then the actual image width,
+            // do not generate a thumbnail, instead safe the original
+            // as thumbnail but with lower quality. But if the image
+            // is to heigh too, then we still have to resize it.
+            if($width >= $cur_width && $cur_height < $this->cfg->thumb_height) {
+               $src_img->setCompressionQuality(75);
+               $src_img->setImageFormat('jpeg');
+               $src_img->writeImage($thumb_image);
+               $src_img->clear();
+               $src_img->destroy();
+               return true;
+            }
+            break;
 
-      // If requested width is more then the actual image width,
-      // do not generate a thumbnail, instead safe the original
-      // as thumbnail but with lower quality. But if the image
-      // is to heigh too, then we still have to resize it.
-      if($width >= $cur_width && $cur_height < $this->cfg->thumb_height) {
-         $result = imagejpeg($src_img, $thumb_image, 75);
-         imagedestroy($src_img);
-         return true;
       }
 
       // If the image will be rotate because EXIF orientation said so
@@ -1366,48 +1496,94 @@ class PHPFSPOT {
          }
       }
 
-      /* creates new image of that size */
-      $dst_img = imagecreatetruecolor($new_w, $new_h);
+      switch($handler) {
 
-      imagefill($dst_img, 0, 0, ImageColorAllocate($dst_img, 255, 255, 255));
+         case 'gd':
 
-      /* copies resized portion of original image into new image */
-      imagecopyresampled($dst_img, $src_img, 0, 0, 0, 0, $new_w, $new_h, imagesx($src_img), imagesy($src_img));
+            /* creates new image of that size */
+            $dst_img = imagecreatetruecolor($new_w, $new_h);
 
-      /* needs the image to be flipped horizontal? */
-      if($flip_hori) {
-         $this->_debug("(FLIP)");
-         $dst_img = $this->flipImage($dst_img, 'hori');
-      }
-      /* needs the image to be flipped vertical? */
-      if($flip_vert) {
-         $this->_debug("(FLIP)");
-         $dst_img = $this->flipImage($dst_img, 'vert');
-      }
+            imagefill($dst_img, 0, 0, ImageColorAllocate($dst_img, 255, 255, 255));
 
-      if($rotate) {
-         $this->_debug("(ROTATE)");
-         $dst_img = $this->rotateImage($dst_img, $rotate);
-      }
+            /* copies resized portion of original image into new image */
+            imagecopyresampled($dst_img, $src_img, 0, 0, 0, 0, $new_w, $new_h, imagesx($src_img), imagesy($src_img));
 
-      /* write down new generated file */
-      $result = imagejpeg($dst_img, $thumb_image, 75);
+            /* needs the image to be flipped horizontal? */
+            if($flip_hori) {
+               $this->_debug("(FLIP)");
+               $dst_img = $this->flipImage($dst_img, 'hori');
+            }
+            /* needs the image to be flipped vertical? */
+            if($flip_vert) {
+               $this->_debug("(FLIP)");
+               $dst_img = $this->flipImage($dst_img, 'vert');
+            }
 
-      /* free your mind */
-      imagedestroy($dst_img);
-      imagedestroy($src_img);
+            if($rotate) {
+               $this->_debug("(ROTATE)");
+               $dst_img = $this->rotateImage($dst_img, $rotate);
+            }
 
-      if($result === false) {
-         print "Can't write thumbnail ". $thumb_image ."\n";
-         return false;
-      }
+            /* write down new generated file */
+            $result = imagejpeg($dst_img, $thumb_image, 75);
 
-      return true;
+            /* free your mind */
+            imagedestroy($dst_img);
+            imagedestroy($src_img);
+
+            if($result === false) {
+               print "Can't write thumbnail ". $thumb_image ."\n";
+               return false;
+            }
+
+            return true;
+
+            break;
+
+         case 'imagick':
+
+            $src_img->resizeImage($new_w, $new_h, Imagick::FILTER_LANCZOS, 1);
+
+            /* needs the image to be flipped horizontal? */
+            if($flip_hori) {
+               $this->_debug("(FLIP)");
+               $src_img->rotateImage(new ImagickPixel(), 90);
+               $src_img->flipImage();
+               $src_img->rotateImage(new ImagickPixel(), -90);
+            }
+            /* needs the image to be flipped vertical? */
+            if($flip_vert) {
+               $this->_debug("(FLIP)");
+               $src_img->flipImage();
+            }
+
+            if($rotate) {
+               $this->_debug("(ROTATE)");
+               $src_img->rotateImage(new ImagickPixel(), $rotate);
+            }
+
+            $src_img->setCompressionQuality(75);
+            $src_img->setImageFormat('jpeg');
+
+            if(!$src_img->writeImage($thumb_image)) {
+               print "Can't write thumbnail ". $thumb_image ."\n";
+               return false;
+            }
+
+            $src_img->clear();
+            $src_img->destroy();
+            return true;
+
+            break;
+
+      }
 
    } // create_thumbnail()
 
    /**
     * return all exif meta data from the file
+    * @param string $file
+    * @return array
     */
    public function get_meta_informations($file)
    {
@@ -1446,6 +1622,9 @@ class PHPFSPOT {
     *    readable
     * 2. Check if the md5sum of the original file has changed
     * 3. Generate the thumbnails if needed
+    * @param integer $idx
+    * @param integer $force
+    * @param boolean $overwrite
     */
    public function gen_thumb($idx = 0, $force = 0, $overwrite = false)
    {
@@ -1473,10 +1652,27 @@ class PHPFSPOT {
          return;
       }
 
-      $file_md5 = md5_file($full_path);
-
       $this->_debug("Image [". $idx ."] ". $this->shrink_text($this->parse_uri($details['uri'], 'filename'), 20) ." Thumbnails:");
 
+      /* If Nikon NEF format, we need to treat it another way */
+      if(isset($this->cfg->dcraw_bin) &&
+         file_exists($this->cfg->dcraw_bin) &&
+         is_executable($this->cfg->dcraw_bin) &&
+         preg_match('/\.nef$/i', $details['uri'])) {
+
+         $ppm_path = preg_replace('/\.nef$/i', '.ppm', $full_path);
+
+         /* if PPM file does not exist, let dcraw convert it from NEF */
+         if(!file_exists($ppm_path)) {
+            system($this->cfg->dcraw_bin ." -a ". $full_path);
+         }
+
+         /* for now we handle the PPM instead of the NEF */
+         $full_path = $ppm_path;
+
+      }
+
+      $file_md5 = md5_file($full_path);
       $changes = false;
 
       foreach($resolutions as $resolution) {
@@ -1528,6 +1724,8 @@ class PHPFSPOT {
     *
     * this function queries the phpfspot database for a
     * stored MD5 checksum of the specified photo
+    * @param integer $idx
+    * @return string|null
     */
    public function getMD5($idx)
    {
@@ -1547,6 +1745,8 @@ class PHPFSPOT {
 
    /**
     * set MD5 sum for the specific photo
+    * @param integer $idx
+    * @param string $md5
     */
    private function setMD5($idx, $md5)
    {
@@ -1562,6 +1762,8 @@ class PHPFSPOT {
     *
     * this function stores the current tag condition
     * (AND or OR) in the users session variables
+    * @param string $mode
+    * @return string
     */
    public function setTagCondition($mode)
    {
@@ -1579,6 +1781,7 @@ class PHPFSPOT {
     * it also handles the date search.
     * getPhotoSelection() will then only return the matching
     * photos.
+    * @return string
     */
    public function startSearch()
    {
@@ -1629,6 +1832,8 @@ class PHPFSPOT {
     *
     * this function is invoked by RPC and will sort the requested
     * sort order in the session variable.
+    * @param string $sort_order
+    * @return string
     */
    public function updateSortOrder($order)
    {
@@ -1646,6 +1851,9 @@ class PHPFSPOT {
     *
     * this function rotates the image according the
     * specified angel.
+    * @param string $img
+    * @param integer $degress
+    * @return image
     */
    private function rotateImage($img, $degrees)
    {
@@ -1723,6 +1931,9 @@ class PHPFSPOT {
     *
     * this function will return an either horizontal or
     * vertical flipped truecolor image.
+    * @param string $image
+    * @param string $mode 
+    * @return image
     */
    private function flipImage($image, $mode)
    {
@@ -1749,6 +1960,8 @@ class PHPFSPOT {
 
    /**
     * return all assigned tags for the specified photo
+    * @param integer $idx
+    * @return array
     */
    private function get_photo_tags($idx)
    {
@@ -1762,8 +1975,11 @@ class PHPFSPOT {
 
       $tags = Array();
 
-      while($row = $this->db->db_fetch_object($result))
+      while($row = $this->db->db_fetch_object($result)) {
+         if(isset($this->cfg->hide_tags) && in_array($row['name'], $this->cfg->hide_tags))
+            continue;
          $tags[$row['id']] = $row['name'];
+      }
 
       return $tags;
 
@@ -1771,6 +1987,11 @@ class PHPFSPOT {
 
    /**
     * create on-the-fly images with text within
+    * @param string $txt
+    * @param string $color
+    * @param integer $space
+    * @param integer $font
+    * @param integer $w
     */
    public function showTextImage($txt, $color=000000, $space=4, $font=4, $w=300)
    {
@@ -1800,6 +2021,7 @@ class PHPFSPOT {
 
    /**
     * check if all requirements are met
+    * @return boolean
     */
    private function check_requirements()
    {
@@ -1854,16 +2076,29 @@ class PHPFSPOT {
 
    /**
     * check if specified MIME type is supported
+    * @param string $mime
+    * @return boolean
     */
    public function checkifImageSupported($mime)
    {
-      if(in_array($mime, Array("image/jpeg", "image/png")))
+      $supported_types =  Array(
+         "image/jpeg",
+         "image/png",
+         "image/x-portable-pixmap",
+         "image/tiff"
+      );
+
+      if(in_array($mime, $supported_types))
          return true;
 
       return false;
 
    } // checkifImageSupported()
 
+   /**
+    * output error text
+    * @param string $text
+    */
    public function _error($text)
    {
       switch($this->cfg->logging) {
@@ -1886,6 +2121,8 @@ class PHPFSPOT {
 
    /**
     * output calendard input fields
+    * @param string $mode
+    * @return string
     */
    private function get_calendar($mode)
    {
@@ -1912,6 +2149,9 @@ class PHPFSPOT {
 
    /**
     * output calendar matrix
+    * @param integer $year
+    * @param integer $month
+    * @param integer $day
     */
    public function get_calendar_matrix($year = 0, $month = 0, $day = 0)
    {
@@ -1990,6 +2230,7 @@ class PHPFSPOT {
 
    /**
     * output export page
+    * @param string $mode
     */
    public function getExport($mode)
    {
@@ -2105,6 +2346,7 @@ class PHPFSPOT {
  
    /**
     * return all selected tags as one string
+    * @return array
     */
    private function getCurrentTags()
    {
@@ -2136,6 +2378,7 @@ class PHPFSPOT {
     * to do next. This is necessary for directly jumping
     * into photo index or single photo view when the are
     * requested with specific URLs
+    * @return string
     */
    public function whatToDo()
    {
@@ -2155,6 +2398,7 @@ class PHPFSPOT {
 
    /**
     * return the current process-user
+    * @return string
     */
    private function getuid()
    {
@@ -2170,6 +2414,9 @@ class PHPFSPOT {
 
    /**
     * returns a select-dropdown box to select photo index sort parameters
+    * @param array $params
+    * @param smarty $smarty
+    * @return string
     */
    public function smarty_sort_select_list($params, &$smarty)
    {
@@ -2189,6 +2436,7 @@ class PHPFSPOT {
 
    /**
     * returns the currently selected sort order
+    * @return string
     */ 
    private function get_sort_order()
    {
@@ -2225,12 +2473,13 @@ class PHPFSPOT {
 
    } // get_sort_order()
 
-   /***
-     * return the next to be shown slide show image
-     *
-     * this function returns the URL of the next image
-     * in the slideshow sequence.
-     */
+   /**
+    * return the next to be shown slide show image
+    *
+    * this function returns the URL of the next image
+    * in the slideshow sequence.
+    * @return string
+    */
    public function getNextSlideShowImage()
    {
       $all_photos = $this->getPhotoSelection();
@@ -2244,12 +2493,13 @@ class PHPFSPOT {
 
    } // getNextSlideShowImage()
 
-   /***
-     * return the previous to be shown slide show image
-     *
-     * this function returns the URL of the previous image
-     * in the slideshow sequence.
-     */
+   /**
+    * return the previous to be shown slide show image
+    *
+    * this function returns the URL of the previous image
+    * in the slideshow sequence.
+    * @return string
+    */
    public function getPrevSlideShowImage()
    {
       $all_photos = $this->getPhotoSelection();
@@ -2270,25 +2520,41 @@ class PHPFSPOT {
 
    } // resetSlideShow()
    
-   /***
-     * get random photo
-     *
-     * this function will get all photos from the fspot
-     * database and randomly return ONE entry
-     *
-     * saddly there is yet no sqlite3 function which returns
-     * the bulk result in array, so we have to fill up our
-     * own here.
-     */ 
+   /**
+    * get random photo
+    *
+    * this function will get all photos from the fspot
+    * database and randomly return ONE entry
+    *
+    * saddly there is yet no sqlite3 function which returns
+    * the bulk result in array, so we have to fill up our
+    * own here.
+    * @return array
+    */
    public function get_random_photo()
    {
       $all = Array();
 
-      $result = $this->db->db_query("
-         SELECT id
-         FROM photos
-      ");
-      
+      $query_str = "
+         SELECT p.id
+         FROM photos p
+      ";
+
+      /* if show_tags is set, only return details for photos which
+         are specified to be shown
+      */
+      if(isset($this->cfg->show_tags) && !empty($this->cfg->show_tags)) {
+         $query_str.= "
+            INNER JOIN photo_tags pt
+               ON p.id=pt.photo_id
+            INNER JOIN tags t
+               ON pt.tag_id=t.id
+            WHERE
+               t.name IN ('".implode("','",$this->cfg->show_tags)."')";
+      }
+
+      $result = $this->db->db_query($query_str);
+
       while($row = $this->db->db_fetch_object($result)) {
          array_push($all, $row['id']);
       }
@@ -2303,6 +2569,8 @@ class PHPFSPOT {
     * this function validates if the provided date
     * contains a valid date and will return true 
     * if it is.
+    * @param string $date_str
+    * @return boolean
     */
    public function isValidDate($date_str)
    {
@@ -2317,15 +2585,22 @@ class PHPFSPOT {
 
    /**
     * timestamp to string conversion
+    * @param integer $timestamp
+    * @return string
     */
    private function ts2str($timestamp)
    {
       return strftime("%Y-%m-%d", $timestamp);
    } // ts2str()
 
+   /**
+    * extract tag-names from $_GET['tags']
+    * @param string $tags_str
+    * @return string
+    */
    private function extractTags($tags_str)
    {
-      $not_validated = split(',', $_GET['tags']);
+      $not_validated = split(',', $tags_str);
       $validated = array();
 
       foreach($not_validated as $tag) {
@@ -2339,6 +2614,9 @@ class PHPFSPOT {
 
    /**
     * returns the full path to a thumbnail
+    * @param integer $width
+    * @param integer $photo
+    * @return string
     */
    public function get_thumb_path($width, $photo)
    {
@@ -2356,6 +2634,7 @@ class PHPFSPOT {
 
    /**
     * returns server's virtual host name
+    * @return string
     */
    private function get_server_name()
    {
@@ -2363,8 +2642,8 @@ class PHPFSPOT {
    } // get_server_name()
 
    /**
-    * returns type of webprotocol which is
-    * currently used
+    * returns type of webprotocol which is currently used
+    * @return string
     */
    private function get_web_protocol()
    {
@@ -2376,6 +2655,7 @@ class PHPFSPOT {
 
    /**
     * return url to this phpfspot installation
+    * @return string
     */
    private function get_phpfspot_url()
    {
@@ -2384,6 +2664,8 @@ class PHPFSPOT {
 
    /**
     * returns the number of photos which are tagged with $tag_id
+    * @param integer $tag_id
+    * @return integer
     */
    public function get_num_photos($tag_id)
    {
@@ -2407,6 +2689,9 @@ class PHPFSPOT {
     * returns true, if everything is ok, otherwise false
     * if $silent is not set, this function will output and
     * error message
+    * @param string $file
+    * @param boolean $silent
+    * @return boolean
     */
    private function check_readable($file, $silent = null)
    {
@@ -2451,6 +2736,7 @@ class PHPFSPOT {
     *
     * this function will return the F-Spot database version number
     * It is stored within the sqlite3 database in the table meta
+    * @return string|null
     */
    public function getFspotDBVersion()
    {
@@ -2467,8 +2753,10 @@ class PHPFSPOT {
    } // getFspotDBVersion()
 
    /**
-    * parse the provided URI and will returned the
-    * requested chunk
+    * parse the provided URI and will returned the requested chunk
+    * @param string $uri
+    * @param string $mode
+    * @return string
     */
    public function parse_uri($uri, $mode)
    {
@@ -2496,6 +2784,7 @@ class PHPFSPOT {
     *
     * this function checks if all necessary configuration options are
     * specified and set.
+    * @return boolean
     */
    private function check_config_options()
    {
@@ -2615,6 +2904,9 @@ class PHPFSPOT {
     * current page, in which the $current photo lies. this is
     * used to display the correct photo, when calling showPhotoIndex()
     * from showImage()
+    * @param integer $current
+    * @param integer $max
+    * @return integer
     */
    private function getCurrentPage($current, $max)
    {
@@ -2628,6 +2920,57 @@ class PHPFSPOT {
 
    } // getCurrentPage()
 
+   /**
+    * return mime info
+    *
+    * this function tries to find out the correct mime-type
+    * for the provided file.
+    * @param string $file
+    * @return string
+    */
+   public function get_mime_info($file)
+   {
+      $details = getimagesize($orig_image);
+
+      /* if getimagesize() returns empty, try at least to find out the
+         mime type.
+      */
+      if(empty($details) && function_exists('mime_content_type')) {
+
+         // mime_content_type is marked as deprecated in the documentation,
+         // but is it really necessary to force users to install a PECL
+         // extension?
+         $details['mime'] = mime_content_type($file);
+      }
+
+      return $details['mime'];
+
+   } // get_mime_info()
+
+   /**
+    * return tag-name by tag-idx
+    *
+    * this function returns the tag-name for the requested
+    * tag specified by tag-idx.
+    * @param integer $idx
+    * @return string
+    */
+   public function get_tag_name($idx)
+   {
+       if($result = $this->db->db_fetchSingleRow("
+         SELECT name
+         FROM tags
+         WHERE
+            id LIKE '". $idx ."'")) {
+
+         return $result['name'];
+
+      }
+
+      return 0;
+      
+   } // get_tag_name()
+
 } // class PHPFSPOT
 
 ?>