ImapProtocol: Add STATUS command support. (Webklex#424)

This library currently contains some functions
that purport to get the status of a folder, but
these are misleading because they issue the
EXAMINE command, not the STATUS command. This library
actually currently lacks support for the STATUS command,
and this command may be necessary to get some information
that the EXAMINE command will not provide.

This adds support for STATUS at the protocol level
and the folder level, and clarifies the difference
in the documentation.

Author: InterLinked1

src/Connection/Protocols/ImapProtocol.php

@@ -536,6 +536,25 @@ public function getCapabilities(): Response {
         return $response->setResult($response->validatedData()[0]);
     }
 
+	/**
+	 * Get an array of available STATUS items
+	 *
+	 * @return Response list of STATUS items
+	 *
+	 * @throws ImapBadRequestException
+	 * @throws ImapServerErrorException
+	 * @throws RuntimeException
+	 * @throws ResponseException
+	 */
+	public function getStatus(): Response {
+		$s = implode(" ", $properties);
+		$response = $this->requestAndResponse('STATUS', array($this->escapeString($folder), "(" . $s . ")"));
+
+		if (!$response->getResponse()) return $response;
+
+		return $response->setResult($response->validatedData()[0]);
+	}
+
     /**
      * Examine and select have the same response.
      * @param string $command can be 'EXAMINE' or 'SELECT'

src/Folder.php

@@ -491,8 +491,30 @@ public function idle(callable $callback, int $timeout = 300): void {
         }
     }
 
-    /**
-     * Get folder status information
+	/**
+	 * Get the standard folder status items from STATUS command
+	 *
+	 * @return array
+	 * @throws ConnectionFailedException
+	 * @throws ImapbadRequestException
+	 * @throws ImapServerErrorException
+	 * @throws RuntimeException
+	 * @throws AuthFailedException
+	 * @throws ResponseException
+	 */
+	public function getFolderStatus(string $folder, array $properties): array {
+		$status = $client->getConnection()->getStatus($folder->full_name, array('MESSAGES', 'UNSEEN', 'RECENT', 'UIDNEXT', 'UIDVALIDITY'))->validatedData();
+		$c = count($status[2]);
+		$s = array();
+		for ($i = 0; $i < $c; $i++) {
+			$a = $i++;
+			$s[$status[2][$a]] = $status[2][$i];
+		}
+		return $s;
+	}
+
+    /**
+     * Get folder status information from the EXAMINE command
      *
      * @return array
      * @throws ConnectionFailedException