You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 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.
Copy file name to clipboardExpand all lines: README.md
+52-20Lines changed: 52 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,6 +34,18 @@ The examples will be using:
34
34
*`Boom\Shakalaka\` as the namespace prefix, though will sometimes be referenced as `PREFIX\` for the purpose of brevity in the docs.
35
35
*`BOOM_SHAKALAKA_` as the constant prefix.
36
36
37
+
## What's new in 3.0.0
38
+
39
+
Version 3.0.0 introduces major new features and breaking changes:
40
+
41
+
-**Type-safe Column Definitions**: Define table columns using strongly-typed classes (`Integer_Column`, `String_Column`, `Float_Column`, etc.) instead of raw SQL
42
+
-**Index Management**: Create and manage indexes with dedicated classes (`Primary_Key`, `Unique_Key`, `Classic_Index`, `Fulltext_Index`)
43
+
-**Schema History**: Track and manage schema changes over time with the `get_schema_history()` method
44
+
-**Enhanced Query Methods**: Access built-in CRUD operations through the `Custom_Table_Query_Methods` trait
45
+
-**Improved Type Safety**: Automatic type casting and validation for PHP/MySQL data transformation
46
+
47
+
**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.
48
+
37
49
## Getting started
38
50
39
51
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.
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.
61
73
74
+
**Version 3.0** introduces a new, type-safe way to define tables using Column and Index classes:
75
+
62
76
```php
63
77
<?php
64
78
namespace Boom\Shakalaka\Tables;
65
79
66
80
use Boom\Shakalaka\StellarWP\Schema\Tables\Contracts\Table;
81
+
use Boom\Shakalaka\StellarWP\Schema\Tables\Table_Schema;
82
+
use Boom\Shakalaka\StellarWP\Schema\Collections\Column_Collection;
83
+
use Boom\Shakalaka\StellarWP\Schema\Columns\ID;
84
+
use Boom\Shakalaka\StellarWP\Schema\Columns\String_Column;
85
+
use Boom\Shakalaka\StellarWP\Schema\Columns\Column_Types;
67
86
68
87
class Sandwiches extends Table {
69
88
/**
@@ -89,34 +108,46 @@ class Sandwiches extends Table {
89
108
/**
90
109
* {@inheritdoc}
91
110
*/
92
-
protected static $uid_column = 'id';
93
-
94
-
/**
95
-
* {@inheritdoc}
96
-
*/
97
-
protected function get_definition() {
98
-
global $wpdb;
99
-
$table_name = self::table_name( true );
100
-
$charset_collate = $wpdb->get_charset_collate();
101
-
102
-
return "
103
-
CREATE TABLE `{$table_name}` (
104
-
`id` int(11) UNSIGNED NOT NULL AUTO_INCREMENT,
105
-
`name` varchar(50) NOT NULL,
106
-
PRIMARY KEY (`id`)
107
-
) {$charset_collate};
108
-
";
111
+
public static function get_schema_history(): array {
112
+
$table_name = static::table_name( true );
113
+
114
+
return [
115
+
'1.0.0' => function() use ( $table_name ) {
116
+
$columns = new Column_Collection();
117
+
118
+
// Define an auto-incrementing ID column
119
+
$columns[] = ( new ID( 'id' ) )
120
+
->set_length( 11 )
121
+
->set_type( Column_Types::INT )
122
+
->set_auto_increment( true );
123
+
124
+
// Define a varchar column for the name
125
+
$columns[] = ( new String_Column( 'name' ) )
126
+
->set_type( Column_Types::VARCHAR )
127
+
->set_length( 50 );
128
+
129
+
return new Table_Schema( $table_name, $columns );
130
+
},
131
+
];
109
132
}
110
133
}
111
134
```
112
135
136
+
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.
137
+
113
138
Here's what the properties and method mean:
114
139
115
140
*`$base_table_name`: The name of the table without the prefix.
116
141
*`$group`: The group that the table belongs to - this is for organizational purposes.
117
142
*`$schema_slug`: An identifier for the table. This is used in storing your table's schema version in `wp_options`.
118
-
*`$uid_column`: The name of the column that is used to uniquely identify each row.
119
-
*`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()`!
143
+
*`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.
144
+
145
+
**Key features of the new v3 system:**
146
+
147
+
***Type-safe columns**: Use `Integer_Column`, `String_Column`, `Float_Column`, `Text_Column`, `Datetime_Column`, and specialized columns like `ID`, `Created_At`, `Updated_At`
148
+
***Fluent API**: Chain methods like `set_length()`, `set_default()`, `set_nullable()`, `set_auto_increment()`
149
+
***Index support**: Define indexes with `Classic_Index`, `Unique_Key`, `Primary_Key`, `Fulltext_Index`
150
+
***Automatic type casting**: Values are automatically cast between PHP and MySQL types
120
151
121
152
### Registering the table
122
153
@@ -155,6 +186,7 @@ Here's some more advanced documentation to get you rolling on using this library
0 commit comments