New exceptions and phpstan level 5 updates (#8)

* Updated CS-Fixer and processed files
* Fixed PHPStan errors up to level 5
* Renamed and created new exceptions for different errors

.php-cs-fixer.dist.php

@@ -0,0 +1,23 @@
+<?php
+
+$finder = PhpCsFixer\Finder::create()->in(__DIR__);
+
+return (new PhpCsFixer\Config())
+    ->setRules([
+        '@Symfony' => true,
+        'new_with_braces' => false,
+        'trailing_comma_in_multiline' => false,
+        'not_operator_with_successor_space' => true,
+        'phpdoc_align' => false,
+        'phpdoc_summary' => false,
+        'function_declaration' => [
+            'closure_function_spacing' => 'one'
+        ],
+        'blank_line_before_statement' => [
+            'statements' => [
+                 'return', 'try', 'throw'
+            ]
+        ]
+    ])
+    ->setFinder($finder)
+    ->setUsingCache(false);

composer.json

@@ -40,8 +40,10 @@
         }
     },
     "scripts": {
-        "fix": "php-cs-fixer fix",
+        "fix": "tools/php-cs-fixer/vendor/bin/php-cs-fixer fix",
         "test": "@php tests/memory.php",
-        "lint": "php-cs-fixer fix --dry-run --diff"
+        "lint": "tools/php-cs-fixer/vendor/bin/php-cs-fixer fix --dry-run --diff",
+        "phpstan": "tools/phpstan/vendor/bin/phpstan --memory-limit=1G analyse",
+        "phpstan-strict": "tools/phpstan/vendor/bin/phpstan --memory-limit=1G --level=6 analyse"
     }
 }

phpstan.neon

@@ -0,0 +1,8 @@
+parameters:
+    level: 5
+    paths:
+        - src
+        - tests
+    checkMissingIterableValueType: false
+    inferPrivatePropertyTypeFromConstructor: true
+    treatPhpDocTypesAsCertain: false

src/Attachment.php

@@ -16,15 +16,14 @@ class Attachment
     public $origFilename;
 
     /**
-     * @param Laminas\Mail\Storage\Part
+     * @var Part
      */
     private $part;
 
     /**
      * Created during generate attachment file paths
      */
     private $baseDir;
-    private $fileSysName;
     private $fileSysPath;
     private $fileDatePath;
 
@@ -36,30 +35,23 @@ public function __construct(Part $part)
     /**
      * Generate a new, reproducible attachment ID for a message's
      * attachment part.
-     *
-     * @param Message $message
      */
     public function generateId(Message $message)
     {
-        if (! $this->part) {
-            throw new Exception('Part not set on attachment.');
-        }
-
         $headers = $this->part->getHeaders();
         $hasAttachmentId = $headers->has('x-attachment-id');
         $attachmentId = $hasAttachmentId
             ? trim($this->part->getHeaderField('x-attachment-id'), ' <>')
             : null;
         $this->id = $hasAttachmentId && $attachmentId
             ? $attachmentId
-            : self::generateAttachmentId($message, $this->part->partNum);
+            : self::generateAttachmentId($message, $this->part->key());
     }
 
     /**
      * Create an ID for a message attachment. This takes the attributes
      * name, date, filename, etc and hashes the result.
      *
-     * @param Message $message
      * @param string $partNum Can take the form "1.2.1", not always an int
      *
      * @return string
@@ -83,9 +75,6 @@ protected static function generateAttachmentId(Message $message, string $partNum
      * attachment part. This will set the path to be inside a
      * folder like 'YYYY/MM' into the $baseDir location. The
      * date part is determined from the $message's date.
-     *
-     * @param Message $message
-     * @param string $baseDir
      */
     public function generateFilepath(Message $message, string $baseDir)
     {
@@ -109,18 +98,17 @@ public function generateFilepath(Message $message, string $baseDir)
         // an error in file_put_contents.
         $fileSysName = substr($fileSysName, 0, 250);
         // Create the YYYY/MM directory to put the attachment into
-        $this->fileDatePath = sprintf(
-            '%s%s%s',
+        $this->fileDatePath = sprintf('%s%s%s',
             date('Y', $timestamp),
             DIRECTORY_SEPARATOR,
-            date('m', $timestamp));
+            date('m', $timestamp)
+        );
         $this->filepath = $this->fileDatePath
             .DIRECTORY_SEPARATOR
             .$fileSysName;
         $this->fileSysPath = $this->baseDir
             .DIRECTORY_SEPARATOR
             .$this->filepath;
-        $this->fileSysName = $fileSysName;
     }
 
     /**

src/Exceptions/FolderAccessException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Pb\Imap\Exceptions;
+
+use Exception;
+
+class FolderAccessException extends Exception
+{
+    public function __construct(string $folder, string $verb)
+    {
+        $this->message = sprintf('Cannot %s folder %s, %s',
+            $verb,
+            $folder,
+            'maybe it doesn\'t exist'
+        );
+    }
+}

src/Exceptions/FolderUpdateException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Pb\Imap\Exceptions;
+
+use Exception;
+
+class FolderUpdateException extends Exception
+{
+}

src/Exceptions/MailboxAccessException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Pb\Imap\Exceptions;
+
+use Exception;
+
+class MailboxAccessException extends Exception
+{
+    public $message = 'Failed to connect to IMAP mailbox';
+}

src/Exceptions/MessageSizeLimit.php → src/Exceptions/MessageSizeLimitException.php

@@ -4,7 +4,7 @@
 
 use Exception;
 
-class MessageSizeLimit extends Exception
+class MessageSizeLimitException extends Exception
 {
     public function __construct(int $maxSize, int $messageSize, int $memoryLimit)
     {

src/Exceptions/MessageUpdateException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Pb\Imap\Exceptions;
+
+use Exception;
+
+class MessageUpdateException extends Exception
+{
+}

src/File.php

@@ -13,16 +13,14 @@ class File
      * it tries to find one from the lookup array. If none is still
      * found use the specified default.
      *
-     * @param string $filename
-     * @param string $mimeType
      * @param string $default
      */
     public static function addExtensionIfMissing(
         string &$filename,
         string $mimeType,
         string $default = null
     ) {
-        if (! $filename || ! strlen($filename)) {
+        if (! strlen($filename)) {
             return null;
         }
 
@@ -45,10 +43,6 @@ public static function addExtensionIfMissing(
     /**
      * Converts a string from one encoding to another.
      *
-     * @param string $string
-     * @param string $fromEncoding
-     * @param string $toEncoding
-     *
      * @return string Converted string if conversion was successful,
      *   or the original string if not
      */
@@ -85,8 +79,6 @@ public static function convertEncoding(
     /**
      * Decodes 7bit text.
      *
-     * @param string $string
-     *
      * @return string
      */
     public static function decode7Bit(string $string)

src/Imap.php

@@ -2,32 +2,36 @@
 
 namespace Pb\Imap;
 
+use Laminas\Mail\Storage\Folder as LaminasFolder;
 use Laminas\Mail\Storage\Imap as LaminasImap;
-use RuntimeException;
+use Pb\Imap\Exceptions\FolderAccessException;
+use Pb\Imap\Exceptions\FolderUpdateException;
+use Pb\Imap\Exceptions\MessageUpdateException;
 
 class Imap extends LaminasImap
 {
     /**
      * Examine given folder. Folder must be selectable!
      *
-     * @param \Laminas\Mail\Storage\Folder|string $globalName
+     * @param LaminasFolder|string $globalName
      *   global name of folder or instance for subfolder
      *
-     * @throws RuntimeException
+     * @throws FolderAccessException
      *
-     * @return null|array
+     * @return array|null
      */
     public function examineFolder($globalName)
     {
-        $this->currentFolder = $globalName;
+        $this->currentFolder = is_string($globalName)
+            ? $globalName
+            : $globalName->getGlobalName();
+
         $examine = $this->protocol->examine($this->currentFolder);
 
         if (! $examine) {
             $this->currentFolder = '';
 
-            throw new RuntimeException(
-                "Cannot examine folder, maybe it doesn't exist"
-            );
+            throw new FolderAccessException($globalName, 'examine');
         }
 
         return $examine;
@@ -36,25 +40,25 @@ public function examineFolder($globalName)
     /**
      * Select given folder.
      *
-     * @param \Laminas\Mail\Storage\Folder|string $globalName
+     * @param LaminasFolder|string $globalName
      *   global name of folder or instance for subfolder
      *
-     * @throws RuntimeException
-     * @throws Protocol\Exception\RuntimeException
+     * @throws FolderAccessException
      *
-     * @return null|array
+     * @return array|null
      */
     public function selectFolder($globalName)
     {
-        $this->currentFolder = $globalName;
+        $this->currentFolder = is_string($globalName)
+            ? $globalName
+            : $globalName->getGlobalName();
+
         $select = $this->protocol->select($this->currentFolder);
 
         if (! $select) {
             $this->currentFolder = '';
 
-            throw new RuntimeException(
-                "Cannot select folder, maybe it doesn't exist"
-            );
+            throw new FolderAccessException($globalName, 'select');
         }
 
         return $select;
@@ -67,9 +71,6 @@ public function selectFolder($globalName)
      * Returns an array of integers, either the message numbers
      * or the UIDs if that option is enabled.
      *
-     * @param array $params
-     * @param bool $uid
-     *
      * @return array
      */
     public function search(array $params, bool $uid = false)
@@ -86,15 +87,16 @@ public function search(array $params, bool $uid = false)
      * @param int $id number of message
      * @param array $flags new flags for message
      *
-     * @throws RuntimeException
+     * @throws MessageUpdateException
      */
     public function addFlags(int $id, array $flags)
     {
         if (! $this->protocol->store($flags, $id, null, '+', true)) {
-            throw new RuntimeException(
+            $message =
                 'Cannot add flags; have you tried to set the '.
-                'recent flag or special chars?'
-            );
+                'recent flag or special chars?';
+
+            throw new MessageUpdateException($message);
         }
     }
 
@@ -107,27 +109,28 @@ public function addFlags(int $id, array $flags)
      * @param int $id number of message
      * @param array $flags flags to remove from message
      *
-     * @throws RuntimeException
+     * @throws MessageUpdateException
      */
     public function removeFlags(int $id, array $flags)
     {
         if (! $this->protocol->store($flags, $id, null, '-', true)) {
-            throw new RuntimeException(
+            $message =
                 'Cannot remove flags; have you tried to set the '.
-                'recent flag or special chars?'
-            );
+                'recent flag or special chars?';
+
+            throw new MessageUpdateException($message);
         }
     }
 
     /**
      * Wrapper around the expunge command.
      *
-     * @throws RuntimeException
+     * @throws FolderUpdateException
      */
-    public function expunge()
+    public function expunge(): void
     {
         if (! $this->protocol->expunge()) {
-            throw new RuntimeException('Failed to expunge folder');
+            throw new FolderUpdateException('Failed to expunge folder');
         }
     }
 }