ext/pdo_sqlite: EXPLAIN mode support for SQL statements.

available since 3.41.0 we can reprepare a statement in either
 explain, explain query plan or the usual prepared mode.

close phpGH-18829

Author: devnexen

NEWS

@@ -148,6 +148,9 @@ PHP                                                                        NEWS
     has a wrong return type. (David Carlier)
   . Added Pdo_Sqlite::ATTR_BUSY_STATEMENT constant to check
     if a statement is currently executing. (David Carlier)
+  . Added Pdo_Sqlite::ATTR_EXPLAIN_STATEMENT constant to set a statement
+    in either EXPLAIN_MODE_PREPARED, EXPLAIN_MODE_EXPLAIN,
+    EXPLAIN_MODE_EXPLAIN_QUERY_PLAN modes. (David Carlier)
 
 - PGSQL:
   . Added pg_close_stmt to close a prepared statement while allowing

UPGRADING

@@ -198,6 +198,9 @@ PHP 8.5 UPGRADE NOTES
 
 - PDO_Sqlite:
   . Added class constant Pdo_Sqlite::ATTR_BUSY_STATEMENT.
+  . Added class constants Pdo_Sqlite::ATTR_EXPLAIN_STATEMENT,
+    Pdo_Sqlite::EXPLAIN_MODE_PREPARED, Pdo_Sqlite::EXPLAIN_MODE_EXPLAIN,
+    Pdo_Sqlite::EXPLAIN_MODE_EXPLAIN_QUERY_PLAN.
 
 - SOAP:
   . Enumeration cases are now dumped in __getTypes().

ext/pdo_sqlite/pdo_sqlite.stub.php

@@ -36,6 +36,15 @@ class Sqlite extends \PDO
     /** @cvalue PDO_SQLITE_ATTR_BUSY_STATEMENT */
     public const int ATTR_BUSY_STATEMENT = UNKNOWN;
 
+    /** @cvalue PDO_SQLITE_ATTR_EXPLAIN_STATEMENT */
+    public const int ATTR_EXPLAIN_STATEMENT = UNKNOWN;
+
+#if SQLITE_VERSION_NUMBER >= 3041000
+    public const int EXPLAIN_MODE_PREPARED = 0;
+    public const int EXPLAIN_MODE_EXPLAIN = 1;
+    public const int EXPLAIN_MODE_EXPLAIN_QUERY_PLAN = 2;
+#endif
+
     /** @cvalue SQLITE_OK */
     public const int OK = UNKNOWN;
 

ext/pdo_sqlite/pdo_sqlite_arginfo.h

@@ -74,7 +74,8 @@ enum {
 	PDO_SQLITE_ATTR_OPEN_FLAGS = PDO_ATTR_DRIVER_SPECIFIC,
 	PDO_SQLITE_ATTR_READONLY_STATEMENT,
 	PDO_SQLITE_ATTR_EXTENDED_RESULT_CODES,
-	PDO_SQLITE_ATTR_BUSY_STATEMENT
+	PDO_SQLITE_ATTR_BUSY_STATEMENT,
+	PDO_SQLITE_ATTR_EXPLAIN_STATEMENT
 };
 
 typedef int pdo_sqlite_create_collation_callback(void*, int, const void*, int, const void*);

ext/pdo_sqlite/php_pdo_sqlite_int.h

@@ -26,6 +26,11 @@
 #include "php_pdo_sqlite.h"
 #include "php_pdo_sqlite_int.h"
 
+#if defined(__APPLE__)
+// If more than one usage, a Zend macro could be created
+// around this runtime check
+#include <Availability.h>
+#endif
 
 static int pdo_sqlite_stmt_dtor(pdo_stmt_t *stmt)
 {
@@ -387,21 +392,78 @@ static int pdo_sqlite_stmt_get_attribute(pdo_stmt_t *stmt, zend_long attr, zval
 				ZVAL_TRUE(val);
 			}
 			break;
+        case PDO_SQLITE_ATTR_EXPLAIN_STATEMENT:
+#if SQLITE_VERSION_NUMBER >= 3041000
+#if defined(__APPLE__)
+            if (__builtin_available(macOS 14.2, *)) {
+#endif
+                ZVAL_LONG(val, (zend_long)sqlite3_stmt_isexplain(S->stmt));
+                return 1;
+#if defined(__APPLE__)
+            } else {
+                zend_value_error("explain statement unsupported");
+                return 0;
+            }
+#endif
+#else
+            zend_value_error("explain statement unsupported");
+            return 0;
+#endif
 		default:
 			return 0;
 	}
 
 	return 1;
 }
 
+static int pdo_sqlite_stmt_set_attribute(pdo_stmt_t *stmt, zend_long attr, zval *zval)
+{
+	pdo_sqlite_stmt *S = (pdo_sqlite_stmt*)stmt->driver_data;
+
+	switch (attr) {
+        case PDO_SQLITE_ATTR_EXPLAIN_STATEMENT:
+#if SQLITE_VERSION_NUMBER >= 3041000
+#if defined(__APPLE__)
+            if (__builtin_available(macOS 14.2, *)) {
+#endif
+                if (Z_TYPE_P(zval) != IS_LONG) {
+                    zend_type_error("explain mode must be of type int, %s given", zend_zval_value_name(zval));
+                    return 0;
+                }
+                if (Z_LVAL_P(zval) < 0 || Z_LVAL_P(zval) > 2) {
+                    zend_value_error("explain mode must be one of the EXPLAIN_MODE_* constants");
+                    return 0;
+                }
+                if (sqlite3_stmt_explain(S->stmt, (int)Z_LVAL_P(zval)) != SQLITE_OK) {
+                    return 0;
+                }
+
+                return 1;
+#if defined(__APPLE__)
+            } else {
+                zend_value_error("explain statement unsupported");
+                return 0;
+            }
+#endif
+#else
+            zend_value_error("explain statement unsupported");
+            return 0;
+#endif
+		default:
+			return 0;
+    }
+
+    return 1;
+}
+
 const struct pdo_stmt_methods sqlite_stmt_methods = {
 	pdo_sqlite_stmt_dtor,
 	pdo_sqlite_stmt_execute,
 	pdo_sqlite_stmt_fetch,
 	pdo_sqlite_stmt_describe,
 	pdo_sqlite_stmt_get_col,
 	pdo_sqlite_stmt_param_hook,
-	NULL, /* set_attr */
+	pdo_sqlite_stmt_set_attribute, /* set_attr */
 	pdo_sqlite_stmt_get_attribute, /* get_attr */
 	pdo_sqlite_stmt_col_meta,
 	NULL, /* next_rowset */