Merge pull request #560 from barbushin/develop

Next release after 4.1.0

Author: Sebbo94BY

.php_cs.dist

@@ -1,38 +1,43 @@
 <?php
 
-return PhpCsFixer\Config::create()
-    ->setRules([
-        '@Symfony' => true,
-        '@Symfony:risky' => true,
-        'array_syntax' => [
-            'syntax' => 'short'
-        ],
-        'ordered_imports' => true,
-        'phpdoc_to_comment' => false,
-        'no_superfluous_phpdoc_tags' => true,
-        'declare_strict_types' => true,
-        'void_return' => true,
-        'ordered_class_elements' => true,
-        'global_namespace_import' => [
-            'import_classes' => true,
-            'import_constants' => true,
-            'import_functions' => false,
-        ],
-        'native_constant_invocation' => true,
-        'native_function_invocation' => true,
-        'php_unit_test_case_static_method_calls' => [
-            'call_type' => 'this',
-        ],
-        'php_unit_method_casing' => true,
-        'php_unit_dedicate_assert' => [
-            'target' => 'newest',
-        ],
-    ])
+declare(strict_types=1);
+
+$finder = PhpCsFixer\Finder::create()
+    ->in(__DIR__.'/src')
+    ->in(__DIR__.'/tests')
+    ->in(__DIR__.'/examples')
+    ->append([__FILE__]);
+
+$config = new PhpCsFixer\Config();
+$config->setRules([
+    '@Symfony' => true,
+    '@Symfony:risky' => true,
+    'array_syntax' => [
+        'syntax' => 'short',
+    ],
+    'ordered_imports' => true,
+    'phpdoc_to_comment' => false,
+    'no_superfluous_phpdoc_tags' => true,
+    'declare_strict_types' => true,
+    'void_return' => true,
+    'ordered_class_elements' => true,
+    'global_namespace_import' => [
+        'import_classes' => true,
+        'import_constants' => true,
+        'import_functions' => false,
+    ],
+    'native_constant_invocation' => true,
+    'native_function_invocation' => true,
+    'php_unit_test_case_static_method_calls' => [
+        'call_type' => 'this',
+    ],
+    'php_unit_method_casing' => true,
+    'php_unit_dedicate_assert' => [
+        'target' => 'newest',
+    ],
+])
     ->setRiskyAllowed(true)
-    ->setFinder(
-        PhpCsFixer\Finder::create()
-            ->in(__DIR__.'/src')
-            ->in(__DIR__.'/tests')
-            ->in(__DIR__.'/examples')
-    )
+    ->setFinder($finder)
 ;
+
+return $config;

README.md

@@ -30,6 +30,7 @@ Initially released in December 2012, the PHP IMAP Mailbox is a powerful and open
 | 7.2  | 3.x, 4.x |
 | 7.3  | 3.x, 4.x |
 | 7.4  | >3.0.33, 4.x |
+| 8.0  | >3.0.33, 4.x |
 
 * PHP `fileinfo` extension must be present; so make sure this line is active in your php.ini: `extension=php_fileinfo.dll`
 * PHP `iconv` extension must be present; so make sure this line is active in your php.ini: `extension=php_iconv.dll`
@@ -121,12 +122,12 @@ echo "\n\nAttachments:\n";
 print_r($mail->getAttachments());
 ```
 
-Method imap() allows to call any imap function in a context of the the instance:
+Method `imap()` allows to call any [PHP IMAP function](https://www.php.net/manual/ref.imap.php) in a context of the instance. Example:
 
 ```php
-// Call imap_check();
-// http://php.net/manual/en/function.imap-check.php
-$info = $mailbox->imap('check'); //
+// Call imap_check() - see http://php.net/manual/function.imap-check.php
+$info = $mailbox->imap('check');
+
 
 // Show current time for the mailbox
 $currentServerTime = isset($info->Date) && $info->Date ? date('Y-m-d H:i:s', strtotime($info->Date)) : 'Unknown';
@@ -156,6 +157,30 @@ foreach($folders as $folder) {
 print_r($mails_ids);
 ```
 
+### Upgrading from 3.x
+
+Prior to 3.1, `Mailbox` used a "magic" method (`Mailbox::imap()`), with the
+class `Imap` now performing it's purpose to call many `imap_*` functions with
+automated string encoding/decoding of arguments and return values:
+
+Before:
+
+```php
+    public function checkMailbox()
+    {
+        return $this->imap('check');
+    }
+```
+
+After:
+
+```php
+    public function checkMailbox(): object
+    {
+        return Imap::check($this->getImapStream());
+    }
+```
+
 ### Recommended
 
 * Google Chrome extension [PHP Console](https://chrome.google.com/webstore/detail/php-console/nfhmhhlpfleoednkpnnnkolmclajemef)

composer.json

@@ -23,7 +23,7 @@
         "sort-packages": true
     },
     "require": {
-        "php": "^7.2",
+        "php": "^7.2 || ^8.0 <8.1",
         "ext-fileinfo": "*",
         "ext-iconv": "*",
         "ext-imap": "*",
@@ -33,13 +33,14 @@
         "friendsofphp/php-cs-fixer": "^2.16",
         "jakub-onderka/php-parallel-lint": "^1.0",
         "maglnet/composer-require-checker": "^2.0",
+        "nikic/php-parser": "^4.3,<4.7",
         "paragonie/hidden-string": "^1.0",
         "phpunit/phpunit": "^8.5",
         "povils/phpmnd": "^2.2",
         "psalm/plugin-phpunit": "^0.10.0",
         "roave/security-advisories": "dev-master",
         "sebastian/phpcpd": "^4.1",
-        "vimeo/psalm": "^3.11.5"
+        "vimeo/psalm": "^3.12"
     },
     "scripts": {
         "static-analysis": [

examples/get_and_parse_all_emails_with_matching_subject.php

@@ -23,9 +23,9 @@
     try {
         $mail_ids = $mailbox->searchMailbox('SUBJECT "part of the subject"');
     } catch (ConnectionException $ex) {
-        die('IMAP connection failed: '.$ex->getMessage());
+        exit('IMAP connection failed: '.$ex->getMessage());
     } catch (Exception $ex) {
-        die('An error occured: '.$ex->getMessage());
+        exit('An error occured: '.$ex->getMessage());
     }
 
     foreach ($mail_ids as $mail_id) {

examples/get_and_parse_all_emails_without_saving_attachments.php

@@ -33,9 +33,9 @@
     try {
         $mail_ids = $mailbox->searchMailbox('UNSEEN');
     } catch (ConnectionException $ex) {
-        die('IMAP connection failed: '.$ex->getMessage());
+        exit('IMAP connection failed: '.$ex->getMessage());
     } catch (Exception $ex) {
-        die('An error occured: '.$ex->getMessage());
+        exit('An error occured: '.$ex->getMessage());
     }
 
     foreach ($mail_ids as $mail_id) {

examples/get_and_parse_unseen_emails.php

@@ -23,9 +23,9 @@
     try {
         $mail_ids = $mailbox->searchMailbox('UNSEEN');
     } catch (ConnectionException $ex) {
-        die('IMAP connection failed: '.$ex->getMessage());
+        exit('IMAP connection failed: '.$ex->getMessage());
     } catch (Exception $ex) {
-        die('An error occured: '.$ex->getMessage());
+        exit('An error occured: '.$ex->getMessage());
     }
 
     foreach ($mail_ids as $mail_id) {

examples/get_and_parse_unseen_emails_save_attachments_one_by_one.php

@@ -21,9 +21,9 @@
     try {
         $mail_ids = $mailbox->searchMailbox('UNSEEN');
     } catch (ConnectionException $ex) {
-        die('IMAP connection failed: '.$ex->getMessage());
+        exit('IMAP connection failed: '.$ex->getMessage());
     } catch (Exception $ex) {
-        die('An error occured: '.$ex->getMessage());
+        exit('An error occured: '.$ex->getMessage());
     }
 
     foreach ($mail_ids as $mail_id) {

psalm.baseline.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="3.11.5@3c60609c218d4d4b3b257728b8089094e5c6c6c2">
+<files psalm-version="3.12.2@7c7ebd068f8acaba211d4a2c707c4ba90874fa26">
   <file src="examples/get_and_parse_all_emails_without_saving_attachments.php">
     <UnusedVariable occurrences="1">
       <code>$mailbox</code>
@@ -12,25 +12,14 @@
       <code>\is_resource($maybe)</code>
     </DocblockTypeContradiction>
   </file>
-  <file src="src/PhpImap/IncomingMail.php">
-    <PossiblyUnusedMethod occurrences="1">
-      <code>replaceInternalLinks</code>
-    </PossiblyUnusedMethod>
-    <PropertyTypeCoercion occurrences="1">
-      <code>$this-&gt;dataInfo</code>
-    </PropertyTypeCoercion>
-  </file>
   <file src="src/PhpImap/Mailbox.php">
     <DocblockTypeContradiction occurrences="2">
       <code>\in_array($imapSearchOption, $supported_options, true)</code>
       <code>\in_array($key, $supported_params, true)</code>
     </DocblockTypeContradiction>
     <InvalidArgument occurrences="3">
-      <code>$element-&gt;charset</code>
       <code>$element-&gt;charset</code>
       <code>$element-&gt;text</code>
-      <code>$element-&gt;charset</code>
-      <code>$element-&gt;charset</code>
       <code>$element-&gt;text</code>
     </InvalidArgument>
     <PossiblyUnusedMethod occurrences="24">

src/PhpImap/DataPartInfo.php

@@ -107,9 +107,10 @@ protected function decodeAfterFetch(): string
 
     protected function convertEncodingAfterFetch(): string
     {
-        if (isset($this->charset) and !empty(\trim($this->charset))) {
+        if (isset($this->charset) && !empty(\trim($this->charset))) {
             $this->data = $this->mail->decodeMimeStr(
                 (string) $this->data // Data to convert
+                \trim($this->charset)
             );
         }
 

src/PhpImap/Imap.php

@@ -181,14 +181,16 @@ public static function clearflag_full(
      * @param false|resource $imap_stream
      *
      * @psalm-param value-of<self::CLOSE_FLAGS> $flag
-     * @psalm-param 0|32768 $flag
      *
      * @return true
      */
     public static function close($imap_stream, int $flag = 0): bool
     {
         \imap_errors(); // flush errors
 
+        /** @var int */
+        $flag = $flag;
+
         $result = \imap_close(self::EnsureConnection($imap_stream, __METHOD__, 1), $flag);
 
         if (false === $result) {
@@ -699,12 +701,12 @@ public static function open(
 
         \imap_errors(); // flush errors
 
-        $result = \imap_open($mailbox, $username, $password, $options, $n_retries, $params);
+        $result = @\imap_open($mailbox, $username, $password, $options, $n_retries, $params);
 
         if (!$result) {
             $lastError = \imap_last_error();
 
-            if ('' !== \trim($lastError)) {
+            if ((\is_string($lastError)) && ('' !== \trim($lastError))) {
                 throw new UnexpectedValueException('IMAP error:'.$lastError);
             }
 
@@ -890,7 +892,6 @@ public static function setflag_full(
      * @param false|resource $imap_stream
      *
      * @psalm-param value-of<self::SORT_CRITERIA> $criteria
-     * @psalm-param 1|5|0|2|6|3|4 $criteria
      *
      * @return int[]
      *
@@ -909,6 +910,9 @@ public static function sort(
         $imap_stream = self::EnsureConnection($imap_stream, __METHOD__, 1);
         $reverse = (int) $reverse;
 
+        /** @var int */
+        $criteria = $criteria;
+
         if (null !== $search_criteria && null !== $charset) {
             $result = \imap_sort(
                 $imap_stream,
@@ -935,7 +939,7 @@ public static function sort(
             );
         }
 
-        if (!$result) {
+        if (false === $result) {
             throw new UnexpectedValueException('Could not sort messages!', 0, self::HandleErrors(\imap_errors(), 'imap_sort'));
         }
 
@@ -990,7 +994,6 @@ public static function subscribe(
 
     /**
      * @psalm-param value-of<self::TIMEOUT_TYPES> $timeout_type
-     * @psalm-param 4|1|2|3 $timeout_type
      *
      * @return true|int
      */
@@ -1000,6 +1003,9 @@ public static function timeout(
     ) {
         \imap_errors(); // flush errors
 
+        /** @var int */
+        $timeout_type = $timeout_type;
+
         $result = \imap_timeout(
             $timeout_type,
             $timeout