From 4f51e942be966504c523d431afe86e3fa73c3c10 Mon Sep 17 00:00:00 2001 From: jgen Date: Sun, 27 Apr 2014 15:33:57 -0400 Subject: [PATCH] Updating/Fixing/Adding more comments with the PHP Doc style. --- core/block.class.php | 12 +++-- core/event.class.php | 62 +++++++++++++++++----- core/extension.class.php | 52 ++++++++++++++++++- core/imageboard.pack.php | 100 +++++++++++++++++++++++++----------- core/page.class.php | 93 +++++++++++++++++++++------------ core/user.class.php | 21 +++++--- core/userclass.class.php | 14 +++++ ext/bbcode/main.php | 25 ++++++++- ext/comment/main.php | 24 +++++++++ ext/ext_manager/main.php | 9 +++- ext/favorites/main.php | 23 ++++++++- ext/handle_archive/main.php | 5 +- ext/handle_flash/main.php | 18 +++++++ ext/handle_ico/main.php | 18 ++++++- ext/handle_pixel/main.php | 46 ++++++++++++++++- ext/handle_svg/main.php | 24 +++++++-- ext/handle_video/main.php | 25 +++++++++ ext/image/main.php | 77 ++++++++++++++++++++------- ext/numeric_score/main.php | 5 ++ ext/pools/main.php | 18 ++++--- ext/upload/main.php | 33 +++++++----- 21 files changed, 569 insertions(+), 135 deletions(-) diff --git a/core/block.class.php b/core/block.class.php index bdbc215f..11a61aad 100644 --- a/core/block.class.php +++ b/core/block.class.php @@ -4,14 +4,14 @@ */ class Block { /** - * The block's title + * The block's title. * * @var string */ public $header; /** - * The content + * The content for the block. * * @var string */ @@ -19,7 +19,7 @@ class Block { /** * Where the block should be placed. The default theme supports - * "main" and "left", other themes can add their own areas + * "main" and "left", other themes can add their own areas. * * @var string */ @@ -35,7 +35,9 @@ class Block { public $position; /** - * @var int + * A unique ID for the block. + * + * @var string */ public $id; @@ -46,7 +48,7 @@ class Block { * @param string $body * @param string $section * @param int $position - * @param null|int $id + * @param null|int $id A unique ID for the block (generated automatically if null). */ public function __construct($header, $body, /*string*/ $section="main", /*int*/ $position=50, $id=null) { $this->header = $header; diff --git a/core/event.class.php b/core/event.class.php index 2b824e5b..c749178e 100644 --- a/core/event.class.php +++ b/core/event.class.php @@ -26,8 +26,19 @@ class InitExtEvent extends Event {} * $event->get_arg(0) = "42" */ class PageRequestEvent extends Event { + /** + * @var array + */ public $args; + + /** + * @var int + */ public $arg_count; + + /** + * @var int + */ public $part_count; /** @@ -90,7 +101,7 @@ class PageRequestEvent extends Event { * Get the n th argument of the page request (if it exists.) * * @param int $n - * @return string|null The argmuent (string) or NULL + * @return string|null The argument (string) or NULL */ public function get_arg(/*int*/ $n) { $offset = $this->part_count + $n; @@ -154,9 +165,19 @@ class PageRequestEvent extends Event { * Sent when index.php is called from the command line */ class CommandEvent extends Event { + /** + * @var string + */ public $cmd = "help"; + + /** + * @var array + */ public $args = array(); + /** + * @param string[] $args + */ public function __construct(/*array(string)*/ $args) { global $user; @@ -215,19 +236,28 @@ class CommandEvent extends Event { class TextFormattingEvent extends Event { /** * For reference + * + * @var string */ - var $original; + public $original; /** * with formatting applied + * + * @var string */ - var $formatted; + public $formatted; /** * with formatting removed + * + * @var string */ - var $stripped; + public $stripped; + /** + * @param string $text + */ public function __construct(/*string*/ $text) { $h_text = html_escape(trim($text)); $this->original = $h_text; @@ -244,36 +274,42 @@ class LogEvent extends Event { /** * a category, normally the extension name * - * @return string + * @var string */ - var $section; + public $section; /** * See python... * - * @return int + * @var int */ - var $priority = 0; + public $priority = 0; /** * Free text to be logged * - * @return text + * @var string */ - var $message; + public $message; /** * The time that the event was created * - * @return int + * @var int */ - var $time; + public $time; /** * Extra data to be held separate */ - var $args; + public $args; + /** + * @param string $section + * @param int $priority + * @param string $message + * @param $args + */ public function __construct($section, $priority, $message, $args) { $this->section = $section; $this->priority = $priority; diff --git a/core/extension.class.php b/core/extension.class.php index 1a0d50c5..5b2e36fc 100644 --- a/core/extension.class.php +++ b/core/extension.class.php @@ -96,7 +96,11 @@ abstract class Extension { } /** - * Find the theme object for a given extension + * Find the theme object for a given extension. + * + * @param Extension $class + * @param bool $fatal + * @return bool */ private function get_theme_object(Extension $class, $fatal=true) { $base = get_class($class); @@ -114,7 +118,9 @@ abstract class Extension { /** * Override this to change the priority of the extension, - * lower numbered ones will recieve events first + * lower numbered ones will recieve events first. + * + * @return int */ public function get_priority() { return 50; @@ -125,12 +131,24 @@ abstract class Extension { * Several extensions have this in common, make a common API */ abstract class FormatterExtension extends Extension { + /** + * @param TextFormattingEvent $event + */ public function onTextFormatting(TextFormattingEvent $event) { $event->formatted = $this->format($event->formatted); $event->stripped = $this->strip($event->stripped); } + /** + * @param string $text + * @return string + */ abstract public function format(/*string*/ $text); + + /** + * @param string $text + * @return string + */ abstract public function strip(/*string*/ $text); } @@ -139,6 +157,10 @@ abstract class FormatterExtension extends Extension { * so we have a base class to extend from */ abstract class DataHandlerExtension extends Extension { + /** + * @param DataUploadEvent $event + * @throws UploadException + */ public function onDataUpload(DataUploadEvent $event) { $supported_ext = $this->supported_ext($event->type); $check_contents = $this->check_contents($event->tmpname); @@ -202,6 +224,9 @@ abstract class DataHandlerExtension extends Extension { } } + /** + * @param ThumbnailGenerationEvent $event + */ public function onThumbnailGeneration(ThumbnailGenerationEvent $event) { if($this->supported_ext($event->type)) { if (method_exists($this, 'create_thumb_force') && $event->force == true) { @@ -213,6 +238,9 @@ abstract class DataHandlerExtension extends Extension { } } + /** + * @param DisplayingImageEvent $event + */ public function onDisplayingImage(DisplayingImageEvent $event) { global $page; if($this->supported_ext($event->image->ext)) { @@ -229,9 +257,29 @@ abstract class DataHandlerExtension extends Extension { protected function setup() {} */ + /** + * @param string $ext + * @return bool + */ abstract protected function supported_ext($ext); + + /** + * @param $tmpname + * @return bool + */ abstract protected function check_contents($tmpname); + + /** + * @param string $filename + * @param array $metadata + * @return Image|null + */ abstract protected function create_image_from_data($filename, $metadata); + + /** + * @param string $hash + * @return bool + */ abstract protected function create_thumb($hash); } diff --git a/core/imageboard.pack.php b/core/imageboard.pack.php index 8c8e27b0..1755e2a9 100644 --- a/core/imageboard.pack.php +++ b/core/imageboard.pack.php @@ -31,15 +31,33 @@ $order_sql = null; // this feels ugly require_once "lib/flexihash.php"; /** - * An object representing an entry in the images table. As of 2.2, this no - * longer necessarily represents an image per se, but could be a video, - * sound file, or any other supported upload type. + * An object representing an entry in the images table. + * + * As of 2.2, this no longer necessarily represents an + * image per se, but could be a video, sound file, or any + * other supported upload type. */ class Image { + /** @var null|int */ public $id = null; - public $height, $width; - public $hash, $filesize; - public $filename, $ext; + + /** @var int */ + public $height; + + /** @var int */ + public $width; + + /** @var string */ + public $hash; + + public $filesize; + + /** @var string */ + public $filename; + + /** @var string */ + public $ext; + public $owner_id, $owner_ip; public $posted, $posted_timestamp; public $source; @@ -47,7 +65,8 @@ class Image { /** * One will very rarely construct an image directly, more common - * would be to use Image::by_id, Image::by_hash, etc + * would be to use Image::by_id, Image::by_hash, etc. + * @param mixed $row */ public function __construct($row=null) { if(!is_null($row)) { @@ -66,7 +85,7 @@ class Image { } /** - * Find an image by ID + * Find an image by ID. * * @param int $id * @return Image @@ -79,7 +98,7 @@ class Image { } /** - * Find an image by hash + * Find an image by hash. * * @param string $hash * @return Image @@ -92,9 +111,9 @@ class Image { } /** - * Pick a random image out of a set + * Pick a random image out of a set. * - * @param array $tags + * @param string[] $tags * @return Image */ public static function by_random($tags=array()) { @@ -112,7 +131,7 @@ class Image { * * @param int $start * @param int $limit - * @param array $tags + * @param string[] $tags * @throws SCoreException * @return Array */ @@ -153,7 +172,7 @@ class Image { /** * Count the number of image results for a given search * - * @param array $tags + * @param string[] $tags * @return mixed */ public static function count_images($tags=array()) { @@ -185,7 +204,7 @@ class Image { /** * Count the number of pages for a given search * - * @param array $tags + * @param string[] $tags * @return float */ public static function count_pages($tags=array()) { @@ -205,7 +224,7 @@ class Image { * Rather than simply $this_id + 1, one must take into account * deleted images and search queries * - * @param array $tags + * @param string[] $tags * @param bool $next * @return Image */ @@ -239,7 +258,7 @@ class Image { /** * The reverse of get_next * - * @param array $tags + * @param string[] $tags * @return Image */ public function get_prev($tags=array()) { @@ -269,7 +288,9 @@ class Image { } /** - * Get this image's tags as an array + * Get this image's tags as an array. + * + * @return string[] */ public function get_tag_array() { global $database; @@ -349,7 +370,7 @@ class Image { /** * Get the tooltip for this image, formatted according to the - * configured template + * configured template. * * @return string */ @@ -378,7 +399,7 @@ class Image { } /** - * Figure out where the full size image is on disk + * Figure out where the full size image is on disk. * * @return string */ @@ -387,7 +408,7 @@ class Image { } /** - * Figure out where the thumbnail is on disk + * Figure out where the thumbnail is on disk. * * @return string */ @@ -396,7 +417,7 @@ class Image { } /** - * Get the original filename + * Get the original filename. * * @return string */ @@ -405,7 +426,7 @@ class Image { } /** - * Get the image's mime type + * Get the image's mime type. * * @return string */ @@ -480,7 +501,9 @@ class Image { } /** - * Set the tags for this image + * Set the tags for this image. + * + * @param string[] $tags */ public function set_tags($tags) { global $database; @@ -564,7 +587,7 @@ class Image { /** * Someone please explain this * - * @param $tmpl + * @param string $tmpl * @param string $_escape * @return string */ @@ -637,6 +660,10 @@ class Image { return $tmpl; } + /** + * @param string[] $terms + * @return \Querylet + */ private static function build_search_querylet($terms) { assert(is_array($terms)); global $database; @@ -666,6 +693,9 @@ class Image { * C) Runs really slow on bad databases: * All the subqueries are executed every time for every row in the * images table. Yes, MySQL does suck this much. + * + * @param string[] $terms + * @return \Querylet */ private static function build_accurate_search_querylet($terms) { global $database; @@ -1003,7 +1033,11 @@ class Tag { } /** - * Turn any string or array into a valid tag array + * Turn any string or array into a valid tag array. + * + * @param string|string[] $tags + * @param bool $tagme + * @return array */ public static function explode($tags, $tagme=true) { assert(is_string($tags) || is_array($tags)); @@ -1033,7 +1067,7 @@ class Tag { } /** - * @param $tags + * @param string|string[] $tags * @return string */ public static function implode($tags) { @@ -1073,6 +1107,10 @@ class Tag { return $negative ? "-$newtag" : $newtag; } + /** + * @param string $tag + * @return array + */ public static function resolve_wildcard($tag) { // if there is no wildcard, return the tag if(strpos($tag, "*") === false) { @@ -1102,8 +1140,8 @@ class Tag { /** * This function takes a list (array) of tags and changes any tags that have aliases * - * @param array $tags Array of tags - * @return array of tags + * @param string[] $tags Array of tags + * @return array */ public static function resolve_aliases($tags) { assert(is_array($tags)); @@ -1139,7 +1177,11 @@ class Tag { /** * Move a file from PHP's temporary area into shimmie's image storage - * hierarchy, or throw an exception trying + * hierarchy, or throw an exception trying. + * + * @param DataUploadEvent $event + * @return bool + * @throws UploadException */ function move_upload_to_archive(DataUploadEvent $event) { $target = warehouse_path("images", $event->hash); diff --git a/core/page.class.php b/core/page.class.php index db588e94..c05f9028 100644 --- a/core/page.class.php +++ b/core/page.class.php @@ -36,20 +36,22 @@ class Page { /** @name Overall */ //@{ - /** @private */ - var $mode = "page"; - /** @private */ - var $type = "text/html; charset=utf-8"; + /** @var string */ + public $mode = "page"; + /** @var string */ + public $type = "text/html; charset=utf-8"; /** * Set what this page should do; "page", "data", or "redirect". + * @param string $mode */ public function set_mode($mode) { $this->mode = $mode; } /** - * Set the page's MIME type + * Set the page's MIME type. + * @param string $type */ public function set_type($type) { $this->type = $type; @@ -61,20 +63,23 @@ class Page { /** @name "data" mode */ //@{ - /** @private */ - var $data = ""; - /** @private */ - var $filename = null; + /** @var string */ + private $data = ""; + + /** @var string */ + private $filename = null; /** - * Set the raw data to be sent + * Set the raw data to be sent. + * @param string $data */ public function set_data($data) { $this->data = $data; } /** - * Set the recommended download filename + * Set the recommended download filename. + * @param string $filename */ public function set_filename($filename) { $this->filename = $filename; @@ -86,12 +91,13 @@ class Page { /** @name "redirect" mode */ //@{ - /** @private */ - var $redirect = ""; + /** @var string */ + private $redirect = ""; /** * Set the URL to redirect to (remember to use make_link() if linking - * to a page in the same site) + * to a page in the same site). + * @param string $redirect */ public function set_redirect($redirect) { $this->redirect = $redirect; @@ -103,55 +109,75 @@ class Page { /** @name "page" mode */ //@{ - /** @privatesection */ - var $title = ""; - var $heading = ""; - var $subheading = ""; - var $quicknav = ""; - var $html_headers = array(); - var $http_headers = array(); - var $blocks = array(); - /** @publicsection */ + /** @var string */ + public $title = ""; + + /** @var string */ + public $heading = ""; + + /** @var string */ + public $subheading = ""; + + /** @var string */ + public $quicknav = ""; + + /** @var string[] */ + public $html_headers = array(); + + /** @var string[] */ + public $http_headers = array(); + + /** @var Block[] */ + public $blocks = array(); + /** - * Set the window title + * Set the window title. + * @param string $title */ public function set_title($title) { $this->title = $title; } /** - * Set the main heading + * Set the main heading. + * @param string $heading */ public function set_heading($heading) { $this->heading = $heading; } /** - * Set the sub heading + * Set the sub heading. + * @param string $subheading */ public function set_subheading($subheading) { $this->subheading = $subheading; } /** - * Add a line to the HTML head section + * Add a line to the HTML head section. + * @param string $line + * @param int $position */ public function add_html_header($line, $position=50) { while(isset($this->html_headers[$position])) $position++; $this->html_headers[$position] = $line; } - + /** * Add a http header to be sent to the client. + * @param string $line + * @param int $position */ public function add_http_header($line, $position=50) { while(isset($this->http_headers[$position])) $position++; $this->http_headers[$position] = $line; } - + /** * Get all the HTML headers that are currently set and return as a string. + * @return string */ public function get_all_html_headers() { $data = ''; @@ -162,14 +188,15 @@ class Page { } /** - * Removes all currently set HTML headers. (Be careful..) + * Removes all currently set HTML headers (Be careful..). */ public function delete_all_html_headers() { $this->html_headers = array(); } - + /** - * Add a Block of data + * Add a Block of data to the page. + * @param Block $block */ public function add_block(Block $block) { $this->blocks[] = $block; @@ -180,7 +207,7 @@ class Page { // ============================================== /** - * Display the page according to the mode and data given + * Display the page according to the mode and data given. */ public function display() { global $page, $user; diff --git a/core/user.class.php b/core/user.class.php index 94e22c63..16b1ebd9 100644 --- a/core/user.class.php +++ b/core/user.class.php @@ -22,10 +22,11 @@ class User { public $join_date; + /** @var string */ public $passhash; /** @var UserClass */ - var $class; + public $class; /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Initialisation * @@ -38,7 +39,9 @@ class User { /** * One will very rarely construct a user directly, more common - * would be to use User::by_id, User::by_session, etc + * would be to use User::by_id, User::by_session, etc. + * + * @param mixed $row */ public function __construct($row) { global $_user_classes; @@ -145,7 +148,7 @@ class User { /** - * Test if this user is anonymous (not logged in) + * Test if this user is anonymous (not logged in). * * @return bool */ @@ -155,7 +158,7 @@ class User { } /** - * Test if this user is logged in + * Test if this user is logged in. * * @return bool */ @@ -165,7 +168,7 @@ class User { } /** - * Test if this user is an administrator + * Test if this user is an administrator. * * @return bool */ @@ -193,6 +196,9 @@ class User { log_info("core-user", 'Set password for '.$this->name); } + /** + * @param string $address + */ public function set_email(/*string*/ $address) { global $database; $database->Execute("UPDATE users SET email=:email WHERE id=:id", array("email"=>$address, "id"=>$this->id)); @@ -201,7 +207,8 @@ class User { /** * Get a snippet of HTML which will render the user's avatar, be that - * a local file, a remote file, a gravatar, a something else, etc + * a local file, a remote file, a gravatar, a something else, etc. + * * @return String of HTML */ public function get_avatar_html() { @@ -231,7 +238,7 @@ class User { * the form was generated within the session. Salted and re-hashed so that * reading a web page from the user's cache doesn't give access to the session key * - * @return String containing auth token (MD5sum) + * @return string A string containing auth token (MD5sum) */ public function get_auth_token() { global $config; diff --git a/core/userclass.class.php b/core/userclass.class.php index ee6871ea..abc9d081 100644 --- a/core/userclass.class.php +++ b/core/userclass.class.php @@ -1,9 +1,23 @@ extract_code($text); foreach(array( @@ -62,6 +66,10 @@ class BBCode extends FormatterExtension { return $text; } + /** + * @param string $text + * @return string + */ public function strip(/*string*/ $text) { foreach(array( "b", "i", "u", "s", "sup", "sub", "h1", "h2", "h3", "h4", @@ -81,7 +89,10 @@ class BBCode extends FormatterExtension { return $text; } - + /** + * @param string $text + * @return mixed + */ private function filter_spoiler(/*string*/ $text) { return str_replace( array("[spoiler]","[/spoiler]"), @@ -89,6 +100,10 @@ class BBCode extends FormatterExtension { $text); } + /** + * @param string $text + * @return string + */ private function strip_spoiler(/*string*/ $text) { $l1 = strlen("[spoiler]"); $l2 = strlen("[/spoiler]"); @@ -110,6 +125,10 @@ class BBCode extends FormatterExtension { return $text; } + /** + * @param string $text + * @return string + */ private function extract_code(/*string*/ $text) { # at the end of this function, the only code! blocks should be # the ones we've added -- others may contain malicious content, @@ -137,6 +156,10 @@ class BBCode extends FormatterExtension { return $text; } + /** + * @param string $text + * @return string + */ private function insert_code(/*string*/ $text) { $l1 = strlen("[code!]"); $l2 = strlen("[/code!]"); diff --git a/ext/comment/main.php b/ext/comment/main.php index f64247e2..a3639c0f 100644 --- a/ext/comment/main.php +++ b/ext/comment/main.php @@ -425,6 +425,9 @@ class CommentList extends Extension { return (count($result) >= $max); } + /** + * @return bool + */ private function hash_match() { return ($_POST['hash'] == $this->get_hash()); } @@ -440,6 +443,10 @@ class CommentList extends Extension { return md5($_SERVER['REMOTE_ADDR'] . date("%Y%m%d")); } + /** + * @param string $text + * @return bool + */ private function is_spam_akismet(/*string*/ $text) { global $config, $user; if(strlen($config->get_string('comment_wordpress_key')) > 0) { @@ -478,11 +485,22 @@ class CommentList extends Extension { return false; } + /** + * @param int $image_id + * @param int $comment + * @return null + */ private function is_dupe(/*int*/ $image_id, /*string*/ $comment) { global $database; return ($database->get_row("SELECT * FROM comments WHERE image_id=:image_id AND comment=:comment", array("image_id"=>$image_id, "comment"=>$comment))); } // do some checks + + /** + * @param int $pagenum + * @param int $maxpage + * @return int + */ private function sanity_check_pagenumber(/*int*/ $pagenum, /*int*/ $maxpage){ if (!is_numeric($pagenum)){ $pagenum=1; @@ -496,6 +514,12 @@ class CommentList extends Extension { return $pagenum; } + /** + * @param int $image_id + * @param User $user + * @param string $comment + * @throws CommentPostingException + */ private function add_comment_wrapper(/*int*/ $image_id, User $user, /*string*/ $comment) { global $database, $config; diff --git a/ext/ext_manager/main.php b/ext/ext_manager/main.php index 1dc41624..0c9f81d4 100644 --- a/ext/ext_manager/main.php +++ b/ext/ext_manager/main.php @@ -81,6 +81,10 @@ class ExtensionInfo { } } + /** + * @param string $fname + * @return bool|null + */ private function is_enabled(/*string*/ $fname) { $core = explode(",", CORE_EXTS); $extra = explode(",", EXTRA_EXTS); @@ -150,7 +154,10 @@ class ExtManager extends Extension { } } - + /** + * @param bool $all + * @return array + */ private function get_extensions(/*bool*/ $all) { $extensions = array(); if($all) { diff --git a/ext/favorites/main.php b/ext/favorites/main.php index e90aa009..bdfa7f2e 100644 --- a/ext/favorites/main.php +++ b/ext/favorites/main.php @@ -14,8 +14,18 @@ */ class FavoriteSetEvent extends Event { - var $image_id, $user, $do_set; + /** @var int */ + public $image_id; + /** @var \User */ + public $user; + /** @var bool */ + public $do_set; + /** + * @param int $image_id + * @param User $user + * @param bool $do_set + */ public function __construct(/*int*/ $image_id, User $user, /*boolean*/ $do_set) { assert(is_numeric($image_id)); assert(is_bool($do_set)); @@ -172,6 +182,11 @@ class Favorites extends Extension { } } + /** + * @param int $image_id + * @param int $user_id + * @param bool $do_set + */ private function add_vote(/*int*/ $image_id, /*int*/ $user_id, /*bool*/ $do_set) { global $database; if ($do_set) { @@ -187,7 +202,11 @@ class Favorites extends Extension { "UPDATE images SET favorites=(SELECT COUNT(*) FROM user_favorites WHERE image_id=:image_id) WHERE id=:user_id", array("image_id"=>$image_id, "user_id"=>$user_id)); } - + + /** + * @param Image $image + * @return array + */ private function list_persons_who_have_favorited(Image $image) { global $database; diff --git a/ext/handle_archive/main.php b/ext/handle_archive/main.php index 3f61ad60..fb423d79 100644 --- a/ext/handle_archive/main.php +++ b/ext/handle_archive/main.php @@ -39,7 +39,10 @@ class ArchiveFileHandler extends Extension { } } - + /** + * @param $ext + * @return bool + */ private function supported_ext($ext) { $exts = array("zip"); return in_array(strtolower($ext), $exts); diff --git a/ext/handle_flash/main.php b/ext/handle_flash/main.php index f84153ad..58d93a3f 100644 --- a/ext/handle_flash/main.php +++ b/ext/handle_flash/main.php @@ -7,15 +7,29 @@ */ class FlashFileHandler extends DataHandlerExtension { + /** + * @param string $hash + * @return bool + */ protected function create_thumb($hash) { copy("ext/handle_flash/thumb.jpg", warehouse_path("thumbs", $hash)); + return true; } + /** + * @param string $ext + * @return bool + */ protected function supported_ext($ext) { $exts = array("swf"); return in_array(strtolower($ext), $exts); } + /** + * @param string $filename + * @param array $metadata + * @return Image|null + */ protected function create_image_from_data(/*string*/ $filename, /*array*/ $metadata) { $image = new Image(); @@ -35,6 +49,10 @@ class FlashFileHandler extends DataHandlerExtension { return $image; } + /** + * @param $file + * @return bool + */ protected function check_contents(/*string*/ $file) { if (!file_exists($file)) return false; diff --git a/ext/handle_ico/main.php b/ext/handle_ico/main.php index dae069c8..185bd7f3 100644 --- a/ext/handle_ico/main.php +++ b/ext/handle_ico/main.php @@ -49,12 +49,20 @@ class IcoFileHandler extends Extension { } } - + /** + * @param $ext + * @return bool + */ private function supported_ext($ext) { $exts = array("ico", "ani", "cur"); return in_array(strtolower($ext), $exts); } + /** + * @param $filename + * @param $metadata + * @return Image + */ private function create_image_from_data($filename, $metadata) { $image = new Image(); @@ -77,6 +85,10 @@ class IcoFileHandler extends Extension { return $image; } + /** + * @param $file + * @return bool + */ private function check_contents($file) { if(!file_exists($file)) return false; $fp = fopen($file, "r"); @@ -85,6 +97,10 @@ class IcoFileHandler extends Extension { return ($header['null'] == 0 && ($header['type'] == 0 || $header['type'] == 1)); } + /** + * @param $hash + * @return bool + */ private function create_thumb($hash) { global $config; diff --git a/ext/handle_pixel/main.php b/ext/handle_pixel/main.php index bf345352..77b72be7 100644 --- a/ext/handle_pixel/main.php +++ b/ext/handle_pixel/main.php @@ -7,12 +7,21 @@ */ class PixelFileHandler extends DataHandlerExtension { + /** + * @param string $ext + * @return bool + */ protected function supported_ext($ext) { $exts = array("jpg", "jpeg", "gif", "png"); $ext = (($pos = strpos($ext,'?')) !== false) ? substr($ext,0,$pos) : $ext; return in_array(strtolower($ext), $exts); } + /** + * @param string $filename + * @param array $metadata + * @return Image|null + */ protected function create_image_from_data(/*string*/ $filename, /*array*/ $metadata) { $image = new Image(); @@ -32,6 +41,10 @@ class PixelFileHandler extends DataHandlerExtension { return $image; } + /** + * @param string $file + * @return bool + */ protected function check_contents(/*string*/ $file) { $valid = Array(IMAGETYPE_PNG, IMAGETYPE_GIF, IMAGETYPE_JPEG); if(!file_exists($file)) return false; @@ -41,6 +54,10 @@ class PixelFileHandler extends DataHandlerExtension { return false; } + /** + * @param string $hash + * @return bool + */ protected function create_thumb(/*string*/ $hash) { $outname = warehouse_path("thumbs", $hash); if(file_exists($outname)) { @@ -49,6 +66,10 @@ class PixelFileHandler extends DataHandlerExtension { return $this->create_thumb_force($hash); } + /** + * @param $hash + * @return bool + */ protected function create_thumb_force(/*string*/ $hash) { global $config; @@ -69,7 +90,10 @@ class PixelFileHandler extends DataHandlerExtension { return $ok; } - + + /** + * @param ImageAdminBlockBuildingEvent $event + */ public function onImageAdminBlockBuilding(ImageAdminBlockBuildingEvent $event) { $event->add_part("
@@ -91,6 +115,12 @@ class PixelFileHandler extends DataHandlerExtension { } // IM thumber {{{ + + /** + * @param string $inname + * @param string $outname + * @return bool + */ private function make_thumb_convert(/*string*/ $inname, /*string*/ $outname) { global $config; @@ -124,6 +154,11 @@ class PixelFileHandler extends DataHandlerExtension { } // }}} // epeg thumber {{{ + /** + * @param string $inname + * @param string $outname + * @return bool + */ private function make_thumb_epeg(/*string*/ $inname, /*string*/ $outname) { global $config; $w = $config->get_int("thumb_width"); @@ -132,6 +167,11 @@ class PixelFileHandler extends DataHandlerExtension { } // }}} // GD thumber {{{ + /** + * @param string $inname + * @param string $outname + * @return bool + */ private function make_thumb_gd(/*string*/ $inname, /*string*/ $outname) { global $config; $thumb = $this->get_thumb($inname); @@ -140,6 +180,10 @@ class PixelFileHandler extends DataHandlerExtension { return $ok; } + /** + * @param string $tmpname + * @return resource + */ private function get_thumb(/*string*/ $tmpname) { global $config; diff --git a/ext/handle_svg/main.php b/ext/handle_svg/main.php index d27bb6f0..b6f562be 100644 --- a/ext/handle_svg/main.php +++ b/ext/handle_svg/main.php @@ -51,11 +51,20 @@ class SVGFileHandler extends Extension { } } + /** + * @param $ext + * @return bool + */ private function supported_ext($ext) { $exts = array("svg"); return in_array(strtolower($ext), $exts); } + /** + * @param $filename + * @param $metadata + * @return Image + */ private function create_image_from_data($filename, $metadata) { global $config; @@ -75,21 +84,30 @@ class SVGFileHandler extends Extension { return $image; } + /** + * @param $file + * @return bool + */ private function check_contents($file) { if(!file_exists($file)) return false; $msp = new MiniSVGParser($file); - return $msp->valid; + return bool_escape($msp->valid); } } class MiniSVGParser { - var $valid=false, $width=0, $height=0; + /** @var bool */ + public $valid=false; + /** @var int */ + public $width=0; + /** @var int */ + public $height=0; function __construct($file) { $xml_parser = xml_parser_create(); xml_set_element_handler($xml_parser, array($this, "startElement"), array($this, "endElement")); - $this->valid = xml_parse($xml_parser, file_get_contents($file), true); + $this->valid = bool_escape(xml_parse($xml_parser, file_get_contents($file), true)); xml_parser_free($xml_parser); } diff --git a/ext/handle_video/main.php b/ext/handle_video/main.php index cdd132d9..0a39336e 100644 --- a/ext/handle_video/main.php +++ b/ext/handle_video/main.php @@ -42,18 +42,25 @@ class VideoFileHandler extends DataHandlerExtension { $event->panel->add_block($sb); } + /** + * @param string $hash + * @return bool + */ protected function create_thumb($hash) { global $config; // this is never used... //$q = $config->get_int("thumb_quality"); + $ok = false; + switch($config->get_string("video_thumb_engine")) { default: case 'static': $outname = warehouse_path("thumbs", $hash); copy("ext/handle_video/thumb.jpg", $outname); + $ok = true; break; case 'ffmpeg': $ffmpeg = escapeshellarg($config->get_string("thumb_ffmpeg_path")); @@ -66,16 +73,30 @@ class VideoFileHandler extends DataHandlerExtension { $cmd = escapeshellcmd("{$ffmpeg} -i {$inname} -s {$w}x{$h} -ss 00:00:00.0 -f image2 -vframes 1 {$outname}"); exec($cmd, $output, $ret); + // TODO: We should really check the result of the exec to see if it really succeeded. + $ok = true; + log_debug('handle_video', "Generating thumbnail with command `$cmd`, returns $ret"); break; } + + return $ok; } + /** + * @param string $ext + * @return bool + */ protected function supported_ext($ext) { $exts = array("flv", "mp4", "m4v", "ogv", "webm"); return in_array(strtolower($ext), $exts); } + /** + * @param string $filename + * @param array $metadata + * @return Image|null + */ protected function create_image_from_data($filename, $metadata) { //global $config; @@ -117,6 +138,10 @@ class VideoFileHandler extends DataHandlerExtension { return $image; } + /** + * @param $file + * @return bool + */ protected function check_contents($file) { if (file_exists($file)) { require_once('lib/getid3/getid3/getid3.php'); diff --git a/ext/image/main.php b/ext/image/main.php index d9a2edbb..3bb24c6b 100644 --- a/ext/image/main.php +++ b/ext/image/main.php @@ -12,15 +12,17 @@ * An image is being added to the database. */ class ImageAdditionEvent extends Event { - var $user, $image; + var $user; + /** @var \Image */ + public $image; /** * Inserts a new image into the database with its associated * information. Also calls TagSetEvent to set the tags for * this new image. * - * @sa TagSetEvent - * @param $image Image The new image to add. + * @see TagSetEvent + * @param Image $image The new image to add. */ public function __construct(Image $image) { $this->image = $image; @@ -39,14 +41,16 @@ class ImageAdditionException extends SCoreException { * An image is being deleted. */ class ImageDeletionEvent extends Event { - var $image; + /** @var \Image */ + public $image; /** * Deletes an image. + * * Used by things like tags and comments handlers to * clean out related rows in their tables. * - * @param $image Image The image being deleted + * @param Image $image The image being deleted. */ public function __construct(Image $image) { $this->image = $image; @@ -57,18 +61,20 @@ class ImageDeletionEvent extends Event { * An image is being replaced. */ class ImageReplaceEvent extends Event { - var $id, $image; + /** @var int */ + public $id; + /** @var \Image */ + public $image; /** * Replaces an image. + * * Updates an existing ID in the database to use a new image * file, leaving the tags and such unchanged. Also removes * the old image file and thumbnail from the disk. * - * @param $id - * The ID of the image to replace - * @param $image - * The image object of the new image to use + * @param int $id The ID of the image to replace. + * @param Image $image The image object of the new image to use. */ public function __construct(/*int*/ $id, Image $image) { $this->id = $id; @@ -77,8 +83,12 @@ class ImageReplaceEvent extends Event { } class ImageReplaceException extends SCoreException { - var $error; + /** @var string */ + public $error; + /** + * @param string $error + */ public function __construct(/*string*/ $error) { $this->error = $error; } @@ -88,14 +98,19 @@ class ImageReplaceException extends SCoreException { * Request a thumbnail be made for an image object. */ class ThumbnailGenerationEvent extends Event { - var $hash, $type, $force; + /** @var string */ + public $hash; + /** @var string */ + public $type; + /** @var bool */ + public $force; /** * Request a thumbnail be made for an image object * - * @param $hash string The unique hash of the image - * @param $type string The type of the image - * @param $force boolean Regenerate the thumbnail even if one already exists + * @param string $hash The unique hash of the image + * @param string $type The type of the image + * @param bool $force Regenerate the thumbnail even if one already exists */ public function __construct($hash, $type, $force=false) { $this->hash = $hash; @@ -112,14 +127,27 @@ class ThumbnailGenerationEvent extends Event { * $image -- the image who's link is being parsed */ class ParseLinkTemplateEvent extends Event { - var $link, $original, $image; + /** @var string */ + public $link; + /** @var string */ + public $original; + /** @var \Image */ + public $image; + /** + * @param string $link The formatted link + * @param Image $image The image who's link is being parsed + */ public function __construct($link, Image $image) { $this->link = $link; $this->original = $link; $this->image = $image; } + /** + * @param string $needle + * @param string $replace + */ public function replace($needle, $replace) { $this->link = str_replace($needle, $replace, $this->link); } @@ -189,8 +217,7 @@ class ImageIO extends Extension { } public function onImageAdminBlockBuilding(ImageAdminBlockBuildingEvent $event) { - global $user; - global $config; + global $user, $config; if($user->can("delete_image")) { $event->add_part($this->theme->get_deleter_html($event->image->id)); @@ -277,6 +304,11 @@ class ImageIO extends Extension { // add image {{{ + /** + * @param Image $image + * @return null + * @throws ImageAdditionException + */ private function add_image(Image $image) { global $page, $user, $database, $config; @@ -346,6 +378,10 @@ class ImageIO extends Extension { // }}} end add // fetch image {{{ + /** + * @param int $image_id + * @param string $type + */ private function send_file($image_id, $type) { global $config; global $database; @@ -398,6 +434,11 @@ class ImageIO extends Extension { // }}} end fetch // replace image {{{ + /** + * @param int $id + * @param Image $image + * @throws ImageReplaceException + */ private function replace_image($id, $image) { global $database; diff --git a/ext/numeric_score/main.php b/ext/numeric_score/main.php index e2754f5a..4cd93fa0 100644 --- a/ext/numeric_score/main.php +++ b/ext/numeric_score/main.php @@ -284,6 +284,11 @@ class NumericScore extends Extension { } } + /** + * @param int $image_id + * @param int $user_id + * @param int $score + */ private function add_vote(/*int*/ $image_id, /*int*/ $user_id, /*int*/ $score) { global $database; $database->execute( diff --git a/ext/pools/main.php b/ext/pools/main.php index 40270a0b..3f565b7f 100644 --- a/ext/pools/main.php +++ b/ext/pools/main.php @@ -353,9 +353,12 @@ class Pools extends Extension { return false; } } - - /* - * HERE WE GET THE LIST OF POOLS + + /** + * HERE WE GET THE LIST OF POOLS. + * + * @param Page $page + * @param int $pageNumber */ private function list_pools(Page $page, /*int*/ $pageNumber) { global $config, $database; @@ -399,8 +402,11 @@ class Pools extends Extension { } - /* + /** * HERE WE CREATE A NEW POOL + * + * @return mixed + * @throws PoolCreationException */ private function add_pool() { global $user, $database; @@ -431,7 +437,7 @@ class Pools extends Extension { /** * Retrieve information about pools given multiple pool IDs. - * @param $poolID Array of integers + * @param int $poolID Array of integers * @return 2D Array */ private function get_pool(/*int*/ $poolID) { @@ -441,7 +447,7 @@ class Pools extends Extension { /** * Retrieve information about a pool given a pool ID. - * @param $poolID Integer + * @param int $poolID the pool id * @return 2D array (with only 1 element in the one dimension) */ private function get_single_pool(/*int*/ $poolID) { diff --git a/ext/upload/main.php b/ext/upload/main.php index 028c2857..7ad79a0c 100644 --- a/ext/upload/main.php +++ b/ext/upload/main.php @@ -10,14 +10,23 @@ * Occurs when some data is being uploaded. */ class DataUploadEvent extends Event { - var $tmpname, $metadata, $hash, $type, $image_id = -1; + /** @var string */ + public $tmpname; + /** @var array */ + public $metadata; + /** @var string */ + public $hash; + /** @var string */ + public $type; + /** @var int */ + public $image_id = -1; /** * Some data is being uploaded. * This should be caught by a file handler. * -- Removed: param $user The user uploading the data. - * @param $tmpname string The temporary file used for upload. - * @param $metadata array Info about the file, should contain at least "filename", "extension", "tags" and "source". + * @param string $tmpname The temporary file used for upload. + * @param array $metadata Info about the file, should contain at least "filename", "extension", "tags" and "source". */ public function __construct(/*string*/ $tmpname, /*array*/ $metadata) { assert(file_exists($tmpname)); @@ -42,7 +51,7 @@ class UploadException extends SCoreException {} * This also includes transloaded files as well. */ class Upload extends Extension { - + /** @var bool */ public $is_full; // early, so it can stop the DataUploadEvent before any data handlers see it @@ -129,12 +138,12 @@ class Upload extends Extension { if(empty($image_id)) { throw new UploadException("Can not replace Image: No valid Image ID given."); } - + $image_old = Image::by_id($image_id); if(is_null($image_old)) { $this->theme->display_error(404, "Image not found", "No image in the database has the ID #$image_id"); } - + if(count($_FILES) + count($_POST) > 0) { if(count($_FILES) > 1) { throw new UploadException("Can not upload more than one image for replacing."); @@ -163,7 +172,7 @@ class Upload extends Extension { $url = $_GET['url']; $source = isset($_GET['source']) ? $_GET['source'] : $url; $ok = $this->try_transload($url, $tags, $source, $image_id); - $this->theme->display_upload_status($page, $ok); + $this->theme->display_upload_status($page, $ok); } else { $this->theme->display_replace_page($page, $image_id); @@ -316,11 +325,11 @@ class Upload extends Extension { /** * Handle an transload. - * @param $url - * @param $tags - * @param $source + * @param string $url + * @param mixed $tags + * @param string $source * @param string $replace - * @return bool TRUE on transload successful. + * @return bool Returns TRUE on transload successful. */ private function try_transload($url, $tags, $source, $replace='') { global $page, $config, $user; @@ -370,7 +379,7 @@ class Upload extends Extension { if(!empty($locked)){ $metadata['locked'] = $locked ? "on" : ""; } - + /* check for rating > adds to metadata if it has */ if(!empty($rating)){ $metadata['rating'] = $rating;