stellarwp / schema

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

Schema Builder

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.

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

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.

<?php
namespace Boom\Shakalaka\Tables;

use Boom\Shakalaka\StellarWP\Schema\Tables\Contracts\Table;

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}
	 */
	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};
		";
	}
}

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()!

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. 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.

schema's Issues

Move files to src/

src/Schema/ 👉🏻 src/
After #20

"src/Schema/" is PSR-0!

Migrate GiveWP's Migrations into Schema

Give's Migrations and the non-UI code for their MigrationLog would be a nice addition to Schema.

We'll need to migrate that over and convert to WP standards.

Migrate GiveWP's Models into Schema

GiveWP's Models are a nice base implementation. We should migrate that over to and convert to WP standards.

Add a migrations UI

GiveWP has a UI for migrations. Bringing some semblance of that code over such that it can be used and extended by projects.

Adopt the stellarwp/db library

Reorganize interfaces and abstracts into `Contracts/` directories

From an code organization standpoint, I like the way Give does that!

Add Batch migration controller

Once 1.2.0 is out, we can start looking in to an approach to supporting batch-processing of migration data.

It'd be rad to use Action Scheduler under the hood.

Fix CVE-2023-29197

Upgrade guzzlehttp/psr7 to v2.4.5
After #20

Add namespaced WPCLI command for managing schemas

It'd be rad to have some sort of auto-namespaced WPCLI commands for schema management

Here are some braindump notes:

wp {namespace}:schema help (list the tables)
wp {namespace}:schema {table} {up|down|drop|version}

wp tec:schema tec_events up

// Maybe build the namespace from the base namespace of the plugin that is consuming it.
$prefix = str_replace( '\\', '-', __NAMESPACE__ );

apply_filters( 'stellarwp_schema_wpcli_namespace', $prefix, __NAMESPACE__ );

wp tribe-pue:schema

Set min. supported PHP version

After #20 is merged.

8d28bde

@borkweb Is it PHP 7.4? Why is there PHP 7.0 as current (faked) value?

Reduce number of queries on every run to zero

stellarwp/schema executes few queries on ever run.

Would it be possible to run stellarwp/schema only on plugin activation/update?

(a production WordPress installation works from persistent object cache, with almost no SQL queries)

Adopt lucatume\DI52\App

[Architecture] Removing custom repositories of public stellarwp packages

I see 2 StellarWP packages with custom configuration in composer.json.
Composer allows source (git) and dist (zip) downloads.

@borkweb What is up here?

Missing coding standard

Started reading the source code ...

What coding standard should I follow?
Could it be PSR-12?

a useful frankenstein

Writing positive conditions

Instead of === null write ! instance of StellarForce.
Would you merge that kind of a PR?

source