Version 0.2

Main changes:
- `DBUtilities`:
  - Improved methods a bit, like wrapping table names into quotes in the queries.
  - New methods: `delete_table()`, `reinit_table()`, `empty_table()`, `clone_table()`, `copy_table()`, `count_table_rows()`, and `sanitize_table_name()`. This is inspired by what BerlinDB does.

- New class `Table`: this class basically combines `TableDefinitionInterface` and `DBUtilities`, to be easier to work with.

- `CRUD` classes:
  - Renamed `get_table()` into `get_table_definition()` to prevent confusion between the classes `Table` and the interface `TableDefinitionInterface`.
  - `AbstractCRUD`: the property `table_definition` is now private. Use `get_table_definition()` in sub-classes instead.

- `AbstractTableDefinition`:
  - `get_table_name()` now uses `DBUtilities::sanitize_table_name()`.
  - New method `jsonSerialize()` (from the interface `JsonSerializable`): returns an array containing the method results. The array keys are `table_version`, `table_short_name`, `table_name`, `table_is_global`, `primary_key`, `column_placeholders`, `column_defaults`, and `table_schema`. `json_encode()` can be used directly on the class instance now.
  - New magic method `__toString()`: this will simply `json_encode()` the class.

- `TableUpgrader`:
  - Signature change: a `Table` object must be used as first argument instead of `TableDefinitionInterface`.
  - New methods `table_is_allowed_to_upgrade()` and `delete_table()`.
  - The table version is not deleted from the DB anymore if the table upgrade failed.

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "autowpdb",
 	"description": "Create and use custom database tables in WordPress.",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"homepage": "https://github.com/Screenfeed/autowpdb",
 	"license": "GPL-2.0",
 	"private": true,

phpcs.xml

@@ -24,6 +24,7 @@
 		<exclude name="Generic.Arrays.DisallowShortArraySyntax.Found"/>
 		<exclude name="WordPress.DB.DirectDatabaseQuery.DirectQuery"/>
 		<exclude name="WordPress.DB.DirectDatabaseQuery.NoCaching"/>
+		<exclude name="WordPress.DB.DirectDatabaseQuery.SchemaChange"/>
 		<exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
 		<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>
 	</rule>

phpstan.neon.dist

@@ -6,3 +6,5 @@ parameters:
     inferPrivatePropertyTypeFromConstructor: true
     paths:
         - %currentWorkingDirectory%/src/
+    ignoreErrors:
+        - '#^Function apply_filters(_ref_array)? invoked with \d parameters, \d required\.$#'

src/CRUD/AbstractCRUD.php

@@ -19,6 +19,10 @@
  * Abstract class that contains some tools to help interacting with the DB table.
  *
  * @since 0.1
+ * @uses  $GLOBALS['wpdb']
+ * @uses  esc_sql()
+ * @uses  maybe_unserialize()
+ * @uses  maybe_serialize()
  */
 abstract class AbstractCRUD implements CRUDInterface {
 
@@ -28,7 +32,7 @@ abstract class AbstractCRUD implements CRUDInterface {
 	 * @var   TableDefinitionInterface
 	 * @since 0.1
 	 */
-	protected $table;
+	private $table_definition;
 
 	/**
 	 * Stores the list of columns that must be (un)serialized.
@@ -60,27 +64,27 @@ abstract class AbstractCRUD implements CRUDInterface {
 	 *
 	 * @since 0.1
 	 *
-	 * @param TableDefinitionInterface $table A TableDefinitionInterface object.
+	 * @param TableDefinitionInterface $table_definition A TableDefinitionInterface object.
 	 */
-	public function __construct( TableDefinitionInterface $table ) {
+	public function __construct( TableDefinitionInterface $table_definition ) {
 		global $wpdb;
 
-		$this->table = $table;
+		$this->table_definition = $table_definition;
 	}
 
 	/** ----------------------------------------------------------------------------------------- */
 	/** GETTERS ================================================================================= */
 	/** ----------------------------------------------------------------------------------------- */
 
 	/**
-	 * Get the table.
+	 * Get the TableDefinitionInterface object.
 	 *
-	 * @since 0.1
+	 * @since 0.2
 	 *
 	 * @return TableDefinitionInterface
 	 */
-	public function get_table(): TableDefinitionInterface {
-		return $this->table;
+	public function get_table_definition(): TableDefinitionInterface {
+		return $this->table_definition;
 	}
 
 	/** ----------------------------------------------------------------------------------------- */
@@ -107,7 +111,7 @@ protected function prepare_select_for_query( array $select ) { // phpcs:ignore N
 			return '*';
 		}
 
-		$column_names = array_keys( $this->table->get_column_placeholders() );
+		$column_names = array_keys( $this->table_definition->get_column_placeholders() );
 		$select       = array_map( 'strtolower', $select );
 		$select       = array_intersect( $select, $column_names );
 
@@ -136,7 +140,7 @@ protected function prepare_data_for_query( array $data ): array {
 		$data = array_change_key_case( $data );
 
 		// Keep only valid columns.
-		$data = array_intersect_key( $data, $this->table->get_column_placeholders() );
+		$data = array_intersect_key( $data, $this->table_definition->get_column_placeholders() );
 
 		// Maybe serialize some values.
 		return $this->serialize_columns( $data );
@@ -154,7 +158,7 @@ protected function prepare_data_for_query( array $data ): array {
 	 * @return array<string>
 	 */
 	protected function get_placeholders( array $columns ): array {
-		$formats = $this->table->get_column_placeholders();
+		$formats = $this->table_definition->get_column_placeholders();
 		$formats = array_intersect_key( $formats, $columns );
 
 		return array_merge( $columns, $formats );
@@ -170,8 +174,8 @@ protected function get_placeholders( array $columns ): array {
 	 * @return string
 	 */
 	protected function get_placeholder( string $column ): string {
-		$columns = $this->table->get_column_placeholders();
-		return isset( $columns[ $column ] ) ? $columns[ $column ] : '%s';
+		$columns = $this->table_definition->get_column_placeholders();
+		return $columns[ $column ] ?? '%s';
 	}
 
 	/**
@@ -183,8 +187,8 @@ protected function get_placeholder( string $column ): string {
 	 * @return mixed|null     The default value. Null if the column does not exist.
 	 */
 	protected function get_default_value( string $column ) { // phpcs:ignore NeutronStandard.Functions.TypeHint.NoReturnType
-		$columns = $this->table->get_column_defaults();
-		return isset( $columns[ $column ] ) ? $columns[ $column ] : null;
+		$columns = $this->table_definition->get_column_defaults();
+		return $columns[ $column ] ?? null;
 	}
 
 	/**
@@ -276,7 +280,7 @@ protected function cast_row( $row_fields ) { // phpcs:ignore NeutronStandard.Fun
 	protected function serialize_columns( array $data ): array {
 		if ( ! isset( $this->to_serialize ) ) {
 			$this->to_serialize = array_filter(
-				$this->table->get_column_defaults(),
+				$this->table_definition->get_column_defaults(),
 				function ( $value ): bool { // phpcs:ignore NeutronStandard.Functions.TypeHint.NoArgumentType
 					return is_array( $value ) || is_object( $value );
 				}
@@ -330,7 +334,7 @@ protected function get_auto_increment_columns(): array {
 			return $this->auto_increment_columns;
 		}
 
-		$schema = $this->table->get_table_schema();
+		$schema = $this->table_definition->get_table_schema();
 
 		if ( preg_match_all( '@^\s*(?<col_name>[^\s]+)\s.+\sauto_increment,?$@mi', $schema, $matches ) ) {
 			$this->auto_increment_columns = array_fill_keys( $matches['col_name'], '' );

src/CRUD/Basic.php

@@ -39,13 +39,13 @@ public function insert( array $data ): int {
 		$data = $this->prepare_data_for_query( $data );
 
 		// Add default values to missing fields.
-		$data = array_merge( $this->serialize_columns( $this->table->get_column_defaults() ), $data );
+		$data = array_merge( $this->serialize_columns( $this->get_table_definition()->get_column_defaults() ), $data );
 
 		// Remove the auto-increment columns.
 		$data = array_diff_key( $data, $this->get_auto_increment_columns() );
 
 		$wpdb->insert(
-			$this->table->get_table_name(),
+			$this->get_table_definition()->get_table_name(),
 			$data,
 			$this->get_placeholders( $data )
 		);
@@ -69,10 +69,10 @@ public function replace( array $data ): int {
 		$data = $this->prepare_data_for_query( $data );
 
 		// Add default values to missing fields.
-		$data = array_merge( $this->serialize_columns( $this->table->get_column_defaults() ), $data );
+		$data = array_merge( $this->serialize_columns( $this->get_table_definition()->get_column_defaults() ), $data );
 
 		$wpdb->replace(
-			$this->table->get_table_name(),
+			$this->get_table_definition()->get_table_name(),
 			$data,
 			$this->get_placeholders( $data )
 		);
@@ -108,7 +108,7 @@ public function get( array $select, array $where, string $output_type = OBJECT )
 			return null;
 		}
 
-		$table = $this->table->get_table_name();
+		$table = $this->get_table_definition()->get_table_name();
 		$where = $this->prepare_data_for_query( $where );
 
 		if ( ! empty( $where ) ) {
@@ -182,7 +182,7 @@ public function update( array $data, array $where ) { // phpcs:ignore NeutronSta
 		$where = $this->prepare_data_for_query( $where );
 
 		return $wpdb->update(
-			$this->table->get_table_name(),
+			$this->get_table_definition()->get_table_name(),
 			$data,
 			$where,
 			$this->get_placeholders( $data ),
@@ -213,7 +213,7 @@ public function delete( array $where ) { // phpcs:ignore NeutronStandard.Functio
 		$where = $this->prepare_data_for_query( $where );
 
 		return $wpdb->delete(
-			$this->table->get_table_name(),
+			$this->get_table_definition()->get_table_name(),
 			$where,
 			$this->get_placeholders( $where )
 		);

src/CRUD/CRUDInterface.php

@@ -26,13 +26,13 @@ interface CRUDInterface {
 	/** ----------------------------------------------------------------------------------------- */
 
 	/**
-	 * Get the table.
+	 * Get the TableDefinitionInterface object.
 	 *
-	 * @since 0.1
+	 * @since 0.2
 	 *
 	 * @return TableDefinitionInterface
 	 */
-	public function get_table(): TableDefinitionInterface;
+	public function get_table_definition(): TableDefinitionInterface;
 
 	/** ----------------------------------------------------------------------------------------- */
 	/** CREATE ================================================================================== */