Branch 0.3

.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;
+	}
+}