Implement PDO driver specific sub-classes

RFC: https://wiki.php.net/rfc/pdo_driver_specific_subclasses
Co-authored-by: Máté Kocsis <kocsismate@woohoolabs.com>

Author: Danack

ext/pdo/pdo_dbh.c

@@ -221,10 +221,82 @@ static char *dsn_from_uri(char *uri, char *buf, size_t buflen) /* {{{ */
 }
 /* }}} */
 
-/* {{{ */
-PHP_METHOD(PDO, __construct)
+#define MAX_PDO_SUB_CLASSES 64
+static unsigned int number_of_pdo_driver_class_entries = 0;
+static pdo_driver_class_entry *pdo_driver_class_entries[MAX_PDO_SUB_CLASSES];
+
+// It would be possible remove this and roll it into the standard driver class entries
+// I chose not to do it at this time, as that would break existing PDO extensions
+zend_result pdo_register_driver_specific_class(pdo_driver_class_entry *driver_class_entry)
+{
+	if (number_of_pdo_driver_class_entries >= MAX_PDO_SUB_CLASSES) {
+		return FAILURE;
+	}
+
+	pdo_driver_class_entries[number_of_pdo_driver_class_entries] = driver_class_entry;
+	number_of_pdo_driver_class_entries += 1;
+
+	return SUCCESS;
+}
+
+static bool create_driver_specific_pdo_object(const char *driver_name, zend_class_entry *called_scope, zval *new_object)
+{
+	zend_class_entry *ce_based_on_driver_name = NULL, *ce_based_on_called_object = NULL;
+
+	for (int i = 0; i < number_of_pdo_driver_class_entries && (ce_based_on_driver_name == NULL || ce_based_on_called_object == NULL); i++) {
+		pdo_driver_class_entry *driver_class_entry = pdo_driver_class_entries[i];
+
+		if (strcmp(driver_class_entry->driver_name, driver_name) == 0) {
+			ce_based_on_driver_name = driver_class_entry->driver_ce;
+		}
+
+		if (called_scope != pdo_dbh_ce && instanceof_function(called_scope, driver_class_entry->driver_ce)) {
+			ce_based_on_called_object = called_scope;
+		}
+	}
+
+	if (ce_based_on_called_object) {
+		if (ce_based_on_driver_name) {
+			if (instanceof_function(ce_based_on_called_object, ce_based_on_driver_name) == false) {
+				zend_throw_exception_ex(php_pdo_get_exception(), 0,
+					"%s::connect() cannot be called when connecting to the \"%s\" driver, "
+					"you must call either %s::connect() or PDO::connect() instead",
+					ZSTR_VAL(called_scope->name), driver_name, ZSTR_VAL(ce_based_on_driver_name->name));
+				return false;
+			}
+
+			object_init_ex(new_object, ce_based_on_called_object);
+			return true;
+		} else {
+			zend_throw_exception_ex(php_pdo_get_exception(), 0,
+				"%s::connect() cannot be called when connecting to an unknown driver, "
+				"you must call PDO::connect() instead",
+				ZSTR_VAL(called_scope->name));
+			return false;
+		}
+	}
+
+	if (ce_based_on_driver_name) {
+		if (called_scope != pdo_dbh_ce) {
+			zend_throw_exception_ex(php_pdo_get_exception(), 0,
+				"%s::connect() cannot be called when connecting to the \"%s\" driver, "
+				"you must call either %s::connect() or PDO::connect() instead",
+				ZSTR_VAL(called_scope->name), driver_name, ZSTR_VAL(ce_based_on_driver_name->name));
+			return false;
+		}
+
+		// A specific driver implementation was called on PDO
+		object_init_ex(new_object, ce_based_on_driver_name);
+	} else {
+		// No specific DB implementation found
+		object_init_ex(new_object, called_scope);
+	}
+
+	return true;
+}
+
+static void internal_construct(INTERNAL_FUNCTION_PARAMETERS, zend_object *object, zend_class_entry *current_scope, zval *new_zval_object)
 {
-	zval *object = ZEND_THIS;
 	pdo_dbh_t *dbh = NULL;
 	bool is_persistent = 0;
 	char *data_source;
@@ -291,7 +363,17 @@ PHP_METHOD(PDO, __construct)
 		RETURN_THROWS();
 	}
 
-	dbh = Z_PDO_DBH_P(object);
+	if (new_zval_object != NULL) {
+		ZEND_ASSERT((driver->driver_name != NULL) && "PDO driver name is null");
+		bool result = create_driver_specific_pdo_object(driver->driver_name, current_scope, new_zval_object);
+		if (!result) {
+			RETURN_THROWS();
+		}
+
+		dbh = Z_PDO_DBH_P(new_zval_object);
+	} else {
+		dbh = php_pdo_dbh_fetch_inner(object);
+	}
 
 	/* is this supposed to be a persistent connection ? */
 	if (options) {
@@ -352,7 +434,7 @@ PHP_METHOD(PDO, __construct)
 		if (pdbh) {
 			efree(dbh);
 			/* switch over to the persistent one */
-			Z_PDO_OBJECT_P(object)->inner = pdbh;
+			php_pdo_dbh_fetch_object(object)->inner = pdbh;
 			pdbh->refcount++;
 			dbh = pdbh;
 		}
@@ -432,6 +514,19 @@ PHP_METHOD(PDO, __construct)
 		zend_throw_exception(pdo_exception_ce, "Constructor failed", 0);
 	}
 }
+
+/* {{{ */
+PHP_METHOD(PDO, __construct)
+{
+	internal_construct(INTERNAL_FUNCTION_PARAM_PASSTHRU, Z_OBJ(EX(This)), EX(This).value.ce, NULL);
+}
+/* }}} */
+
+/* {{{ */
+PHP_METHOD(PDO, connect)
+{
+	internal_construct(INTERNAL_FUNCTION_PARAM_PASSTHRU, Z_OBJ(EX(This)), EX(This).value.ce, return_value);
+}
 /* }}} */
 
 static zval *pdo_stmt_instantiate(pdo_dbh_t *dbh, zval *object, zend_class_entry *dbstmt_ce, zval *ctor_args) /* {{{ */
@@ -1334,6 +1429,8 @@ static HashTable *dbh_get_gc(zend_object *object, zval **gc_data, int *gc_count)
 }
 
 static zend_object_handlers pdo_dbh_object_handlers;
+static zend_object_handlers pdosqlite_dbh_object_handlers;
+
 static void pdo_dbh_free_storage(zend_object *std);
 
 void pdo_dbh_init(int module_number)
@@ -1349,6 +1446,13 @@ void pdo_dbh_init(int module_number)
 	pdo_dbh_object_handlers.get_method = dbh_method_get;
 	pdo_dbh_object_handlers.compare = zend_objects_not_comparable;
 	pdo_dbh_object_handlers.get_gc = dbh_get_gc;
+
+	memcpy(&pdosqlite_dbh_object_handlers, &std_object_handlers, sizeof(zend_object_handlers));
+	pdosqlite_dbh_object_handlers.offset = XtOffsetOf(pdo_dbh_object_t, std);
+	pdosqlite_dbh_object_handlers.free_obj = pdo_dbh_free_storage;
+	pdosqlite_dbh_object_handlers.get_method = dbh_method_get;
+	pdosqlite_dbh_object_handlers.compare = zend_objects_not_comparable;
+	pdosqlite_dbh_object_handlers.get_gc = dbh_get_gc;
 }
 
 static void dbh_free(pdo_dbh_t *dbh, bool free_persistent)

ext/pdo/pdo_dbh.stub.php

@@ -166,6 +166,13 @@ class PDO
 
     public function __construct(string $dsn, ?string $username = null, #[\SensitiveParameter] ?string $password = null, ?array $options = null) {}
 
+    public static function connect(
+        string $dsn,
+        ?string $username = null,
+        #[\SensitiveParameter] ?string $password = null,
+        ?array $options = null
+    ): static {}
+
     /** @tentative-return-type */
     public function beginTransaction(): bool {}
 

ext/pdo/pdo_dbh_arginfo.h

@@ -19,9 +19,12 @@
 
 #include "zend.h"
 
-extern zend_module_entry pdo_module_entry;
+PHPAPI extern zend_module_entry pdo_module_entry;
 #define phpext_pdo_ptr &pdo_module_entry
 
+PHPAPI extern zend_class_entry *pdo_dbh_ce;
+PHPAPI extern zend_object *pdo_dbh_new(zend_class_entry *ce);
+
 #include "php_version.h"
 #define PHP_PDO_VERSION PHP_VERSION
 
@@ -50,9 +53,6 @@ PHP_MINFO_FUNCTION(pdo);
 #define REGISTER_PDO_CLASS_CONST_LONG(const_name, value) \
 	zend_declare_class_constant_long(php_pdo_get_dbh_ce(), const_name, sizeof(const_name)-1, (zend_long)value);
 
-#define REGISTER_PDO_CLASS_CONST_STRING(const_name, value) \
-	zend_declare_class_constant_stringl(php_pdo_get_dbh_ce(), const_name, sizeof(const_name)-1, value, sizeof(value)-1);
-
 #define LONG_CONST(c) (zend_long) c
 
 #define PDO_CONSTRUCT_CHECK \

ext/pdo/php_pdo.h

@@ -215,6 +215,16 @@ typedef struct {
 
 } pdo_driver_t;
 
+// NOTE - This separate struct, could be rolled it into pdo_driver_t
+// I chose not to, as that would cause BC break and require a lot of
+// downstream work.
+typedef struct {
+	char *driver_name;
+	zend_class_entry *driver_ce;
+} pdo_driver_class_entry;
+
+PHPAPI zend_result pdo_register_driver_specific_class(pdo_driver_class_entry *driver_class_entry);
+
 /* {{{ methods for a database handle */
 
 /* close or otherwise disconnect the database */

ext/pdo/php_pdo_driver.h

@@ -28,9 +28,7 @@ int php_pdo_list_entry(void);
 void pdo_dbh_init(int module_number);
 void pdo_stmt_init(void);
 
-extern zend_object *pdo_dbh_new(zend_class_entry *ce);
 extern const zend_function_entry pdo_dbh_functions[];
-extern zend_class_entry *pdo_dbh_ce;
 extern ZEND_RSRC_DTOR_FUNC(php_pdo_pdbh_dtor);
 
 extern zend_object *pdo_dbstmt_new(zend_class_entry *ce);

ext/pdo/php_pdo_int.h

@@ -54,12 +54,12 @@ class PDOTest {
         }
     }
 
-    static function test_factory($file) {
+    static function test_factory($file, $classname = 'PDO') {
         $config = self::get_config($file);
         foreach ($config['ENV'] as $k => $v) {
             putenv("$k=$v");
         }
-        return self::factory();
+        return self::factory($classname);
     }
 
     static function get_config($file) {

ext/pdo/tests/pdo_test.inc

@@ -27,10 +27,14 @@
 #include "php_pdo_dblib.h"
 #include "php_pdo_dblib_int.h"
 #include "zend_exceptions.h"
+#include "pdo_dblib_arginfo.h"
 
 ZEND_DECLARE_MODULE_GLOBALS(dblib)
 static PHP_GINIT_FUNCTION(dblib);
 
+zend_class_entry *PdoDblib_ce;
+static pdo_driver_class_entry PdoDblib_pdo_driver_class_entry;
+
 static const zend_module_dep pdo_dblib_deps[] = {
 	ZEND_MOD_REQUIRED("pdo")
 	ZEND_MOD_END
@@ -201,6 +205,13 @@ PHP_MINIT_FUNCTION(pdo_dblib)
 		return FAILURE;
 	}
 
+	PdoDblib_ce = register_class_PdoDblib(pdo_dbh_ce);
+	PdoDblib_ce->create_object = pdo_dbh_new;
+
+	PdoDblib_pdo_driver_class_entry.driver_name = "dblib";
+	PdoDblib_pdo_driver_class_entry.driver_ce = PdoDblib_ce;
+	pdo_register_driver_specific_class(&PdoDblib_pdo_driver_class_entry);
+
 	if (FAILURE == php_pdo_register_driver(&pdo_dblib_driver)) {
 		return FAILURE;
 	}

ext/pdo_dblib/pdo_dblib.c

@@ -0,0 +1,31 @@
+<?php
+
+/** @generate-class-entries */
+
+/**
+ * @strict-properties
+ * @not-serializable
+ */
+class PdoDblib extends PDO
+{
+    /** @cvalue PDO_DBLIB_ATTR_CONNECTION_TIMEOUT */
+    public const int ATTR_CONNECTION_TIMEOUT = UNKNOWN;
+
+    /** @cvalue PDO_DBLIB_ATTR_QUERY_TIMEOUT */
+    public const int ATTR_QUERY_TIMEOUT = UNKNOWN;
+
+    /** @cvalue PDO_DBLIB_ATTR_STRINGIFY_UNIQUEIDENTIFIER */
+    public const int ATTR_STRINGIFY_UNIQUEIDENTIFIER = UNKNOWN;
+
+    /** @cvalue PDO_DBLIB_ATTR_VERSION */
+    public const int ATTR_VERSION = UNKNOWN;
+
+    /** @cvalue PDO_DBLIB_ATTR_TDS_VERSION */
+    public const int ATTR_TDS_VERSION = UNKNOWN;
+
+    /** @cvalue PDO_DBLIB_ATTR_SKIP_EMPTY_ROWSETS */
+    public const int ATTR_SKIP_EMPTY_ROWSETS = UNKNOWN;
+
+    /** @cvalue PDO_DBLIB_ATTR_DATETIME_CONVERT */
+    public const int ATTR_DATETIME_CONVERT = UNKNOWN;
+}