Branch 0.3 (#2)

## Tests

Unit and integration tests have been added, they cover 100% of the current code.
Sadly, we're stuck with PHPUNIT 7.5.20 because of WP’s test suite 😢.

## AbstractCRUD

- `prepare_select_for_query()`:
  - Trim quotes.
  - Add backticks.
  - Remove empty fields.
  - Don't use `esc_sql()` anymore.
- `get_placeholders()`:
  - Return only valid columns.
- `cast()`:
  - When the placeholder is not `%d` nor `%f` and the column is not serializable, return numeric values as string.

## Basic

- `get()`:
  - Disallowed `ARRAY_N` value for the output type, as it conflicts with `cast_row()`.

## AbstractTableDefinition

- An instance of `Worker` can be injected into the constructor.

## DBUtilities / DBWorker\Worker

- The static class `DBUtilities` is now the instanciable class `DBWorker\Worker` that implements `DBWorker\WorkerInterface`.
Seeing how `DBUtilities` was used at this point, using a static class was not shorter. The advantage now is that the instance can be typehinted against the interface. Although, it is not typehinted directly in `AbstractTableDefinition` today, we need php 7.1 for nullable typehints (this is for a future release), but `instanceof` is used for the time being.
The full instanciation is now `new Table( new MyTableDefinition( new MyWorker() ) )`.
`AbstractTableDefinition` falls back to `new DBWorker\Worker()` if no custom worker is specified as argument.
- Hide database errors in most methods.
- `table_exists()`:
  - Fix returned value by comparing the query value to the unescaped name of the table.
- New method `get_last_error()`, which returns the last `$wpdb` error.
- `sanitize_table_name()`:
  - Allow `0` as a valid table name.
- `quote_string()`:
  - Do not escape simple quotes anymore, it is done by `esc_sql()` in `prepare_values_list()`.
- `can_log()`:
  - New filter `screenfeed_autowpdb_can_log`.

## Table

- New method `get_last_error()`, which returns the last DB error.
- `clone_to()`:
  - Allow `0` as a valid table name.

## TableUpgrader

- Use `static` instead of `self`, so the class can be extended and tested.
- `init()`:
  - Move tests from the constructor to the `init()` method.
  - Don't add the upgrade hook if the hook name is set to `false`.
- `table_is_up_to_date()`:
  - Fix when downgrade is handled, it was returning the opposite of the expected value.

Author: Screenfeed

.gitignore

@@ -1,4 +1,5 @@
 # Directories
+/.vscode
 /report
 /vendor
 

.markdownlint.json

@@ -0,0 +1,5 @@
+{
+	"ul-indent": { "indent": 4 },
+	"line-length": false,
+	"no-hard-tabs": false
+}

README.md

@@ -18,17 +18,35 @@ Requires **php 7.0** and **WordPress 4.9.6**. With php 7.1+, can be used with Wo
 
 With composer:
 
-```
+```json
 "require": {
 	"screenfeed/autowpdb": "dev-master"
 },
 ```
 
 ## How to use
 
-Create 2 classes and you’re ready:
+Create 1 or 2 classes and you're ready:
 
 * One that "defines" your custom table (name, default values, value types, schema, etc) by extending *TableDefinition\AbstractTableDefinition*,
-* One containing your CRUD methods (optional) by extending *CRUD\Basic*.
+* Optionally, one containing your CRUD methods by extending *CRUD\Basic*.
+
+Example:
+
+```php
+use Screenfeed\AutoWPDB\Table;
+use Screenfeed\AutoWPDB\TableUpgrader;
+
+add_action( 'plugins_loaded', 'my_plugin_init' );
+
+function my_plugin_init() {
+	// Your class defining your custom DB table.
+	$table_def = new MyCustomTableDefinition();
+
+	// The upgrader: it will upgrade your DB table automatically if the schema changes.
+	$upgrader = new TableUpgrader( new Table( $table_def ) );
+	$upgrader->init();
+}
+```
 
 Please take a look at [this plugin](https://github.com/Screenfeed/autowpdb-example-plugin) to see an example of use.

Tests/Fixtures/WordPress/wp-admin/includes/upgrade.php

@@ -0,0 +1 @@
+<?php

Tests/Fixtures/src/CRUD/CustomCRUD.php

@@ -0,0 +1,27 @@
+<?php
+namespace Screenfeed\AutoWPDB\Tests\Fixtures\src\CRUD;
+
+use Screenfeed\AutoWPDB\CRUD\AbstractCRUD;
+
+class CustomCRUD extends AbstractCRUD {
+
+	public function insert( array $data ): int {
+		return 0;
+	}
+
+	public function replace( array $data ): int {
+		return 0;
+	}
+
+	public function get( array $select, array $where, string $output_type = OBJECT ) {
+		return null;
+	}
+
+	public function update( array $data, array $where ) {
+		return false;
+	}
+
+	public function delete( array $where ) {
+		return false;
+	}
+}

Tests/Fixtures/src/DBWorker/Worker/WorkerIntegration.php

@@ -0,0 +1,22 @@
+<?php
+namespace Screenfeed\AutoWPDB\Tests\Fixtures\src\DBWorker\Worker;
+
+use Screenfeed\AutoWPDB\DBWorker\Worker;
+
+/**
+ * Allows to perform some Integration tests for Worker->create_table() and Worker->delete_table().
+ * During the integration tests, WP only allows to create temporary tables, which won't be listed in 'SHOW TABLES'.
+ *
+ * @source https://wordpress.stackexchange.com/questions/220275/wordpress-unit-testing-cannot-create-tables
+ */
+class WorkerIntegration extends Worker {
+
+	public function table_exists( string $table_name ): bool {
+		global $wpdb;
+
+		$query = "SELECT * FROM `$table_name` LIMIT 1";
+		$wpdb->get_results( $query ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
+
+		return "Table '{$wpdb->dbname}.$table_name' doesn't exist" !== $wpdb->last_error;
+	}
+}

Tests/Fixtures/src/Table/CustomTable.php

@@ -0,0 +1,120 @@
+<?php
+namespace Screenfeed\AutoWPDB\Tests\Fixtures\src\Table;
+
+use Screenfeed\AutoWPDB\TableDefinition\AbstractTableDefinition;
+
+/**
+ * Class that defines our custom table.
+ *
+ * @since 0.3
+ */
+class CustomTable extends AbstractTableDefinition {
+	protected $table_version;
+	protected $schema;
+	protected $short_name;
+	protected $table_is_global;
+
+	protected $default_table_version = 102;
+	protected $default_schema = "
+	file_id bigint(20) unsigned NOT NULL auto_increment,
+	file_date datetime NOT NULL default '0000-00-00 00:00:00',
+	path varchar(191) NOT NULL default '',
+	mime_type varchar(100) NOT NULL default '',
+	modified tinyint(1) unsigned NOT NULL default 0,
+	width smallint(2) unsigned NOT NULL default 0,
+	height smallint(2) unsigned NOT NULL default 0,
+	file_size int(4) unsigned NOT NULL default 0,
+	status varchar(20) default NULL,
+	error varchar(255) default NULL,
+	data longtext default NULL,
+	PRIMARY KEY  (file_id),
+	UNIQUE KEY path (path),
+	KEY status (status),
+	KEY modified (modified)";
+	protected $default_short_name = 'foobar';
+	protected $default_table_is_global = true;
+
+	public function get_table_version(): int {
+		if ( ! isset( $this->table_version ) ) {
+			$this->table_version = $this->default_table_version;
+		}
+		return $this->table_version;
+	}
+
+	public function get_table_short_name(): string {
+		if ( ! isset( $this->short_name ) ) {
+			$this->short_name = $this->default_short_name;
+		}
+		return $this->short_name;
+	}
+
+	public function is_table_global(): bool {
+		if ( ! isset( $this->table_is_global ) ) {
+			$this->table_is_global = $this->default_table_is_global;
+		}
+		return $this->table_is_global;
+	}
+
+	public function get_primary_key(): string {
+		return 'file_id';
+	}
+
+	public function get_column_placeholders(): array {
+		return [
+			'file_id'   => '%d',
+			'file_date' => '%s',
+			'path'      => '%s',
+			'mime_type' => '%s',
+			'modified'  => '%d',
+			'width'     => '%d',
+			'height'    => '%d',
+			'file_size' => '%d',
+			'status'    => '%s',
+			'error'     => '%s',
+			'data'      => '%s',
+		];
+	}
+
+	public function get_column_defaults(): array {
+		return [
+			'file_id'   => 0,
+			'file_date' => '0000-00-00 00:00:00',
+			'path'      => '',
+			'mime_type' => '',
+			'modified'  => 0,
+			'width'     => 0,
+			'height'    => 0,
+			'file_size' => 0,
+			'status'    => null,
+			'error'     => null,
+			'data'      => [],
+		];
+	}
+
+	public function get_table_schema(): string {
+		if ( ! isset( $this->schema ) ) {
+			$this->schema = $this->default_schema;
+		}
+		return $this->schema;
+	}
+
+	/** ----------------------------------------------------------------------------------------- */
+	/** SETTERS ================================================================================= */
+	/** ----------------------------------------------------------------------------------------- */
+
+	public function set_table_version( $table_version ) {
+		$this->table_version = $table_version;
+	}
+
+	public function set_table_short_name( $short_name ) {
+		$this->short_name = $short_name;
+	}
+
+	public function set_table_schema( $schema ) {
+		$this->schema = $schema;
+	}
+
+	public function set_table_is_global( $table_is_global ) {
+		$this->table_is_global = $table_is_global;
+	}
+}

Tests/Integration/TemporaryTableTrait.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Screenfeed\AutoWPDB\Tests\Integration;
+
+trait TemporaryTableTrait {
+	protected $table_name        = 'foobar';
+	protected $target_table_name = 'targettable';
+	protected $drop_table        = false;
+	protected $drop_target_table = false;
+
+	protected function init_temporary_tables() {
+		global $wpdb;
+
+		$this->table_name        = $wpdb->prefix . $this->table_name;
+		$this->target_table_name = $wpdb->prefix . $this->target_table_name;
+	}
+
+	protected function maybe_drop_temporary_tables() {
+		global $wpdb;
+
+		if ( $this->drop_table ) {
+			$query  = "DROP TEMPORARY TABLE IF EXISTS `{$this->table_name}`";
+			$result = $wpdb->query( $query );
+		}
+
+		if ( $this->drop_target_table ) {
+			$query  = "DROP TEMPORARY TABLE IF EXISTS `{$this->target_table_name}`";
+			$result = $wpdb->query( $query );
+		}
+	}
+
+	protected function create_table( $table_name = '' ) {
+		global $wpdb;
+
+		if ( empty( $table_name ) ) {
+			$table_name = $this->table_name;
+		}
+
+		$charset_collate = $wpdb->get_charset_collate();
+		$schema          = "
+			id bigint(20) unsigned NOT NULL auto_increment,
+			data longtext default NULL,
+			PRIMARY KEY  (id)";
+
+		$wpdb->query( "CREATE TEMPORARY TABLE `$table_name` ($schema) $charset_collate" );
+	}
+
+	protected function add_row( $data, $table_name = '' ) {
+		global $wpdb;
+
+		if ( empty( $table_name ) ) {
+			$table_name = $this->table_name;
+		}
+
+		$wpdb->insert(
+			$table_name,
+			[ 'data' => $data ],
+			[ 'data' => '%s' ]
+		);
+
+		return (int) $wpdb->insert_id;
+	}
+
+	protected function get_rows( $table_name = '' ) {
+		global $wpdb;
+
+		if ( empty( $table_name ) ) {
+			$table_name = $this->table_name;
+		}
+
+		return $wpdb->get_results(
+			"SELECT * FROM $table_name ORDER BY `id` ASC",
+			ARRAY_A
+		);
+	}
+
+	protected function get_last_row( $table_name = '' ) {
+		global $wpdb;
+
+		if ( empty( $table_name ) ) {
+			$table_name = $this->table_name;
+		}
+
+		return $wpdb->get_row(
+			"SELECT * FROM {$table_name} ORDER BY `id` DESC LIMIT 1;",
+			ARRAY_A
+		);
+	}
+}

Tests/Integration/TestCase.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Screenfeed\AutoWPDB\Tests\Integration;
+
+use Brain\Monkey;
+use Screenfeed\AutoWPDB\Tests\TestCaseTrait;
+use WP_UnitTestCase;
+
+abstract class TestCase extends WP_UnitTestCase {
+	use TestCaseTrait;
+
+	/**
+	 * Prepares the test environment before each test.
+	 */
+	public function setUp() {
+		parent::setUp();
+		Monkey\setUp();
+	}
+
+	/**
+	 * Cleans up the test environment after each test.
+	 */
+	public function tearDown() {
+		Monkey\tearDown();
+		parent::tearDown();
+	}
+
+	public function return_true() {
+		return true;
+	}
+
+	public function return_false() {
+		return false;
+	}
+}