Add a new imap_is_open() function to check that a connection object is still valid

NEWS

@@ -24,6 +24,10 @@ PHP                                                                        NEWS
   . Fixed bug GH-8517 (Random crash of FPM master process in
     fpm_stdio_child_said). (Jakub Zelenka)
 
+- Imap:
+  . Fixed bug GH-10051 (IMAP: there's no way to check if a IMAP\Connection is
+    still open). (Girgias)
+
 - MBString:
   . Fixed bug GH-9535 (The behavior of mb_strcut in mbstring has been changed in
     PHP8.1). (Nathan Freeman)

UPGRADING

@@ -234,6 +234,9 @@ PHP 8.2 UPGRADE NOTES
 - Curl:
   . curl_upkeep() (libcurl >= 7.62.0)
 
+- IMAP:
+  . imap_is_open() (Only as of PHP 8.2.1)
+
 - mysqli:
   . mysqli_execute_query()
 

ext/imap/php_imap.c

@@ -781,6 +781,24 @@ PHP_FUNCTION(imap_reopen)
 }
 /* }}} */
 
+PHP_FUNCTION(imap_is_open)
+{
+	zval *imap_conn_obj;
+	php_imap_object *imap_conn_struct;
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS(), "O", &imap_conn_obj, php_imap_ce) == FAILURE) {
+		RETURN_THROWS();
+	}
+
+	/* Manual reimplementation of the GET_IMAP_STREAM() macro that doesn't throw */
+	imap_conn_struct = imap_object_from_zend_object(Z_OBJ_P(imap_conn_obj));
+	/* Stream was closed */
+	if (imap_conn_struct->imap_stream == NULL) {
+		RETURN_FALSE;
+	}
+	RETURN_TRUE;
+}
+
 /* {{{ Append a new message to a specified mailbox */
 PHP_FUNCTION(imap_append)
 {

ext/imap/php_imap.stub.php

@@ -411,6 +411,8 @@ namespace {
 
     function imap_close(IMAP\Connection $imap, int $flags = 0): bool {}
 
+    function imap_is_open(IMAP\Connection $imap): bool {}
+
     function imap_num_msg(IMAP\Connection $imap): int|false {}
 
     function imap_num_recent(IMAP\Connection $imap): int {}

ext/imap/php_imap_arginfo.h

@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: c1f54f259bde2c49c5b49a595751acd2fb365efe */
+ * Stub hash: c7ef736ea5c4121a4694c24af33fa1672f502c25 */
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_imap_open, 0, 3, IMAP\\Connection, MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(0, mailbox, IS_STRING, 0)
@@ -22,6 +22,10 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_imap_close, 0, 1, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, flags, IS_LONG, 0, "0")
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_imap_is_open, 0, 1, _IS_BOOL, 0)
+	ZEND_ARG_OBJ_INFO(0, imap, IMAP\\Connection, 0)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_imap_num_msg, 0, 1, MAY_BE_LONG|MAY_BE_FALSE)
 	ZEND_ARG_OBJ_INFO(0, imap, IMAP\\Connection, 0)
 ZEND_END_ARG_INFO()
@@ -101,9 +105,7 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_imap_gc, 0, 2, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO(0, flags, IS_LONG, 0)
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_imap_expunge, 0, 1, _IS_BOOL, 0)
-	ZEND_ARG_OBJ_INFO(0, imap, IMAP\\Connection, 0)
-ZEND_END_ARG_INFO()
+#define arginfo_imap_expunge arginfo_imap_is_open
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_imap_delete, 0, 2, _IS_BOOL, 0)
 	ZEND_ARG_OBJ_INFO(0, imap, IMAP\\Connection, 0)
@@ -171,7 +173,7 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_imap_append, 0, 3, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, internal_date, IS_STRING, 1, "null")
 ZEND_END_ARG_INFO()
 
-#define arginfo_imap_ping arginfo_imap_expunge
+#define arginfo_imap_ping arginfo_imap_is_open
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_imap_base64, 0, 1, MAY_BE_STRING|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(0, string, IS_STRING, 0)
@@ -341,6 +343,7 @@ ZEND_END_ARG_INFO()
 ZEND_FUNCTION(imap_open);
 ZEND_FUNCTION(imap_reopen);
 ZEND_FUNCTION(imap_close);
+ZEND_FUNCTION(imap_is_open);
 ZEND_FUNCTION(imap_num_msg);
 ZEND_FUNCTION(imap_num_recent);
 ZEND_FUNCTION(imap_headers);
@@ -425,6 +428,7 @@ static const zend_function_entry ext_functions[] = {
 	ZEND_FE(imap_open, arginfo_imap_open)
 	ZEND_FE(imap_reopen, arginfo_imap_reopen)
 	ZEND_FE(imap_close, arginfo_imap_close)
+	ZEND_FE(imap_is_open, arginfo_imap_is_open)
 	ZEND_FE(imap_num_msg, arginfo_imap_num_msg)
 	ZEND_FE(imap_num_recent, arginfo_imap_num_recent)
 	ZEND_FE(imap_headers, arginfo_imap_headers)

ext/imap/tests/imap_is_open.phpt

@@ -0,0 +1,37 @@
+--TEST--
+Test imap_is_open()
+--EXTENSIONS--
+imap
+--SKIPIF--
+<?php
+require_once(__DIR__.'/setup/skipif.inc');
+?>
+--FILE--
+<?php
+
+// include file for required variables in imap_open()
+require_once(__DIR__.'/setup/imap_include.inc');
+
+$mailbox_suffix = 'imapisopen';
+
+// set up temp mailbox with 0 messages
+$stream_id = setup_test_mailbox($mailbox_suffix, 0, $mailbox);
+
+var_dump(imap_is_open($stream_id));
+
+// Close connection
+var_dump(imap_close($stream_id));
+var_dump(imap_is_open($stream_id));
+
+?>
+--CLEAN--
+<?php
+$mailbox_suffix = 'imapisopen';
+require_once(__DIR__.'/setup/clean.inc');
+?>
+--EXPECT--
+Create a temporary mailbox and add 0 msgs
+New mailbox created
+bool(true)
+bool(true)
+bool(false)