Refine the 3.0 API surface

packages/mysql-on-sqlite/src/load.php

@@ -36,10 +36,10 @@
 require_once __DIR__ . '/sqlite/class-wp-sqlite-connection.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-configurator.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-driver.php';
-require_once __DIR__ . '/sqlite/class-wp-sqlite-driver-exception.php';
+require_once __DIR__ . '/sqlite/class-wp-mysql-on-sqlite-exception.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-information-schema-builder.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-information-schema-exception.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-information-schema-reconstructor.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-pdo-user-defined-functions.php';
 require_once __DIR__ . '/sqlite/class-wp-mysql-on-sqlite.php';
-require_once __DIR__ . '/sqlite/class-wp-pdo-proxy-statement.php';
+require_once __DIR__ . '/sqlite/class-wp-mysql-on-sqlite-statement.php';

packages/mysql-on-sqlite/src/mysql/class-wp-mysql-lexer.php

@@ -16,6 +16,8 @@
  *   https://github.com/mysql/mysql-workbench/blob/8.0.38/library/parsers/grammars/MySQLLexer.g4
  *   https://github.com/mysql/mysql-workbench/blob/8.0.38/library/parsers/grammars/predefined.tokens
  *   https://github.com/mysql/mysql-workbench/blob/8.0.38/library/parsers/mysql/MySQLBaseLexer.cpp
+ *
+ * @access private
  */
 class WP_MySQL_Lexer {
 	/**

packages/mysql-on-sqlite/src/mysql/class-wp-mysql-parser.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * MySQL parser used by the SQLite driver.
+ *
+ * @access private
+ */
 class WP_MySQL_Parser extends WP_Parser {
 	/**
 	 * The current query AST.

packages/mysql-on-sqlite/src/mysql/class-wp-mysql-token.php

@@ -5,6 +5,8 @@
  *
  * This class represents a MySQL SQL token that is produced by WP_MySQL_Lexer,
  * and consumed by WP_MySQL_Parser during the parsing process.
+ *
+ * @access private
  */
 class WP_MySQL_Token extends WP_Parser_Token {
 	/**

packages/mysql-on-sqlite/src/mysql/native/class-wp-mysql-lexer.php

@@ -1,3 +1,8 @@
 <?php
 
+/**
+ * Native lexer facade used by the SQLite driver.
+ *
+ * @access private
+ */
 class WP_MySQL_Lexer extends WP_MySQL_Native_Lexer {}

packages/mysql-on-sqlite/src/mysql/native/class-wp-mysql-native-parser-node.php

@@ -8,6 +8,8 @@
  * caller actually walks the tree. On the first mutation (append_child or
  * merge_fragment), the node materializes its children into the inherited
  * `$children` array and behaves like a plain WP_Parser_Node from then on.
+ *
+ * @access private
  */
 class WP_MySQL_Native_Parser_Node extends WP_Parser_Node {
 	private $was_mutated = false;

packages/mysql-on-sqlite/src/mysql/native/class-wp-mysql-parser.php

@@ -8,6 +8,8 @@
  * loaded. The actual parsing work is delegated to a composed
  * `WP_MySQL_Native_Parser` instance via the `WP_MySQL_Native_Parser_Impl`
  * trait — see that file for the per-method delegation.
+ *
+ * @access private
  */
 class WP_MySQL_Parser extends WP_Parser {
 	use WP_MySQL_Native_Parser_Impl;

packages/mysql-on-sqlite/src/mysql/native/mysql-rust-bridge.php

@@ -8,6 +8,8 @@
 /**
  * Export grammar internals for the native parser.
  *
+ * @access private
+ *
  * @param WP_Parser_Grammar $grammar Parser grammar.
  * @return array<string, mixed>
  */

packages/mysql-on-sqlite/src/mysql/native/trait-wp-mysql-native-parser-impl.php

@@ -13,6 +13,8 @@
  *
  * Adding a public method here is enough to plumb a new public method
  * through to the native parser; the using class does not need touching.
+ *
+ * @access private
  */
 trait WP_MySQL_Native_Parser_Impl {
 	/**

packages/mysql-on-sqlite/src/parser/class-wp-parser-grammar.php

@@ -8,6 +8,8 @@
  * representation, and precomputes a lookup table for quick branch selection.
  *
  * @TODO: Add more details about the grammar implementation.
+ *
+ * @access private
  */
 class WP_Parser_Grammar {
 	/**

packages/mysql-on-sqlite/src/parser/class-wp-parser-node.php

@@ -8,6 +8,8 @@
  * Each node can contain children, consisting of other nodes and grammar tokens.
  * In this way, a parser node constitutes a recursive structure that represents
  * a parse (sub)tree at each level of the full grammar tree.
+ *
+ * @access private
  */
 class WP_Parser_Node {
 	/**

packages/mysql-on-sqlite/src/parser/class-wp-parser-token.php

@@ -7,6 +7,8 @@
  * In a parse tree, a token represent a leaf, that is, a node without children.
  * It is a simple generic container for a token ID and value, that can be used
  * as a base class and extended for specific use cases.
+ *
+ * @access private
  */
 class WP_Parser_Token {
 	/**

packages/mysql-on-sqlite/src/parser/class-wp-parser.php

@@ -7,6 +7,8 @@
  *
  * @TODO: Add a detailed description and list the properties that a grammar must
  *        satisfy in order to be supported by this parser (e.g., no left recursion).
+ *
+ * @access private
  */
 class WP_Parser {
 	protected $grammar;

packages/mysql-on-sqlite/src/sqlite/class-wp-sqlite-driver-exception.php → packages/mysql-on-sqlite/src/sqlite/class-wp-mysql-on-sqlite-exception.php

@@ -1,8 +1,8 @@
 <?php
 
-class WP_SQLite_Driver_Exception extends PDOException {
+class WP_MySQL_On_SQLite_Exception extends PDOException {
 	/**
-	 * The SQLite driver that originated the exception.
+	 * The MySQL-on-SQLite driver that originated the exception.
 	 *
 	 * @var WP_MySQL_On_SQLite
 	 */
@@ -11,7 +11,7 @@ class WP_SQLite_Driver_Exception extends PDOException {
 	/**
 	 * Constructor.
 	 *
-	 * @param WP_MySQL_On_SQLite $driver The SQLite driver that originated the exception.
+	 * @param WP_MySQL_On_SQLite $driver   The MySQL-on-SQLite driver that originated the exception.
 	 * @param string                 $message  The exception message.
 	 * @param int|string             $code     The exception code. In PDO, it can be a string with value of SQLSTATE.
 	 * @param Throwable|null         $previous The previous throwable used for the exception chaining.
@@ -27,7 +27,7 @@ public function __construct(
 		$this->driver = $driver;
 	}
 
-	public function getDriver(): WP_MySQL_On_SQLite {
+	public function get_driver(): WP_MySQL_On_SQLite {
 		return $this->driver;
 	}
 }

packages/mysql-on-sqlite/src/sqlite/class-wp-pdo-proxy-statement.php → packages/mysql-on-sqlite/src/sqlite/class-wp-mysql-on-sqlite-statement.php

@@ -26,7 +26,12 @@
  * we conditionally define traits with different APIs based on the PHP version.
  */
 if ( PHP_VERSION_ID < 80000 ) {
-	trait WP_PDO_Proxy_Statement_PHP_Compat {
+	/**
+	 * PHP compatibility methods for WP_MySQL_On_SQLite_Statement.
+	 *
+	 * @access private
+	 */
+	trait WP_MySQL_On_SQLite_Statement_PHP_Compat {
 		/**
 		 * Set the default fetch mode for this statement.
 		 *
@@ -61,7 +66,12 @@ public function fetchAll( $mode = null, $class_name = null, $constructor_args =
 		}
 	}
 } else {
-	trait WP_PDO_Proxy_Statement_PHP_Compat {
+	/**
+	 * PHP compatibility methods for WP_MySQL_On_SQLite_Statement.
+	 *
+	 * @access private
+	 */
+	trait WP_MySQL_On_SQLite_Statement_PHP_Compat {
 		/**
 		 * Set the default fetch mode for this statement.
 		 *
@@ -88,10 +98,10 @@ public function fetchAll( $mode = PDO::FETCH_DEFAULT, ...$args ): array {
 }
 
 /**
- * PDOStatement implementation that operates on in-memory data.
+ * PDOStatement implementation for MySQL-on-SQLite query results.
  *
- * This class implements a complete PDOStatement interface on top of PHP arrays.
- * It is used for result sets that are composed or transformed in the PHP layer.
+ * Delegates operations to the underlying SQLite statement while adapting
+ * MySQL-specific behavior such as affected row counts.
  *
  * PDO supports the following fetch modes:
  *   - PDO::FETCH_DEFAULT:  current default fetch mode (available from PHP 8.0)
@@ -108,8 +118,8 @@ public function fetchAll( $mode = PDO::FETCH_DEFAULT, ...$args ): array {
  *   - PDO::FETCH_BOUND:    bind values to PHP variables, can't be used with fetchAll()
  *   - PDO::FETCH_FUNC:     custom function, only works with fetchAll(), can't be default [1 extra arg]
  */
-class WP_PDO_Proxy_Statement extends PDOStatement {
-	use WP_PDO_Proxy_Statement_PHP_Compat;
+class WP_MySQL_On_SQLite_Statement extends PDOStatement {
+	use WP_MySQL_On_SQLite_Statement_PHP_Compat;
 
 	/**
 	 * The original PDO statement.
@@ -347,7 +357,7 @@ public function debugDumpParams(): ?bool {
 	/**
 	 * Fetch all remaining rows from the result set.
 	 *
-	 * This is used internally by the "WP_PDO_Proxy_Statement_PHP_Compat" trait,
+	 * This is used internally by the "WP_MySQL_On_SQLite_Statement_PHP_Compat" trait,
 	 * that is defined conditionally based on the current PHP version.
 	 *
 	 * @param  int   $mode The fetch mode to use.
@@ -361,7 +371,7 @@ private function fetchAllRows( $mode = null, ...$args ): array {
 	/**
 	 * Set the default fetch mode for this statement.
 	 *
-	 * This is used internally by the "WP_PDO_Proxy_Statement_PHP_Compat" trait,
+	 * This is used internally by the "WP_MySQL_On_SQLite_Statement_PHP_Compat" trait,
 	 * that is defined conditionally based on the current PHP version.
 	 *
 	 * @param  int   $mode   The fetch mode to set as the default.