From 12fc66e66288365731ad40bf2016633d0569bf81 Mon Sep 17 00:00:00 2001 From: Christian Weiske Date: Wed, 16 Apr 2014 18:25:00 +0200 Subject: [PATCH] fix CS --- data/phancap.config.php.dist | 6 +++ src/phancap/Adapter/Cutycapt.php | 76 ++++++++++++++++++++++++++- src/phancap/Authenticator.php | 39 +++++++++++++- src/phancap/Config.php | 60 ++++++++++++++++++++- src/phancap/Executor.php | 32 +++++++++++- src/phancap/Image.php | 67 +++++++++++++++++++++++- src/phancap/Options.php | 89 +++++++++++++++++++++++++++++++- src/phancap/Repository.php | 69 +++++++++++++++++++++++-- src/phar-stub.php | 2 +- www/get.php | 14 ++++- www/index.php | 20 +++++-- www/setup.php | 16 ++++-- 12 files changed, 468 insertions(+), 22 deletions(-) diff --git a/data/phancap.config.php.dist b/data/phancap.config.php.dist index 9a83e7b..884f059 100644 --- a/data/phancap.config.php.dist +++ b/data/phancap.config.php.dist @@ -1,4 +1,10 @@ secret key $access = array( 'bar' => 'bar', diff --git a/src/phancap/Adapter/Cutycapt.php b/src/phancap/Adapter/Cutycapt.php index 461fdaa..19657c8 100644 --- a/src/phancap/Adapter/Cutycapt.php +++ b/src/phancap/Adapter/Cutycapt.php @@ -1,12 +1,46 @@ + * @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 + * @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; diff --git a/src/phancap/Authenticator.php b/src/phancap/Authenticator.php index 73d4ae6..d0a9021 100644 --- a/src/phancap/Authenticator.php +++ b/src/phancap/Authenticator.php @@ -1,8 +1,39 @@ + * @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 + * @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); diff --git a/src/phancap/Config.php b/src/phancap/Config.php index bb39da1..b519454 100644 --- a/src/phancap/Config.php +++ b/src/phancap/Config.php @@ -1,6 +1,29 @@ + * @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 + * @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 */ diff --git a/src/phancap/Executor.php b/src/phancap/Executor.php index 12a34c3..5b59094 100644 --- a/src/phancap/Executor.php +++ b/src/phancap/Executor.php @@ -1,8 +1,39 @@ + * @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 + * @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 } } } - ?> diff --git a/src/phancap/Image.php b/src/phancap/Image.php index 151847e..15263c2 100644 --- a/src/phancap/Image.php +++ b/src/phancap/Image.php @@ -1,18 +1,61 @@ + * @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 + * @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; diff --git a/src/phancap/Options.php b/src/phancap/Options.php index c1a9b09..061230c 100644 --- a/src/phancap/Options.php +++ b/src/phancap/Options.php @@ -1,8 +1,36 @@ + * @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 + * @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; diff --git a/src/phancap/Repository.php b/src/phancap/Repository.php index 7bdbe3a..9e7ad32 100644 --- a/src/phancap/Repository.php +++ b/src/phancap/Repository.php @@ -1,13 +1,41 @@ + * @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 + * @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; + } } ?> diff --git a/src/phar-stub.php b/src/phar-stub.php index b5cdf4d..c8e168f 100644 --- a/src/phar-stub.php +++ b/src/phar-stub.php @@ -39,7 +39,7 @@ function rewritePath($path) . '/'; header('Location: ' . $url); exit(0); - } else if( $path == '/') { + } else if ($path == '/') { return 'www/index.php'; } diff --git a/www/get.php b/www/get.php index 4cd2b3a..f78c3b5 100644 --- a/www/get.php +++ b/www/get.php @@ -1,8 +1,18 @@ + * @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')) { diff --git a/www/index.php b/www/index.php index 947a1bf..ee69271 100644 --- a/www/index.php +++ b/www/index.php @@ -1,8 +1,17 @@ + * @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) { +} ?> @@ -90,7 +100,9 @@ try {

-
Available URL parameters
+
+ Available URL parameters +
diff --git a/www/setup.php b/www/setup.php index da93207..3107769 100644 --- a/www/setup.php +++ b/www/setup.php @@ -1,8 +1,17 @@ + * @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 .= '
  • '; + $out .= '
  • '; $out .= htmlspecialchars($message); $out .= '
    • ' . "\n"; } -- 2.30.2