README

A library for simplifying the creation, update, and field modification of custom tables within WordPress.

Installation

It's recommended that you install Schema as a project dependency via Composer:

composer require stellarwp/schema

We actually recommend that this library gets included in your project using Strauss.

Luckily, adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.

Usage prerequisites

To actually use the schema library, you must have two additional libraries in your project:

1. A Dependency Injection Container (DI Container) that is compatible with di52 (We recommend using di52.).
2. The stellarwp/db library.

In order to keep this library as light as possible, those dependencies are not included in the library itself. To avoid version compatibility issues, those libraries are also not included as Composer dependencies. Instead, you must include them in your project. We recommend including them via composer using Strauss, just like you have done with this library.

Important note on ALL examples

All examples within the documentation for this project will be assuming that you are using Strauss to prefix the namespaces provided by this library.

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 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. But for folks that want to get rolling with the basics quickly, try out the following.

Initializing the library

use Boom\Shakalaka\StellarWP\Schema\Config;

// You'll need a Dependency Injection Container that is compatible with https://github.com/lucatume/di52.
use Boom\Shakalaka\lucatume\DI52\Container;

// You'll need to use the StellarWP\DB library for database operations.
use Boom\Shakalaka\StellarWP\DB\DB;

$container = new Boom\Shakalaka\lucatume\DI52\Container();

Config::set_container( $container );
Config::set_db( DB::class );

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
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 {
	/**
	 * {@inheritdoc}
	 */
	const SCHEMA_VERSION = '1.0.0';

	/**
	 * {@inheritdoc}
	 */
	protected static $base_table_name = 'sandwiches';

	/**
	 * {@inheritdoc}
	 */
	protected static $group = 'boom';

	/**
	 * {@inheritdoc}
	 */
	protected static $schema_slug = 'boom-sandwiches';

	/**
	 * {@inheritdoc}
	 */
	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.
• 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

The Schema library gets initialized automatically when you register at table or a field schema. To register your table, simply use the handy Register::table() method within the plugins_loaded:

namespace Boom\Shakalaka;

use Boom\Shakalaka\StellarWP\Schema\Register;
use Boom\Shakalaka\Tables\Sandwiches;

add_action( 'plugins_loaded', static function() {
	Register::table( Sandwiches::class );
} );

That's it!

The table will be automatically registered, created, and updated during the plugins_loaded action at priority 1000! (that priority number is filterable via the stellarwp_schema_up_plugins_loaded_priority filter)

Documentation

Here's some more advanced documentation to get you rolling on using this library at a deeper level:

1. Setting up Strauss
2. Schema management
3. Table schemas
   1. Versioning
   2. Registering tables
   3. Deregistering tables
   4. Table collection
   5. Publicly accessible methods
4. Field schemas
   1. Versioning
   2. Registering fields
   3. Deregistering fields
   4. Field collection
   5. Publicly accessible methods
5. Migrating from v2 to v3 - Important for existing users!
6. Automated testing

Acknowledgements

Special props go to @lucatume and @stratease for their initial work on this structure before it was extracted into a standalone library.