Add PHPStan at level 6

.github/workflows/test-package.yml

@@ -49,3 +49,42 @@ jobs:
       run: composer update --prefer-dist --no-progress --no-suggest --no-interaction ${{ matrix.composer-flags }}
 
     - run: composer run-script test
+
+  phpstan:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # TODO: we likely have to care about Guzzle's version too - ideally we'd
+        #       check our use of Guzzle is correct on each version
+        php-version: ['7.1', '8.1']
+        phpstan-version: ['~1.4']
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: install PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ matrix.php-version }}
+        coverage: none
+        extensions: intl, mbstring
+        # by default setup-php uses a production php.ini so force development values
+        ini-values: >-
+          zend.exception_ignore_args=Off,
+          zend.exception_string_param_max_len=15,
+          error_reporting=-1,
+          display_errors=On,
+          display_startup_errors=On,
+          zend.assertions=1
+
+    # - name: require guzzle
+    #   run: composer require "guzzlehttp/guzzle:${{ matrix.guzzle-version }}" --no-update ${{ matrix.composer-flags }}
+
+    - name: require phpstan
+      run: composer require "phpstan/phpstan:${{ matrix.phpstan-version }}" --no-update ${{ matrix.composer-flags }}
+
+    - name: install dependencies
+      run: composer update --prefer-dist --no-progress --no-suggest --no-interaction ${{ matrix.composer-flags }}
+
+    - run: ./vendor/bin/phpstan

CHANGELOG.md

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+## TBD
+
+### Fixes
+
+* A number of errors in docblocks have been corrected
+  [xPaw](https://github.com/xPaw)
+  [#633](https://github.com/bugsnag/bugsnag-php/pull/633)
+  [#637](https://github.com/bugsnag/bugsnag-php/pull/637)
+
 ## 3.26.1 (2021-09-09)
 
 ### Fixes

phpstan.neon

@@ -0,0 +1,14 @@
+parameters:
+    level: 6
+
+    treatPhpDocTypesAsCertain: false
+    checkMissingIterableValueType: false # TODO: remove this!
+
+    paths:
+        - src/
+
+    ignoreErrors:
+        -
+            message: "#^Property Bugsnag\\\\Handler\\:\\:\\$reservedMemory is never read, only written\\.$#"
+            count: 1
+            path: src/Handler.php

src/Breadcrumbs/Recorder.php

@@ -5,6 +5,9 @@
 use Countable;
 use Iterator;
 
+/**
+ * @implements Iterator<int, Breadcrumb>
+ */
 class Recorder implements Countable, Iterator
 {
     /**
@@ -138,7 +141,7 @@ public function rewind()
     /**
      * Is the current key position set?
      *
-     * @return int
+     * @return bool
      */
     #[\ReturnTypeWillChange]
     public function valid()

src/Client.php

@@ -105,6 +105,7 @@ public static function make(
         $config = new Configuration($apiKey ?: $env->get('BUGSNAG_API_KEY'));
         $guzzle = static::makeGuzzle($notifyEndpoint ?: $env->get('BUGSNAG_ENDPOINT'));
 
+        // @phpstan-ignore-next-line
         $client = new static($config, null, $guzzle);
 
         if ($defaults) {
@@ -470,7 +471,7 @@ public function getSessionTracker()
     /**
      * Get the Bugsnag API Key.
      *
-     * @var string
+     * @return string
      */
     public function getApiKey()
     {
@@ -550,7 +551,7 @@ public function setFilters(array $filters)
      *
      * @deprecated Use redactedKeys instead
      *
-     * @var string[]
+     * @return string[]
      */
     public function getFilters()
     {
@@ -586,7 +587,7 @@ public function setProjectRootRegex($projectRootRegex)
      *
      * @param string $file
      *
-     * @return string
+     * @return bool
      */
     public function isInProject($file)
     {
@@ -674,7 +675,7 @@ public function setNotifier(array $notifier)
     /**
      * Get the notifier to report as to Bugsnag.
      *
-     * @var string[]
+     * @return string[]
      */
     public function getNotifier()
     {
@@ -948,6 +949,8 @@ public function getSessionClient()
      * This is an amount of bytes or 'null' to disable increasing the limit.
      *
      * @param int|null $value
+     *
+     * @return Configuration
      */
     public function setMemoryLimitIncrease($value)
     {
@@ -985,7 +988,7 @@ public function setDiscardClasses(array $discardClasses)
      *
      * This can contain both fully qualified class names and regular expressions.
      *
-     * @var array
+     * @return array
      */
     public function getDiscardClasses()
     {
@@ -1009,7 +1012,7 @@ public function setRedactedKeys(array $redactedKeys)
     /**
      * Get the array of metadata keys that should be redacted.
      *
-     * @var string[]
+     * @return string[]
      */
     public function getRedactedKeys()
     {

src/Configuration.php

@@ -133,7 +133,7 @@ class Configuration
     /**
      * A client to use to send sessions.
      *
-     * @var \GuzzleHttp\ClientInterface
+     * @var \GuzzleHttp\ClientInterface|null
      *
      * @deprecated This will be removed in the next major version.
      */
@@ -204,7 +204,7 @@ public function __construct($apiKey)
     /**
      * Get the Bugsnag API Key.
      *
-     * @var string
+     * @return string
      */
     public function getApiKey()
     {
@@ -288,7 +288,7 @@ public function setFilters(array $filters)
      *
      * @deprecated Use redactedKeys instead
      *
-     * @var string[]
+     * @return string[]
      */
     public function getFilters()
     {
@@ -317,7 +317,7 @@ public function setProjectRoot($projectRoot)
      */
     public function setProjectRootRegex($projectRootRegex)
     {
-        if ($projectRootRegex && @preg_match($projectRootRegex, null) === false) {
+        if ($projectRootRegex && @preg_match($projectRootRegex, '') === false) {
             throw new InvalidArgumentException('Invalid project root regex: '.$projectRootRegex);
         }
 
@@ -330,7 +330,7 @@ public function setProjectRootRegex($projectRootRegex)
      *
      * @param string $file
      *
-     * @return string
+     * @return bool
      */
     public function isInProject($file)
     {
@@ -359,7 +359,7 @@ public function setStripPath($stripPath)
      */
     public function setStripPathRegex($stripPathRegex)
     {
-        if ($stripPathRegex && @preg_match($stripPathRegex, null) === false) {
+        if ($stripPathRegex && @preg_match($stripPathRegex, '') === false) {
             throw new InvalidArgumentException('Invalid strip path regex: '.$stripPathRegex);
         }
 
@@ -423,7 +423,7 @@ public function setNotifier(array $notifier)
     /**
      * Get the notifier to report as to Bugsnag.
      *
-     * @var string[]
+     * @return string[]
      */
     public function getNotifier()
     {
@@ -804,6 +804,8 @@ public function getSessionClient()
      * This is an amount of bytes or 'null' to disable increasing the limit.
      *
      * @param int|null $value
+     *
+     * @return $this
      */
     public function setMemoryLimitIncrease($value)
     {
@@ -843,7 +845,7 @@ public function setDiscardClasses(array $discardClasses)
      *
      * This can contain both fully qualified class names and regular expressions.
      *
-     * @var array
+     * @return array
      */
     public function getDiscardClasses()
     {
@@ -867,7 +869,7 @@ public function setRedactedKeys(array $redactedKeys)
     /**
      * Get the array of metadata keys that should be redacted.
      *
-     * @var string[]
+     * @return string[]
      */
     public function getRedactedKeys()
     {

src/Handler.php

@@ -70,6 +70,7 @@ public static function register($client = null)
             $client = Client::make($client);
         }
 
+        // @phpstan-ignore-next-line
         $handler = new static($client);
         $handler->registerBugsnagHandlers(true);
 
@@ -196,6 +197,9 @@ public function exceptionHandler($throwable)
 
             return;
         } catch (Throwable $exceptionFromPreviousHandler) {
+            // TODO: if we drop support for PHP 5, we can remove this catch, which
+            //       fixes the PHPStan issue here
+            // @phpstan-ignore-next-line
         } catch (Exception $exceptionFromPreviousHandler) {
         }
 
@@ -307,8 +311,9 @@ public function shutdownHandler()
             && preg_match($this->oomRegex, $lastError['message'], $matches) === 1
         ) {
             $currentMemoryLimit = (int) $matches[1];
+            $newMemoryLimit = $currentMemoryLimit + $this->client->getMemoryLimitIncrease();
 
-            ini_set('memory_limit', $currentMemoryLimit + $this->client->getMemoryLimitIncrease());
+            ini_set('memory_limit', (string) $newMemoryLimit);
         }
 
         // Check if a fatal error caused this shutdown

src/HttpClient.php

@@ -262,14 +262,16 @@ protected function getHeaders($version = self::NOTIFY_PAYLOAD_VERSION)
     /**
      * Send a POST request to Bugsnag.
      *
-     * @param string $uri  the uri to hit
-     * @param array  $data the request options
+     * @param string $uri the uri to hit
+     * @param array $options the request options
      *
      * @return void
      */
     protected function post($uri, array $options = [])
     {
         if (GuzzleCompat::isUsingGuzzle5()) {
+            // TODO: validate this by running PHPStan with Guzzle 5
+            // @phpstan-ignore-next-line
             $this->guzzle->post($uri, $options);
         } else {
             $this->guzzle->request('POST', $uri, $options);

src/Internal/GuzzleCompat.php

@@ -43,8 +43,9 @@ public static function getBaseUriOptionName()
      */
     public static function getBaseUri(GuzzleHttp\ClientInterface $guzzle)
     {
+        // TODO: validate this by running PHPStan with Guzzle 5
         return self::isUsingGuzzle5()
-            ? $guzzle->getBaseUrl()
+            ? $guzzle->getBaseUrl() // @phpstan-ignore-line
             : $guzzle->getConfig(self::getBaseUriOptionName());
     }
 

src/Report.php

@@ -125,7 +125,7 @@ class Report
     /**
      * Attached session from SessionTracking.
      *
-     * @var array
+     * @var array|null
      */
     protected $session;
 
@@ -143,6 +143,7 @@ class Report
      */
     public static function fromPHPError(Configuration $config, $code, $message, $file, $line, $fatal = false)
     {
+        // @phpstan-ignore-next-line
         $report = new static($config);
 
         $report->setPHPError($code, $message, $file, $line, $fatal)
@@ -162,6 +163,7 @@ public static function fromPHPError(Configuration $config, $code, $message, $fil
      */
     public static function fromPHPThrowable(Configuration $config, $throwable)
     {
+        // @phpstan-ignore-next-line
         $report = new static($config);
 
         $report->setPHPThrowable($throwable)
@@ -182,6 +184,7 @@ public static function fromPHPThrowable(Configuration $config, $throwable)
      */
     public static function fromNamedError(Configuration $config, $name, $message = null)
     {
+        // @phpstan-ignore-next-line
         $report = new static($config);
 
         $report->setName($name)
@@ -229,6 +232,9 @@ public function getOriginalError()
      */
     public function setPHPThrowable($throwable)
     {
+        // TODO: if we drop support for PHP 5, we can remove this check for
+        //       'Exception', which fixes the PHPStan issue here
+        // @phpstan-ignore-next-line
         if (!$throwable instanceof Throwable && !$throwable instanceof Exception) {
             throw new InvalidArgumentException('The throwable must implement Throwable or extend Exception.');
         }
@@ -331,6 +337,8 @@ public function setSeverityReason(array $severityReason)
     /**
      * Sets the unhandled flag.
      *
+     * @param bool $unhandled
+     *
      * @return $this
      */
     public function setUnhandled($unhandled)
@@ -637,7 +645,7 @@ public function getSummary()
     /**
      * Sets the session data.
      *
-     * @return $this
+     * @return void
      */
     public function setSessionData(array $session)
     {
@@ -746,12 +754,12 @@ protected function exceptionObject()
      * @param mixed $obj        the data to cleanup
      * @param bool  $isMetaData if it is meta data
      *
-     * @return array|null
+     * @return mixed
      */
     protected function cleanupObj($obj, $isMetaData)
     {
         if (is_null($obj)) {
-            return;
+            return null;
         }
 
         if (is_array($obj)) {