ext/pgsql: introducing pg_result_verbose_error().

unlike pg_set_error_context_visibility()/pg_set_error_verbosity(), it is
affecting only a particular PgSql\Result instance rather than the whole
PgSql\Connection, e.g. debugging a problematic SQL request.
Available since postgresql 14.

Author: devnexen

ext/pgsql/config.m4

@@ -31,6 +31,9 @@ if test "$PHP_PGSQL" != "no"; then
   PHP_CHECK_LIBRARY([pq], [PQclosePrepared],
     [AC_DEFINE([HAVE_PG_CLOSE_STMT], [1], [PostgreSQL 17 or later])],,
     [$PGSQL_LIBS])
+  PHP_CHECK_LIBRARY([pq], [PQresultVerboseErrorMessage],
+    [AC_DEFINE([HAVE_PG_RESULT_VERBOSE_ERROR_MESSAGE], [1], [PostgreSQL 14 or later])],,
+    [$PGSQL_LIBS])
 
   old_CFLAGS=$CFLAGS
   CFLAGS="$CFLAGS $PGSQL_CFLAGS"

ext/pgsql/pgsql.c

@@ -6347,3 +6347,39 @@ PHP_FUNCTION(pg_close_stmt)
 	}
 }
 #endif
+
+#if defined(HAVE_PG_RESULT_VERBOSE_ERROR_MESSAGE)
+PHP_FUNCTION(pg_result_verbose_error)
+{
+	zval *result;
+	pgsql_result_handle *pg_result;
+	zend_long verbosity, visibility;
+	char *err = NULL;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_OBJECT_OF_CLASS(result, pgsql_result_ce)
+		Z_PARAM_LONG(verbosity)
+		Z_PARAM_LONG(visibility)
+	ZEND_PARSE_PARAMETERS_END();
+
+	if (!(verbosity & (PQERRORS_TERSE|PQERRORS_DEFAULT|PQERRORS_VERBOSE|PQERRORS_SQLSTATE))) {
+		zend_argument_value_error(2, "verbosity must be one of the PQERRORS_* constants");
+		RETURN_THROWS();
+	}
+	if (visibility < PQSHOW_CONTEXT_NEVER || !(visibility & (PQSHOW_CONTEXT_ERRORS|PQSHOW_CONTEXT_ALWAYS))) {
+		zend_argument_value_error(3, "visibility must be one of the PQSHOW_CONTEXT_* constants");
+		RETURN_THROWS();
+	}
+
+	pg_result = Z_PGSQL_RESULT_P(result);
+	CHECK_PGSQL_RESULT(pg_result);
+
+	err = PQresultVerboseErrorMessage(pg_result->result, verbosity, visibility);
+	if (UNEXPECTED(!err)) {
+		RETURN_FALSE;
+	} else {
+		RETVAL_STRING(err);
+		PQfreemem(err);
+	}
+}
+#endif

ext/pgsql/pgsql.stub.php

@@ -973,6 +973,10 @@ function pg_set_chunked_rows_size(PgSql\Connection $connection, int $size): bool
 #ifdef HAVE_PG_CLOSE_STMT
     function pg_close_stmt(Pgsql\Connection $connection, string $statement_name): Pgsql\Result|false {}
 #endif
+#ifdef HAVE_PG_RESULT_ERROR_MESSAGE
+    /** @refcount 1 */
+    function pg_result_verbose_error(PgSql\Result $result, int $verbosity, int $visibility): string|false {}
+#endif
 }
 
 namespace PgSql {