From 48d5d8b564d7303735c66983507f05b1dbde7535 Mon Sep 17 00:00:00 2001 From: AmraniCh Date: Wed, 28 Oct 2020 13:59:50 +0100 Subject: [PATCH 1/2] [Whoops\Run] Improve PHPdocs --- src/Whoops/Run.php | 166 ++++++++++++++++++++++++++++++--------------- 1 file changed, 113 insertions(+), 53 deletions(-) diff --git a/src/Whoops/Run.php b/src/Whoops/Run.php index 1484736..446f0f6 100644 --- a/src/Whoops/Run.php +++ b/src/Whoops/Run.php @@ -7,6 +7,7 @@ namespace Whoops; use InvalidArgumentException; +use Throwable; use Whoops\Exception\ErrorException; use Whoops\Exception\Inspector; use Whoops\Handler\CallbackHandler; @@ -17,8 +18,19 @@ use Whoops\Util\SystemFacade; final class Run implements RunInterface { + /** + * @var bool + */ private $isRegistered; + + /** + * @var bool + */ private $allowQuit = true; + + /** + * @var bool + */ private $sendOutput = true; /** @@ -31,17 +43,34 @@ final class Run implements RunInterface */ private $handlerStack = []; + /** + * @var array + */ private $silencedPatterns = []; + /** + * @var SystemFacade + */ private $system; + /** + * In certain scenarios, like in shutdown handler, we can not throw exceptions. + * + * @var bool + */ + private $canThrowExceptions = true; + public function __construct(SystemFacade $system = null) { $this->system = $system ?: new SystemFacade; } /** - * Explicitly request your handler runs as the last of all currently registered handlers + * Explicitly request your handler runs as the last of all currently registered handlers. + * + * @param HandlerInterface $handler + * + * @return Run */ public function appendHandler($handler) { @@ -50,7 +79,11 @@ final class Run implements RunInterface } /** - * Explicitly request your handler runs as the first of all currently registered handlers + * Explicitly request your handler runs as the first of all currently registered handlers. + * + * @param HandlerInterface $handler + * + * @return Run */ public function prependHandler($handler) { @@ -58,12 +91,14 @@ final class Run implements RunInterface } /** - * Register your handler as the last of all currently registered handlers. + * Register your handler as the last of all currently registered handlers (to be executed first). * Prefer using appendHandler and prependHandler for clarity. * - * @throws InvalidArgumentException If argument is not callable or instance of HandlerInterface - * @param Callable|HandlerInterface $handler + * @param Callable|HandlerInterface $handler + * * @return Run + * + * @throws InvalidArgumentException If argument is not callable or instance of HandlerInterface. */ public function pushHandler($handler) { @@ -72,17 +107,21 @@ final class Run implements RunInterface } /** - * See removeFirstHandler and removeLastHandler - * @return null|HandlerInterface + * Removes and returns the last handler pushed to the handler stack. + * + * @see Run::removeFirstHandler(), Run::removeLastHandler() + * + * @return HandlerInterface|null */ public function popHandler() { return array_pop($this->handlerStack); } - /** - * Removes the first handler + * Removes the first handler. + * + * @return void */ public function removeFirstHandler() { @@ -90,7 +129,9 @@ final class Run implements RunInterface } /** - * Removes the last handler + * Removes the last handler. + * + * @return void */ public function removeLastHandler() { @@ -98,8 +139,8 @@ final class Run implements RunInterface } /** - * Returns an array with all handlers, in the - * order they were added to the stack. + * Returns an array with all handlers, in the order they were added to the stack. + * * @return array */ public function getHandlers() @@ -108,8 +149,8 @@ final class Run implements RunInterface } /** - * Clears all handlers in the handlerStack, including - * the default PrettyPage handler. + * Clears all handlers in the handlerStack, including the default PrettyPage handler. + * * @return Run */ public function clearHandlers() @@ -118,17 +159,9 @@ final class Run implements RunInterface return $this; } - /** - * @param \Throwable $exception - * @return Inspector - */ - private function getInspector($exception) - { - return new Inspector($exception); - } - /** * Registers this instance as an error handler. + * * @return Run */ public function register() @@ -152,7 +185,8 @@ final class Run implements RunInterface } /** - * Unregisters all handlers registered by this Whoops\Run instance + * Unregisters all handlers registered by this Whoops\Run instance. + * * @return Run */ public function unregister() @@ -169,7 +203,9 @@ final class Run implements RunInterface /** * Should Whoops allow Handlers to force the script to quit? - * @param bool|int $exit + * + * @param bool|int $exit + * * @return bool */ public function allowQuit($exit = null) @@ -182,10 +218,12 @@ final class Run implements RunInterface } /** - * Silence particular errors in particular files - * @param array|string $patterns List or a single regex pattern to match - * @param int $levels Defaults to E_STRICT | E_DEPRECATED - * @return \Whoops\Run + * Silence particular errors in particular files. + * + * @param array|string $patterns List or a single regex pattern to match. + * @param int $levels Defaults to E_STRICT | E_DEPRECATED. + * + * @return Run */ public function silenceErrorsInPaths($patterns, $levels = 10240) { @@ -201,12 +239,12 @@ final class Run implements RunInterface (array) $patterns ) ); + return $this; } - /** - * Returns an array with silent errors in path configuration + * Returns an array with silent errors in path configuration. * * @return array */ @@ -215,13 +253,16 @@ final class Run implements RunInterface return $this->silencedPatterns; } - /* + /** * Should Whoops send HTTP error code to the browser if possible? * Whoops will by default send HTTP code 500, but you may wish to * use 502, 503, or another 5xx family code. * * @param bool|int $code + * * @return int|false + * + * @throws InvalidArgumentException */ public function sendHttpCode($code = null) { @@ -239,7 +280,7 @@ final class Run implements RunInterface if ($code < 400 || 600 <= $code) { throw new InvalidArgumentException( - "Invalid status code '$code', must be 4xx or 5xx" + "Invalid status code '$code', must be 4xx or 5xx" ); } @@ -248,8 +289,10 @@ final class Run implements RunInterface /** * Should Whoops push output directly to the client? - * If this is false, output will be returned by handleException - * @param bool|int $send + * If this is false, output will be returned by handleException. + * + * @param bool|int $send + * * @return bool */ public function writeToOutput($send = null) @@ -262,11 +305,11 @@ final class Run implements RunInterface } /** - * Handles an exception, ultimately generating a Whoops error - * page. + * Handles an exception, ultimately generating a Whoops error page. * - * @param \Throwable $exception - * @return string Output generated by handlers + * @param Throwable $exception + * + * @return string Output generated by handlers. */ public function handleException($exception) { @@ -343,17 +386,17 @@ final class Run implements RunInterface } /** - * Converts generic PHP errors to \ErrorException - * instances, before passing them off to be handled. + * Converts generic PHP errors to \ErrorException instances, before passing them off to be handled. * * This method MUST be compatible with set_error_handler. * - * @param int $level - * @param string $message - * @param string $file - * @param int $line + * @param int $level + * @param string $message + * @param string|null $file + * @param int|null $line * * @return bool + * * @throws ErrorException */ public function handleError($level, $message, $file = null, $line = null) @@ -388,6 +431,8 @@ final class Run implements RunInterface /** * Special case to deal with Fatal errors and the like. + * + * @return void */ public function handleShutdown() { @@ -411,11 +456,24 @@ final class Run implements RunInterface } /** - * In certain scenarios, like in shutdown handler, we can not throw exceptions - * @var bool + * @param Throwable $exception + * + * @return Inspector */ - private $canThrowExceptions = true; + private function getInspector($exception) + { + return new Inspector($exception); + } + /** + * Resolves the giving handler. + * + * @param HandlerInterface $handler + * + * @return HandlerInterface + * + * @throws InvalidArgumentException + */ private function resolveHandler($handler) { if (is_callable($handler)) { @@ -424,7 +482,7 @@ final class Run implements RunInterface if (!$handler instanceof HandlerInterface) { throw new InvalidArgumentException( - "Handler must be a callable, or instance of " + "Handler must be a callable, or instance of " . "Whoops\\Handler\\HandlerInterface" ); } @@ -433,13 +491,15 @@ final class Run implements RunInterface } /** - * Echo something to the browser - * @param string $output - * @return $this + * Echo something to the browser. + * + * @param string $output + * + * @return Run */ private function writeToOutputNow($output) { - if ($this->sendHttpCode() && \Whoops\Util\Misc::canSendHeaders()) { + if ($this->sendHttpCode() && Misc::canSendHeaders()) { $this->system->setHttpResponseCode( $this->sendHttpCode() ); From 624c4b8d12f46a72d63d38f7c6be0ca22441cee7 Mon Sep 17 00:00:00 2001 From: El Amrani Chakir Date: Fri, 30 Oct 2020 05:50:31 +0100 Subject: [PATCH 2/2] Adding psalm-var tag Co-authored-by: Markus Staab --- src/Whoops/Run.php | 1 + 1 file changed, 1 insertion(+) diff --git a/src/Whoops/Run.php b/src/Whoops/Run.php index 446f0f6..4ea7630 100644 --- a/src/Whoops/Run.php +++ b/src/Whoops/Run.php @@ -45,6 +45,7 @@ final class Run implements RunInterface /** * @var array + * @psalm-var list */ private $silencedPatterns = [];