Feat/adding more column types

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file. This project adhere to the [Semantic Versioning](http://semver.org/) standard.
 
+## [3.1.0] 2025-09-30
+
+* Feature - Introduce new column types: `Blob_Column`, `Binary_Column`, and `Boolean_Column`.
+* Feature - Introduce new PHP type: Blob. Blob will be stored as a base64 encoded string.
+* Tweak - Update string based columns to have the ability to become primary keys. Those columns include: char, varchar, binary and varbinary.
+
+[3.1.0]: https://github.com/stellarwp/schema/releases/tag/3.1.0
+
 ## [3.0.0] 2025-09-24
 
 * Feature - Introduces stricter column and indexes definitions. This is NOT a backwards compatible change. Read the migration guide in docs/migrating-from-v2-to-v3.md.

README.md

@@ -34,6 +34,18 @@ The examples will be using:
 * `Boom\Shakalaka\` as the namespace prefix, though will sometimes be referenced as `PREFIX\` for the purpose of brevity in the docs.
 * `BOOM_SHAKALAKA_` as the constant prefix.
 
+## What's new in 3.0.0
+
+Version 3.0.0 introduces major new features and breaking changes:
+
+- **Type-safe Column Definitions**: Define table columns using strongly-typed classes (`Integer_Column`, `String_Column`, `Float_Column`, etc.) instead of raw SQL
+- **Index Management**: Create and manage indexes with dedicated classes (`Primary_Key`, `Unique_Key`, `Classic_Index`, `Fulltext_Index`)
+- **Schema History**: Track and manage schema changes over time with the `get_schema_history()` method
+- **Enhanced Query Methods**: Access built-in CRUD operations through the `Custom_Table_Query_Methods` trait
+- **Improved Type Safety**: Automatic type casting and validation for PHP/MySQL data transformation
+
+**Note**: Version 3.0.0 is NOT backwards compatible with 2.x. See the [migration guide](docs/migrating-from-v2-to-v3.md) for upgrading from v2 to v3.
+
 ## Getting started
 
 For a full understanding of what is available in this library and how to use it, definitely read through the full [documentation](#documentation). But for folks that want to get rolling with the basics quickly, try out the following.
@@ -55,15 +67,22 @@ Config::set_container( $container );
 Config::set_db( DB::class );
 ```
 
-### Creating a table
+### Creating a table (v3.0+)
 
 Let's say you want a new custom table called `sandwiches` (with the default WP prefix, it'd be `wp_sandwiches`). You'll need a class file for the table. For the sake of this example, we'll be assuming this class is going into a `Tables/` directory and is reachable via the `Boom\Shakalaka\Tables` namespace.
 
+**Version 3.0** introduces a new, type-safe way to define tables using Column and Index classes:
+
 ```php
 <?php
 namespace Boom\Shakalaka\Tables;
 
 use Boom\Shakalaka\StellarWP\Schema\Tables\Contracts\Table;
+use Boom\Shakalaka\StellarWP\Schema\Tables\Table_Schema;
+use Boom\Shakalaka\StellarWP\Schema\Collections\Column_Collection;
+use Boom\Shakalaka\StellarWP\Schema\Columns\ID;
+use Boom\Shakalaka\StellarWP\Schema\Columns\String_Column;
+use Boom\Shakalaka\StellarWP\Schema\Columns\Column_Types;
 
 class Sandwiches extends Table {
 	/**
@@ -89,34 +108,46 @@ class Sandwiches extends Table {
 	/**
 	 * {@inheritdoc}
 	 */
-	protected static $uid_column = 'id';
-
-	/**
-	 * {@inheritdoc}
-	 */
-	protected function get_definition() {
-		global $wpdb;
-		$table_name = self::table_name( true );
-		$charset_collate = $wpdb->get_charset_collate();
-
-		return "
-			CREATE TABLE `{$table_name}` (
-				`id` int(11) UNSIGNED NOT NULL AUTO_INCREMENT,
-				`name` varchar(50) NOT NULL,
-				PRIMARY KEY (`id`)
-			) {$charset_collate};
-		";
+	public static function get_schema_history(): array {
+		$table_name = static::table_name( true );
+
+		return [
+			'1.0.0' => function() use ( $table_name ) {
+				$columns = new Column_Collection();
+
+				// Define an auto-incrementing ID column
+				$columns[] = ( new ID( 'id' ) )
+					->set_length( 11 )
+					->set_type( Column_Types::INT )
+					->set_auto_increment( true );
+
+				// Define a varchar column for the name
+				$columns[] = ( new String_Column( 'name' ) )
+					->set_type( Column_Types::VARCHAR )
+					->set_length( 50 );
+
+				return new Table_Schema( $table_name, $columns );
+			},
+		];
 	}
 }
 ```
 
+You can still use the `get_definition()` method for backwards compatibility, but the new Column/Index system is recommended for all new tables. You must switch the visibility of the `get_definition()` method to `public` and still implement the `get_schema_history()` method, however.
+
 Here's what the properties and method mean:
 
 * `$base_table_name`: The name of the table without the prefix.
 * `$group`: The group that the table belongs to - this is for organizational purposes.
 * `$schema_slug`: An identifier for the table. This is used in storing your table's schema version in `wp_options`.
-* `$uid_column`: The name of the column that is used to uniquely identify each row.
-* `get_definition()`: This should return the base SQL definition used to create your `sandwiches` table. To get the full SQL (with any field schemas included), you can call `get_sql()`!
+* `get_schema_history()`: Returns an array of callables keyed by version number. Each callable returns a `Table_Schema` object defining columns and indexes for that version.
+
+**Key features of the new v3 system:**
+
+* **Type-safe columns**: Use `Integer_Column`, `String_Column`, `Float_Column`, `Text_Column`, `Datetime_Column`, and specialized columns like `ID`, `Created_At`, `Updated_At`
+* **Fluent API**: Chain methods like `set_length()`, `set_default()`, `set_nullable()`, `set_auto_increment()`
+* **Index support**: Define indexes with `Classic_Index`, `Unique_Key`, `Primary_Key`, `Fulltext_Index`
+* **Automatic type casting**: Values are automatically cast between PHP and MySQL types
 
 ### Registering the table
 
@@ -155,6 +186,7 @@ Here's some more advanced documentation to get you rolling on using this library
 	1. [Deregistering fields](/docs/schemas-field.md#deregistering-fields)
 	1. [Field collection](/docs/schemas-field.md#field-collection)
 	1. [Publicly accessible methods](/docs/schemas-field.md#publicly-accessible-methods)
+1. [Migrating from v2 to v3](/docs/migrating-from-v2-to-v3.md) - **Important for existing users!**
 1. [Automated testing](/docs/automated-testing.md)
 
 ## Acknowledgements