From 2fc3fbb41dbd81a92dfe27a22b31f36b10ea37ca Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:02:39 +0000 Subject: Extend and improve PHP code comments (PHPDoc) Add file summaries, @copyright tags and other comments. Covers majority of the PHP code base now. I have avoided being too verbose and omitted some potential tags. Most visibly to the user, this comments every user configurable setting and clarifies what some of the options do. POMF_DB_USER and POMF_DB_PASS are not rendered perfectly in phpDocumentor version 2.8.5. This is a sacrifice I made in attempt for not being too verbose and obvious. Response class gets a @todo for being a god object. --- static/classes/Response.class.php | 75 +++++++++++++++++++++++++++++++- static/classes/UploadException.class.php | 8 ++-- static/classes/UploadedFile.class.php | 12 +++-- static/includes/database.inc.php | 4 +- static/includes/settings.inc.php | 71 +++++++++++++++++++++++++----- static/upload.php | 12 +++-- 6 files changed, 159 insertions(+), 23 deletions(-) (limited to 'static') diff --git a/static/classes/Response.class.php b/static/classes/Response.class.php index f8555d6..fdf57e6 100755 --- a/static/classes/Response.class.php +++ b/static/classes/Response.class.php @@ -1,8 +1,11 @@ - * Copyright (c) 2015, 2016 the Pantsu.cat developers + * Prints file upload API responses depending on desired response type format. + * + * @copyright Copyright (c) 2015 cenci0 + * @copyright Copyright (c) 2015, 2016 the Pantsu.cat developers + * * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -23,10 +26,30 @@ * SOFTWARE. */ +/** + * The Response class is a do-it-all for getting responses out in different + * formats. + * + * @todo Create sub-classes to split and extend this god object. + */ class Response { + /** + * Indicates response type used for routing. + * + * Valid strings are 'csv', 'html', 'json' and 'text'. + * + * @var string $type Response type + */ private $type; + /** + * Indicates requested response type. + * + * Valid strings are 'csv', 'html', 'json', 'gyazo' and 'text'. + * + * @param string|null $response_type Response type + */ public function __construct($response_type = null) { switch ($response_type) { @@ -59,6 +82,13 @@ class Response } } + /** + * Routes error messages depending on response type. + * + * @param int $code HTTP status code number. + * @param int $desc Descriptive error message. + * @return void + */ public function error($code, $desc) { $response = null; @@ -82,6 +112,12 @@ class Response echo $response; } + /** + * Routes success messages depending on response type. + * + * @param mixed[] $files + * @return void + */ public function send($files) { $response = null; @@ -106,7 +142,11 @@ class Response } /** + * Indicates with CSV body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $description Descriptive error message. + * @return string Error message in CSV format. */ private static function csv_error($description) { @@ -114,7 +154,11 @@ class Response } /** + * Indicates with CSV body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in CSV format. */ private static function csv_success($files) { @@ -130,7 +174,12 @@ class Response } /** + * Indicates with HTML body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $code HTTP status code number. + * @param int $description Descriptive error message. + * @return string Error message in HTML format. */ private static function html_error($code, $description) { @@ -138,7 +187,11 @@ class Response } /** + * Indicates with HTML body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in HTML format. */ private static function html_success($files) { @@ -152,7 +205,12 @@ class Response } /** + * Indicates with JSON body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $code HTTP status code number. + * @param int $description Descriptive error message. + * @return string Error message in pretty-printed JSON format. */ private static function json_error($code, $description) { @@ -164,7 +222,11 @@ class Response } /** + * Indicates with JSON body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in pretty-printed JSON format. */ private static function json_success($files) { @@ -175,7 +237,12 @@ class Response } /** + * Indicates with plain text body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $code HTTP status code number. + * @param int $description Descriptive error message. + * @return string Error message in plain text format. */ private static function text_error($code, $description) { @@ -183,7 +250,11 @@ class Response } /** + * Indicates with plain text body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in plain text format. */ private static function text_success($files) { diff --git a/static/classes/UploadException.class.php b/static/classes/UploadException.class.php index dbe47eb..7740ee6 100755 --- a/static/classes/UploadException.class.php +++ b/static/classes/UploadException.class.php @@ -1,6 +1,11 @@ + * @author Michiel Thalen + * @copyright * -------------------------------------------------------------------- * The PHP License, version 3.01 * Copyright (c) 1999 - 2014 The PHP Group. All rights reserved. @@ -71,9 +76,6 @@ * . */ -// Exception class extension from: http://php.net/manual/en/features.file-upload.errors.php#89374 -// Handles files error returning a proper error description - class UploadException extends Exception { public function __construct($code) diff --git a/static/classes/UploadedFile.class.php b/static/classes/UploadedFile.class.php index 99020ce..1149581 100644 --- a/static/classes/UploadedFile.class.php +++ b/static/classes/UploadedFile.class.php @@ -1,7 +1,9 @@ + * Returns information about uploaded files. + * + * @copyright Copyright (c) 2013, 2014 Peter Lejeck * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -31,14 +33,18 @@ class UploadedFile public $tempfile; public $error; - /* Cached checksums */ + /** + * SHA-1 checksum + * + * @var string 40 digit hexadecimal hash (160 bits) + */ private $sha1; /** * Generates the SHA1 or returns the cached SHA1 hash for the file. * * @deprecated 2.1.0 To be replaced with SHA-256 hashing. - * @return string + * @return string|false $sha1 */ public function get_sha1() { diff --git a/static/includes/database.inc.php b/static/includes/database.inc.php index ff04561..7a1d4f9 100644 --- a/static/includes/database.inc.php +++ b/static/includes/database.inc.php @@ -1,7 +1,9 @@ + * Prepares a PDO connection between Pomf and a database server. + * + * @copyright Copyright (c) 2013 Peter Lejeck * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/static/includes/settings.inc.php b/static/includes/settings.inc.php index 6072249..ce6fa5e 100644 --- a/static/includes/settings.inc.php +++ b/static/includes/settings.inc.php @@ -1,9 +1,12 @@ - * Copyright (c) 2015 cenci0 - * Copyright (c) 2015 the Pantsu.cat developers + * User configurable settings for Pomf. + * + * @copyright Copyright (c) 2013, 2014 Peter Lejeck + * @copyright Copyright (c) 2015 cenci0 + * @copyright Copyright (c) 2015 the Pantsu.cat developers + * * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -24,22 +27,70 @@ * SOFTWARE. */ -// PDO socket -// mysql.sock path can be different from /tmp/mysql.sock, see /etc/my.cnf +/** + * PDO connection socket + * + * Database connection to use for communication. Currently, MySQL is the only + * DSN prefix supported. + * + * @see http://php.net/manual/en/ref.pdo-mysql.connection.php PHP manual for + * PDO_MYSQL DSN. + * @param string POMF_DB_CONN DSN:host|unix_socket=hostname|path;dbname=database + */ define('POMF_DB_CONN', 'mysql:unix_socket=/tmp/mysql.sock;dbname=pomf'); -// MySQL user and password + +/** + * PDO database login credentials + */ + +/** @param string POMF_DB_NAME Database username */ define('POMF_DB_USER', 'pomf'); +/** @param string POMF_DB_PASS Database password */ define('POMF_DB_PASS', '***'); -// Root location of files +/** + * File system location where to store uploaded files + * + * @param string Path to directory with trailing delimiter + */ define('POMF_FILES_ROOT', '/mnt/pantsu/http/files/'); -// Maximum number of iterations while generating a new filename + +/** + * Maximum number of iterations while generating a new filename + * + * Pomf uses an algorithm to generate random filenames. Sometimes a file may + * exist under a randomly generated filename, so we count tries and keep trying. + * If this value is exceeded, we give up trying to generate a new filename. + * + * @param int POMF_FILES_RETRIES Number of attempts to retry + */ define('POMF_FILES_RETRIES', 15); -// Number of random characters to use in a new filename + +/** + * The length of generated filename (without file extension) + * + * @param int POMF_FILES_LENGTH Number of random alphabetical ASCII characters + * to use + */ define('POMF_FILES_LENGTH', 6); -// URL to prepend to output (include trailing slash) + +/** + * URI to prepend to links for uploaded files + * + * @param string POMF_URL URI with trailing delimiter + */ define('POMF_URL', 'https://i.pantsu.cat/'); +/** + * Double dot file extensions + * + * Pomf keeps the last file extension for the uploaded file. In other words, an + * uploaded file with `.tar.gz` extension will be given a random filename which + * ends in `.gz` unless configured here to ignore discards for `.tar.gz`. + * + * @param string[] $doubledots Array of double dot file extensions strings + * without the first prefixing dot + */ $doubledots = array_map('strrev', array( 'tar.gz', 'tar.bz', diff --git a/static/upload.php b/static/upload.php index 4bee979..b8fb46a 100644 --- a/static/upload.php +++ b/static/upload.php @@ -1,10 +1,14 @@ - * Copyright (c) 2013, 2014, 2015 Eric Johansson - * Copyright (c) 2015 cenci0 - * Copyright (c) 2015, 2016 the Pantsu.cat developers + * Handles POST uploads, generates filenames, moves files around and commits + * uploaded metadata to database. + * + * @copyright Copyright (c) 2013, 2014 Peter Lejeck + * @copyright Copyright (c) 2013, 2014, 2015 Eric Johansson + * @copyright Copyright (c) 2015 cenci0 + * @copyright Copyright (c) 2015, 2016 the Pantsu.cat developers + * * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal -- cgit v1.2.3 From 118e7a7e53f32cc4ed76ec164de4835619d319d4 Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:21:14 +0000 Subject: Add Pantsu.cat copyright year 2016 for recent change Claiming copyright for parts of UploadedFile.class.php and settings.inc.php as per previous change, which introduced PHPDoc comments. The other files where edits were made in previous commits are non-substantial and thus most likely not under copyright. --- static/classes/UploadedFile.class.php | 2 ++ static/includes/settings.inc.php | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'static') diff --git a/static/classes/UploadedFile.class.php b/static/classes/UploadedFile.class.php index 1149581..8c80b4a 100644 --- a/static/classes/UploadedFile.class.php +++ b/static/classes/UploadedFile.class.php @@ -4,6 +4,8 @@ * Returns information about uploaded files. * * @copyright Copyright (c) 2013, 2014 Peter Lejeck + * @copyright Copyright (c) 2016 the Pantsu.cat developers + * * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/static/includes/settings.inc.php b/static/includes/settings.inc.php index ce6fa5e..872fde0 100644 --- a/static/includes/settings.inc.php +++ b/static/includes/settings.inc.php @@ -5,7 +5,7 @@ * * @copyright Copyright (c) 2013, 2014 Peter Lejeck * @copyright Copyright (c) 2015 cenci0 - * @copyright Copyright (c) 2015 the Pantsu.cat developers + * @copyright Copyright (c) 2015, 2016 the Pantsu.cat developers * * * Permission is hereby granted, free of charge, to any person obtaining a copy -- cgit v1.2.3 From f5f387293f67b6d0fcd2f34a5d118db88ef9660c Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:26:06 +0000 Subject: UploadedFile: Fix typo SHA1 to SHA-1 This typo has been around for a while. Well, not anymore. --- static/classes/UploadedFile.class.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'static') diff --git a/static/classes/UploadedFile.class.php b/static/classes/UploadedFile.class.php index 8c80b4a..20d42b3 100644 --- a/static/classes/UploadedFile.class.php +++ b/static/classes/UploadedFile.class.php @@ -43,7 +43,7 @@ class UploadedFile private $sha1; /** - * Generates the SHA1 or returns the cached SHA1 hash for the file. + * Generates the SHA-1 or returns the cached SHA-1 hash for the file. * * @deprecated 2.1.0 To be replaced with SHA-256 hashing. * @return string|false $sha1 -- cgit v1.2.3 From 4606553f38909b483bc06674f9558ede1a9ff1f6 Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Wed, 25 May 2016 03:12:40 +0000 Subject: Response: Clarify what http_response_code(200); is Add a comment explaining how HTTP status code 200 means success. --- static/classes/Response.class.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'static') diff --git a/static/classes/Response.class.php b/static/classes/Response.class.php index fdf57e6..081baa6 100755 --- a/static/classes/Response.class.php +++ b/static/classes/Response.class.php @@ -137,7 +137,7 @@ class Response break; } - http_response_code(200); + http_response_code(200); // "200 OK". Success. echo $response; } -- cgit v1.2.3