From d105d222869cd2e00bc7f7568e21c86a530b603a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rub=C3=A9n=20Calvo?= Date: Tue, 17 Jul 2018 12:48:27 +0200 Subject: [PATCH] [ticket/14285] Add comments PHPBB3-14285 --- phpBB/phpbb/storage/controller/attachment.php | 22 +++++++++- phpBB/phpbb/storage/controller/avatar.php | 29 +++++++++++++ phpBB/phpbb/storage/controller/controller.php | 43 +++++++++++++++++-- 3 files changed, 90 insertions(+), 4 deletions(-) diff --git a/phpBB/phpbb/storage/controller/attachment.php b/phpBB/phpbb/storage/controller/attachment.php index 17e6b408c9..13bb834380 100644 --- a/phpBB/phpbb/storage/controller/attachment.php +++ b/phpBB/phpbb/storage/controller/attachment.php @@ -27,6 +27,9 @@ use Symfony\Component\HttpFoundation\Request as symfony_request; use Symfony\Component\HttpFoundation\RedirectResponse; use Symfony\Component\HttpFoundation\ResponseHeaderBag; +/** + * Controller for /download/attachment/{id} routes + */ class attachment extends controller { /** @var auth */ @@ -47,7 +50,21 @@ class attachment extends controller /** @var user */ protected $user; - public function __construct(auth $auth, service $cache, config $config, $content_visibility, driver_interface $db, dispatcher $dispatcher, request $request, storage $storage, symfony_request $symfony_request, user $user) + /** + * Constructor + * + * @param auth $auth + * @param service $cache + * @param config $config + * @param content_visibility $content_visibility + * @param driver_interface $db + * @param dispatcher_interface $dispatcher + * @param request $request + * @param storage $storage + * @param symfony_request $symfony_request + * @param user $user + */ + public function __construct(auth $auth, service $cache, config $config, content_visibility $content_visibility, driver_interface $db, dispatcher $dispatcher, request $request, storage $storage, symfony_request $symfony_request, user $user) { parent::__construct($cache, $db, $storage, $symfony_request); @@ -59,6 +76,9 @@ class attachment extends controller $this->user = $user; } + /** + * {@inheritdoc} + */ public function handle($id) { $attach_id = (int) $id; diff --git a/phpBB/phpbb/storage/controller/avatar.php b/phpBB/phpbb/storage/controller/avatar.php index 7980b65266..a6ec3339e1 100644 --- a/phpBB/phpbb/storage/controller/avatar.php +++ b/phpBB/phpbb/storage/controller/avatar.php @@ -20,13 +20,26 @@ use phpbb\storage\storage; use Symfony\Component\HttpFoundation\Request as symfony_request; use Symfony\Component\HttpFoundation\ResponseHeaderBag; +/** + * Controller for /download/avatar/{file} routes + */ class avatar extends controller { /** @var config */ protected $config; + /** @var array */ protected $allowed_extensions = ['png', 'gif', 'jpg', 'jpeg']; + /** + * Constructor + * + * @param service $cache + * @param config $config + * @param driver_interface $db + * @param storage $storage + * @param symfony_request $symfony_request + */ public function __construct(service $cache, config $config, driver_interface $db, storage $storage, symfony_request $symfony_request) { parent::__construct($cache, $db, $storage, $symfony_request); @@ -34,6 +47,9 @@ class avatar extends controller $this->config = $config; } + /** + * {@inheritdoc} + */ public function handle($file) { $file = $this->decode_avatar_filename($file); @@ -41,6 +57,9 @@ class avatar extends controller return parent::handle($file); } + /** + * {@inheritdoc} + */ protected function is_allowed($file) { $ext = substr(strrchr($file, '.'), 1); @@ -49,6 +68,13 @@ class avatar extends controller return strpos($file, '.') && in_array($ext, $this->allowed_extensions); } + /** + * Decode avatar filename + * + * @param string $file Filename + * + * @return string Filename in filesystem + */ protected function decode_avatar_filename($file) { $avatar_group = false; @@ -65,6 +91,9 @@ class avatar extends controller return $this->config['avatar_salt'] . '_' . ($avatar_group ? 'g' : '') . $file . '.' . $ext; } + /** + * {@inheritdoc} + */ protected function prepare($file) { $disposition = $this->response->headers->makeDisposition( diff --git a/phpBB/phpbb/storage/controller/controller.php b/phpBB/phpbb/storage/controller/controller.php index 97ecd92730..a93c4f9567 100644 --- a/phpBB/phpbb/storage/controller/controller.php +++ b/phpBB/phpbb/storage/controller/controller.php @@ -20,6 +20,9 @@ use phpbb\storage\storage; use phpbb\storage\streamed_response; use Symfony\Component\HttpFoundation\Request as symfony_request; +/** + * Generic controller for storage + */ class controller { /** @var service */ @@ -37,6 +40,14 @@ class controller /** @var symfony_request */ protected $symfony_request; + /** + * Constructor + * + * @param service $cache + * @param driver_interfacd $db + * @param storage $storage + * @param symfony_request $symfony_request + */ public function __construct(service $cache, driver_interface $db, storage $storage, symfony_request $symfony_request) { $this->cache = $cache; @@ -46,6 +57,15 @@ class controller $this->response = new streamed_response(); } + /** + * Handler + * + * @param string $file File path + * + * @throws \phpbb\exception\http_exception when can't access $file + * + * @return \Symfony\Component\HttpFoundation\StreamedResponse a Symfony response object + */ public function handle($file) { if (!$this->is_allowed($file)) @@ -68,16 +88,35 @@ class controller return $this->response; } + /** + * If the user is allowed to download the file + * + * @param string $file File path + * + * @return bool + */ protected function is_allowed($file) { return true; } + /** + * Check if file exists + * + * @param string $file File path + * + * @return bool + */ protected function file_exists($file) { return $this->storage->exists($file); } + /** + * Prepare response + * + * @param string $file File path + */ protected function prepare($file) { $this->response->setPublic(); @@ -132,9 +171,7 @@ class controller /** * Garbage Collection * - * @param bool $exit Whether to die or not. - * - * @return null + * @param bool $exit Whether to die or not */ protected function file_gc() {