Merge pull request #676 from AmraniCh/improve-phpdocs

[Whoops\Run] Improve PHPdocs

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 @@
 
 final class Run implements RunInterface
 {
+    /**
+     * @var bool
+     */
     private $isRegistered;
+
+    /**
+     * @var bool
+     */
     private $allowQuit       = true;
+
+    /**
+     * @var bool
+     */
     private $sendOutput      = true;
 
     /**
@@ -31,17 +43,35 @@ final class Run implements RunInterface
      */
     private $handlerStack = [];
 
+    /**
+     * @var array
+     * @psalm-var list<array{patterns: string, levels: int}>
+     */
     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,20 +80,26 @@ public function appendHandler($handler)
     }
 
     /**
-     * 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)
     {
         return $this->pushHandler($handler);
     }
 
     /**
-     * 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,34 +108,40 @@ public function pushHandler($handler)
     }
 
     /**
-     * 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()
     {
         array_pop($this->handlerStack);
     }
 
     /**
-     * Removes the last handler
+     * Removes the last handler.
+     *
+     * @return void
      */
     public function removeLastHandler()
     {
         array_shift($this->handlerStack);
     }
 
     /**
-     * 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 +150,8 @@ public function getHandlers()
     }
 
     /**
-     * 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 +160,9 @@ public function clearHandlers()
         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 +186,8 @@ class_exists("\\Whoops\\Exception\\Inspector");
     }
 
     /**
-     * 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 +204,9 @@ public function unregister()
 
     /**
      * 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 +219,12 @@ public function allowQuit($exit = null)
     }
 
     /**
-     * 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 +240,12 @@ function ($pattern) use ($levels) {
                 (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 +254,16 @@ public function getSilenceErrorsInPaths()
         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 +281,7 @@ public function sendHttpCode($code = null)
 
         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 +290,10 @@ public function sendHttpCode($code = null)
 
     /**
      * 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 +306,11 @@ public function writeToOutput($send = null)
     }
 
     /**
-     * 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 +387,17 @@ public function handleException($exception)
     }
 
     /**
-     * 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 +432,8 @@ public function handleError($level, $message, $file = null, $line = null)
 
     /**
      * Special case to deal with Fatal errors and the like.
+     *
+     * @return void
      */
     public function handleShutdown()
     {
@@ -411,11 +457,24 @@ public function handleShutdown()
     }
 
     /**
-     * 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 +483,7 @@ private function resolveHandler($handler)
 
         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 +492,15 @@ private function resolveHandler($handler)
     }
 
     /**
-     * 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()
             );