fix CS
authorChristian Weiske <cweiske@cweiske.de>
Wed, 16 Apr 2014 16:25:00 +0000 (18:25 +0200)
committerChristian Weiske <cweiske@cweiske.de>
Wed, 16 Apr 2014 16:25:00 +0000 (18:25 +0200)
12 files changed:
data/phancap.config.php.dist
src/phancap/Adapter/Cutycapt.php
src/phancap/Authenticator.php
src/phancap/Config.php
src/phancap/Executor.php
src/phancap/Image.php
src/phancap/Options.php
src/phancap/Repository.php
src/phar-stub.php
www/get.php
www/index.php
www/setup.php

index 9a83e7b..884f059 100644 (file)
@@ -1,4 +1,10 @@
 <?php
+/**
+ * phancap configuration
+ *
+ * See README for a list of configuration options
+ */
+
 //username => secret key
 $access = array(
     'bar' => 'bar',
index 461fdaa..19657c8 100644 (file)
@@ -1,12 +1,46 @@
 <?php
+/**
+ * Part of phancap
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Adapter_Cutycapt
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
+ */
 namespace phancap;
 
+/**
+ * Screenshot rendering using the "cutycapt" command line tool.
+ *
+ * @category  Tools
+ * @package   Adapter_Cutycapt
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/phancap.htm
+ */
 class Adapter_Cutycapt
 {
+    /**
+     * Lock file handle
+     * @var resourece
+     */
     protected $lockHdl;
+
+    /**
+     * Lock file path
+     * @var string
+     */
     protected $lockFile = null;
 
     /**
+     * Check if all dependencies are available.
+     *
      * @return mixed TRUE if all is fine, array with error messages otherwise
      */
     public function isAvailable()
@@ -31,6 +65,15 @@ class Adapter_Cutycapt
         return true;
     }
 
+    /**
+     * Render a website screenshot
+     *
+     * @param Image   $img     Image configuration
+     * @param Options $options Screenshot configuration
+     *
+     * @return void
+     * @throws \Exception When something fails
+     */
     public function render(Image $img, Options $options)
     {
         $format = $options->values['sformat'];
@@ -59,6 +102,14 @@ class Adapter_Cutycapt
         $this->resize($tmpPath, $img, $options);
     }
 
+    /**
+     * Get a free X server number.
+     *
+     * Each xvfb-run process needs its own free server number.
+     * Needed for multiple parallel requests.
+     *
+     * @return integer Server number
+     */
     protected function getServerNumber()
     {
         //clean stale lock files
@@ -87,6 +138,11 @@ class Adapter_Cutycapt
         return $num;
     }
 
+    /**
+     * Unlock lock file and clean up old lock files
+     *
+     * @return void
+     */
     public function cleanup()
     {
         if ($this->lockFile !== null && $this->lockHdl) {
@@ -107,7 +163,18 @@ class Adapter_Cutycapt
         }
     }
 
-    protected function resize($tmpPath, $img, $options)
+    /**
+     * Convert an image to the given size.
+     *
+     * Target file is the path of $img.
+     *
+     * @param string  $tmpPath Path of image to be scaled.
+     * @param Image   $img     Image configuration
+     * @param Options $options Screenshot configuration
+     *
+     * @return void
+     */
+    protected function resize($tmpPath, Image $img, Options $options)
     {
         if ($options->values['sformat'] == 'pdf') {
             //nothing to resize.
@@ -132,6 +199,13 @@ class Adapter_Cutycapt
         unlink($tmpPath);
     }
 
+    /**
+     * Set phancap configuration
+     *
+     * @param Config $config Phancap configuration
+     *
+     * @return void
+     */
     public function setConfig(Config $config)
     {
         $this->config = $config;
index 73d4ae6..d0a9021 100644 (file)
@@ -1,8 +1,39 @@
 <?php
+/**
+ * Part of phancap
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Authenticator
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
+ */
 namespace phancap;
 
+/**
+ * Authentication helper methods
+ *
+ * @category  Tools
+ * @package   Authenticator
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/phancap.htm
+ */
 class Authenticator
 {
+    /**
+     * Validate the authentication signature.
+     *
+     * @param object $config Phancap configuration
+     *
+     * @return void
+     * @throws \Exception When a parameter is missing, or authentication fails
+     */
     public function authenticate(Config $config)
     {
         if ($config->access === false) {
@@ -45,7 +76,13 @@ class Authenticator
         }
     }
 
-
+    /**
+     * Convert a list of parameters into a string that can be hashed.
+     *
+     * @param array $params Parameters, key-value pairs
+     *
+     * @return string Line of encoded parameters
+     */
     protected function getSignatureData($params)
     {
         ksort($params);
index bb39da1..b519454 100644 (file)
@@ -1,6 +1,29 @@
 <?php
+/**
+ * Part of phancap
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Config
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
+ */
 namespace phancap;
 
+/**
+ * Phancap configuration
+ *
+ * @category  Tools
+ * @package   Config
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/phancap.htm
+ */
 class Config
 {
     /**
@@ -88,6 +111,9 @@ class Config
     public $screenshotMinAge = 'PT1H';
 
 
+    /**
+     * Initialize default values and loads configuration file paths
+     */
     public function __construct()
     {
         $this->cacheDir    = getcwd() . '/imgcache/';
@@ -100,6 +126,12 @@ class Config
         $this->loadConfigFilePaths();
     }
 
+    /**
+     * Load the first configuration file that exists
+     *
+     * @return void
+     * @uses   $cfgFileExists
+     */
     public function load()
     {
         $this->cfgFileExists = false;
@@ -134,6 +166,13 @@ class Config
         $this->cfgFiles[] = '/etc/phancap.php';
     }
 
+    /**
+     * Load values of a configuration file into this class
+     *
+     * @param string $filename Configuration file (.php)
+     *
+     * @return void
+     */
     protected function loadFile($filename)
     {
         include $filename;
@@ -143,16 +182,31 @@ class Config
         }
     }
 
+    /**
+     * Check if the cache directory exists and is writable
+     *
+     * @return void
+     * @throws \Exception When something is not ok
+     */
     public function setupCheck()
     {
         if (!is_dir($this->cacheDir)) {
-            throw new \Exception('Cache directory does not exist: ' . $this->cacheDir);
+            throw new \Exception(
+                'Cache directory does not exist: ' . $this->cacheDir
+            );
         }
         if (!is_writable($this->cacheDir)) {
-            throw new \Exception('Cache directory is not writable: ' . $this->cacheDir);
+            throw new \Exception(
+                'Cache directory is not writable: ' . $this->cacheDir
+            );
         }
     }
 
+    /**
+     * Returns the current URL, without fragmet.
+     *
+     * @return string Full URL
+     */
     protected function getCurrentUrl()
     {
         if (!isset($_SERVER['REQUEST_SCHEME'])) {
@@ -164,6 +218,8 @@ class Config
     }
 
     /**
+     * Returns the current URL without the file name in the path
+     *
      * @return string Directory of URL without trailing slash,
      *                and without .phar file
      */
index 12a34c3..5b59094 100644 (file)
@@ -1,8 +1,39 @@
 <?php
+/**
+ * Part of phancap
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Executor
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
+ */
 namespace phancap;
 
+/**
+ * Run a shell command
+ *
+ * @category  Tools
+ * @package   Executor
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/phancap.htm
+ */
 class Executor
 {
+    /**
+     * Run a shell command and check exit code.
+     *
+     * @param string $cmd Full command including parameters and options
+     *
+     * @return void
+     * @throws \Exception When the exit code is not 0
+     */
     public static function run($cmd)
     {
         exec($cmd . ' 2>&1', $arOutput, $exitcode);
@@ -13,5 +44,4 @@ class Executor
         }
     }
 }
-
 ?>
index 151847e..15263c2 100644 (file)
@@ -1,18 +1,61 @@
 <?php
+/**
+ * Part of phancap
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Image
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
+ */
 namespace phancap;
 
+/**
+ * Image meta data and methods to get info about the file
+ *
+ * @category  Tools
+ * @package   Image
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/phancap.htm
+ */
 class Image
 {
+
+    /**
+     * Description for protected
+     * @var object
+     */
     protected $config;
+
+    /**
+     * Description for public
+     * @var string
+     */
     public $name;
 
 
+    /**
+     * Set the file name
+     *
+     * @param string $name Image file name
+     */
     public function __construct($name)
     {
         $this->name = $name;
     }
 
     /**
+     * Get the expiration date for the image, depending on
+     * the maximum age the user requested.
+     *
+     * @param Options $options Image rendering options
+     *
      * @return integer Unix timestamp
      */
     public function getExpiryDate(Options $options)
@@ -22,6 +65,11 @@ class Image
         return $mtime + $options->values['smaxage'];
     }
 
+    /**
+     * Get the MIME type for the file
+     *
+     * @return string MIME type string ("image/png")
+     */
     public function getMimeType()
     {
         $ext = substr($this->name, -4);
@@ -29,22 +77,39 @@ class Image
             return 'image/jpeg';
         } else if ($ext == '.png') {
             return 'image/png';
-        } else  if ($ext == '.png') {
+        } else if ($ext == '.png') {
             return 'application/pdf';
         }
         return 'application/octet-stream';
     }
 
+    /**
+     * Get the full path to the cached image on disk
+     *
+     * @return string Full path to image
+     */
     public function getPath()
     {
         return $this->config->cacheDir . $this->name;
     }
 
+    /**
+     * Get the public URL for the image
+     *
+     * @return string Public image URL
+     */
     public function getUrl()
     {
         return $this->config->cacheDirUrl . $this->name;
     }
 
+    /**
+     * Set phancap configuration
+     *
+     * @param Config $config Phancap configuration
+     *
+     * @return void
+     */
     public function setConfig(Config $config)
     {
         $this->config = $config;
index c1a9b09..061230c 100644 (file)
@@ -1,8 +1,36 @@
 <?php
+/**
+ * Part of phancap
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Options
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
+ */
 namespace phancap;
 
+/**
+ * Options a user can give to the API
+ *
+ * @category  Tools
+ * @package   Options
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/phancap.htm
+ */
 class Options
 {
+    /**
+     * Available options and their configuration
+     *
+     * @var array
+     */
     public $options = array(
         /**
          * Browser settings
@@ -80,6 +108,11 @@ class Options
         ),
     );
 
+    /**
+     * Actual values we use after parsing the GET parameters
+     *
+     * @var array
+     */
     public $values = array();
 
     /**
@@ -93,6 +126,10 @@ class Options
      * $this->values.
      *
      * @param array $arValues Array of options, e.g. $_GET
+     *
+     * @return void
+     * @throws \InvalidArgumentException When required parameters are missing
+     *         or parameter values are invalid.
      */
     public function parse($arValues)
     {
@@ -140,6 +177,11 @@ class Options
         $this->calcPageSize();
     }
 
+    /**
+     * Calculate the browser size and screenshot size from the given options
+     *
+     * @return void
+     */
     protected function calcPageSize()
     {
         if ($this->values['swidth'] === null) {
@@ -166,6 +208,18 @@ class Options
         }
     }
 
+    /**
+     * Makes sure a value is between $min and $max (inclusive)
+     *
+     * @param integer $value  Value to check
+     * @param integer $min    Minimum allowed value
+     * @param integer $max    Maximum allowed value
+     * @param boolean $silent When silent, invalid values are corrected.
+     *                        An exception is thrown otherwise.
+     *
+     * @return integer Corrected value
+     * @throws \InvalidArgumentException When not silent and value outside range
+     */
     protected function clamp($value, $min, $max, $silent = false)
     {
         if ($min !== null && $value < $min) {
@@ -196,7 +250,6 @@ class Options
      * @param string $value Age in seconds
      *
      * @return integer Age in seconds
-     *
      * @throws \InvalidArgumentException
      * @link   http://en.wikipedia.org/wiki/Iso8601#Durations
      */
@@ -223,6 +276,15 @@ class Options
         return $value;
     }
 
+    /**
+     * Check that a given value exists in an array
+     *
+     * @param string $value   Value to check
+     * @param array  $options Array of allowed values
+     *
+     * @return string Value
+     * @throws \InvalidArgumentException If the value does not exist in $options
+     */
     protected function validateArray($value, $options)
     {
         if (array_search($value, $options) === false) {
@@ -234,6 +296,16 @@ class Options
         return $value;
     }
 
+    /**
+     * Validate that a value is numeric and between $min and $max (inclusive)
+     *
+     * @param string  $value Value to check
+     * @param integer $min   Minimum allowed value
+     * @param integer $max   Maximum allowed value
+     *
+     * @return integer Value as integer
+     * @throws \InvalidArgumentException When outside range or not numeric
+     */
     protected function validateInt($value, $min, $max)
     {
         if (!is_numeric($value)) {
@@ -245,6 +317,14 @@ class Options
         return $this->clamp($value, $min, $max);
     }
 
+    /**
+     * Validate (and fix) an URL
+     *
+     * @param string $url URL
+     *
+     * @return string Fixed URL
+     * @throws \InvalidArgumentException
+     */
     protected function validateUrl($url)
     {
         $parts = parse_url($url);
@@ -263,6 +343,13 @@ class Options
         return $url;
     }
 
+    /**
+     * Set phancap configuration
+     *
+     * @param Config $config Phancap configuration
+     *
+     * @return void
+     */
     public function setConfig(Config $config)
     {
         $this->config = $config;
index 7bdbe3a..9e7ad32 100644 (file)
@@ -1,13 +1,41 @@
 <?php
+/**
+ * Part of phancap
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Repository
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
+ */
 namespace phancap;
 
+/**
+ * Repository of existing screenshots
+ *
+ * @category  Tools
+ * @package   Repository
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/phancap.htm
+ */
 class Repository
 {
-    public function setConfig(Config $config)
-    {
-        $this->config = $config;
-    }
-
+    /**
+     * Return image object for the given rendering options.
+     * Loads it from cache if possible.
+     * If cache is expired or image does not yet exist,
+     * it will be rendered.
+     *
+     * @param Options $options Image rendering options
+     *
+     * @return Image Image object
+     */
     public function getImage(Options $options)
     {
         $name = $this->getFilename($options);
@@ -19,6 +47,13 @@ class Repository
         return $img;
     }
 
+    /**
+     * Get the cache image filename for the given rendering options
+     *
+     * @param Options $options Image rendering options
+     *
+     * @return string relative file name for the image
+     */
     public function getFilename(Options $options)
     {
         $optValues = $options->values;
@@ -35,6 +70,9 @@ class Repository
     /**
      * Check if the image is available locally.
      *
+     * @param Image   $img     Image object to render (contains name)
+     * @param Options $options Image rendering options
+     *
      * @return boolean True if we have it and it's within the cache lifetime,
      *                 false if the cache expired or the screenshot does not
      *                 exist.
@@ -53,6 +91,15 @@ class Repository
         return true;
     }
 
+    /**
+     * Render a website screenshot
+     *
+     * @param Image   $img     Image object to render (contains name)
+     * @param Options $options Image rendering options
+     *
+     * @return void
+     * @throws \Exception When something goes wrong
+     */
     protected function render(Image $img, Options $options)
     {
         $adapter = new Adapter_Cutycapt();
@@ -65,5 +112,17 @@ class Repository
             throw $e;
         }
     }
+
+    /**
+     * Set phancap configuration
+     *
+     * @param Config $config Phancap configuration
+     *
+     * @return void
+     */
+    public function setConfig(Config $config)
+    {
+        $this->config = $config;
+    }
 }
 ?>
index b5cdf4d..c8e168f 100644 (file)
@@ -39,7 +39,7 @@ function rewritePath($path)
             . '/';
         header('Location: ' . $url);
         exit(0);
-    } else if$path == '/') {
+    } else if ($path == '/') {
         return 'www/index.php';
     }
 
index 4cd2b3a..f78c3b5 100644 (file)
@@ -1,8 +1,18 @@
 <?php
-namespace phancap;
 /**
- * Get a screenshot for a website.
+ * Create a website screenshot API
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Phancap
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
  */
+namespace phancap;
+
 header('HTTP/1.0 500 Internal Server Error');
 
 if (file_exists(__DIR__ . '/../src/phancap/Autoloader.php')) {
index 947a1bf..ee69271 100644 (file)
@@ -1,8 +1,17 @@
 <?php
-namespace phancap;
 /**
- * Check if everything is setup
+ * Give information about phancap 
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Phancap
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
  */
+namespace phancap;
 header('HTTP/1.0 500 Internal Server Error');
 
 if (file_exists(__DIR__ . '/../src/phancap/Autoloader.php')) {
@@ -18,7 +27,8 @@ $config = new Config();
 try {
     $config->load();
     $options->setConfig($config);
-} catch (\Exception $e) {}
+} catch (\Exception $e) {
+}
 ?>
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
@@ -90,7 +100,9 @@ try {
      </p>
 
      <div class="panel panel-default">
-      <div class="panel-heading" style="text-align: center">Available URL parameters</div>
+      <div class="panel-heading" style="text-align: center">
+       Available URL parameters
+      </div>
       <table class="table table-striped table-bordered table-condensed">
        <thead>
         <tr>
index da93207..3107769 100644 (file)
@@ -1,8 +1,17 @@
 <?php
-namespace phancap;
 /**
- * Check if everything is setup
+ * Check if everything is setup correctly
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Phancap
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/phancap.htm
  */
+namespace phancap;
 header('HTTP/1.0 500 Internal Server Error');
 
 if (file_exists(__DIR__ . '/../src/phancap/Autoloader.php')) {
@@ -133,7 +142,8 @@ foreach ($messages as $key => $messages) {
     }
     foreach ($messages as $data) {
         list($state, $message) = $data;
-        $out .= '<li class="list-group-item list-group-item-' . $stateMap[$state] . '">';
+        $out .= '<li class="list-group-item list-group-item-'
+            . $stateMap[$state] . '">';
         $out .= htmlspecialchars($message);
         $out .= '</li>' . "\n";
     }