Merge pull request #43 from stellarwp/feat/v3-strict-column-definitions

feat: Introduce v3 strict column definitions and enhanced type safety

Author: dpanta94

CHANGELOG.md

@@ -2,7 +2,11 @@
 
 All notable changes to this project will be documented in this file. This project adhere to the [Semantic Versioning](http://semver.org/) standard.
 
-## [unreleased] Unreleased
+## [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.
+
+[3.0.0]: https://github.com/stellarwp/schema/releases/tag/3.0.0
 
 ## [2.0.1] 2025-07-18
 
@@ -16,7 +20,6 @@ Feature - Bump di52 to 4.0.1 and all other deps.
 
 * Tweak - Add @throws tags from the [stellarwp/db](https://github.com/stellarwp/db) library and better generics.
 
-
 ## [1.1.8] 2025-01-10
 
 * Feature - Introduce truncate method which does what the empty_table method was doing. Update empty_table to actually empty the table instead of truncating it.

docs/migrating-from-v2-to-v3.md

@@ -0,0 +1,35 @@
+# Migrating from V2 to V3
+
+## Overview
+
+Version 3 introduces several important changes:
+
+- Stricter column and indexes definitions
+- Enhanced query methods available through extending `StellarWP\Schema\Tables\Contracts\Table`
+
+## Migration Steps
+
+### 1. Update Method Visibility
+
+For classes extending `StellarWP\Schema\Tables\Contracts\Table`:
+
+- Convert the `get_definition` method from `protected` to `public`
+
+If in your implementation you chose to directly implement the renamed interface `StellarWP\Schema\Tables\Contracts\Schema_Interface`, you will need to implement the new interface `StellarWP\Schema\Tables\Contracts\Table_Interface` instead.
+
+We strongly recommend extending the provided abstract instead.
+
+### 2. Implement Schema History
+
+In your table class:
+
+- Add the static method `get_schema_history`
+- Optionally keep or remove the `get_definition` method
+
+### 3. Define Schema History
+
+The `get_schema_history` method must:
+
+- Return an array of callables
+- Each callable should return a `StellarWP\Schema\Tables\Contracts\Table_Schema_Interface` object
+- Include at least one entry for your current schema version

phpstan.neon.dist

@@ -20,7 +20,6 @@ parameters:
 	level: 5
 	inferPrivatePropertyTypeFromConstructor: true
 	reportUnmatchedIgnoredErrors: false
-	checkGenericClassInNonGenericObjectType: false
 
 	# Paths to be analyzed.
 	paths:

src/Schema/Builder.php

@@ -3,10 +3,8 @@
 namespace StellarWP\Schema;
 
 use StellarWP\Schema\Config;
-use StellarWP\Schema\Fields;
-use StellarWP\Schema\Fields\Contracts\Schema_Interface as Field_Schema_Interface;
 use StellarWP\Schema\Tables;
-use StellarWP\Schema\Tables\Contracts\Schema_Interface as Table_Schema_Interface;
+use StellarWP\Schema\Tables\Contracts\Table_Interface as Table_Schema_Interface;
 use StellarWP\Schema\Tables\Filters\Group_FilterIterator;
 use WP_CLI;
 
@@ -37,7 +35,7 @@ public function __construct( $db = null, $container = null ) {
 	}
 
 	/**
-	 * Whether all the custom tables exist or not. Does not check custom fields.
+	 * Whether all the custom tables exist or not.
 	 *
 	 * Note: the method will return `false` if even one table is missing.
 	 *
@@ -47,7 +45,7 @@ public function __construct( $db = null, $container = null ) {
 	 *
 	 * @param string|null $group An optional group name to restrict the check to.
 	 *
-	 * @return bool Whether all custom tables exist or not. Does not check custom fields.
+	 * @return bool Whether all custom tables exist or not.
 	 */
 	public function all_tables_exist( $group = null ) {
 		$table_schemas = $this->get_registered_table_schemas();
@@ -64,7 +62,6 @@ public function all_tables_exist( $group = null ) {
 		$result = $this->db::get_col( 'SHOW TABLES' );
 		foreach ( $table_schemas as $table_schema ) {
 			if ( ! in_array( $table_schema::table_name(), $result, true ) ) {
-
 				return false;
 			}
 		}
@@ -108,35 +105,6 @@ public function down() {
 		 * @since 1.0.0
 		 */
 		do_action( 'stellarwp_post_drop_tables' );
-
-		/**
-		 * Runs before the custom fields are dropped.
-		 *
-		 * @since 1.0.0
-		 */
-		do_action( 'stellarwp_pre_drop_fields' );
-
-		$field_schemas = $this->get_registered_field_schemas();
-
-		/**
-		 * Filters the fields to be dropped.
-		 *
-		 * @since 1.0.0
-		 *
-		 * @param \Iterator $field_classes A list of Field_Schema_Interface objects that will have their fields dropped.
-		 */
-		$field_schemas = apply_filters( 'stellarwp_fields_to_drop', $field_schemas );
-
-		foreach ( $field_schemas as $field_schema ) {
-			$field_schema->drop();
-		}
-
-		/**
-		 * Runs after the custom tables have been dropped by The Events Calendar.
-		 *
-		 * @since 1.0.0
-		 */
-		do_action( 'stellarwp_post_drop_fields' );
 	}
 
 	/**
@@ -153,17 +121,6 @@ public function empty_custom_tables() {
 		}
 	}
 
-	/**
-	 * Get the registered field handlers.
-	 *
-	 * @since 1.0.0
-	 *
-	 * @return Fields\Collection
-	 */
-	public function get_registered_field_schemas(): Fields\Collection {
-		return $this->container->get( Fields\Collection::class );
-	}
-
 	/**
 	 * Get the md5 hash of all the registered schemas classes with their versions.
 	 *

src/Schema/Collections/Collection.php

@@ -0,0 +1,200 @@
+<?php
+/**
+ * Abstract collection.
+ *
+ * @since 3.0.0
+ *
+ * @package StellarWP\Schema\Collections
+ */
+
+declare( strict_types=1 );
+
+namespace StellarWP\Schema\Collections;
+
+use ArrayAccess;
+use Countable;
+use Iterator;
+use JsonSerializable;
+use ReturnTypeWillChange;
+
+/**
+ * Abstract collection.
+ *
+ * @since 3.0.0
+ *
+ * @package StellarWP\Schema\Collections
+ */
+abstract class Collection implements ArrayAccess, Iterator, Countable, JsonSerializable {
+	/**
+	 * Collection of items.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @var array
+	 */
+	protected array $resources = [];
+
+	/**
+	 * Constructor.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param array $resources An array of items.
+	 */
+	final public function __construct( array $resources = [] ) {
+		foreach ( $resources as $offset => $value ) {
+			$this->set( (string) $offset, $value );
+		}
+	}
+
+	/**
+	 * Sets a value in the collection.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param string $offset The offset to set.
+	 * @param mixed  $value  The value to set.
+	 */
+	protected function set( string $offset, $value ): void {
+		$this->resources[ $offset ] = $value;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	#[ReturnTypeWillChange]
+	public function current() {
+		return current( $this->resources );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function key(): ?string {
+		return (string) key( $this->resources );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function next(): void {
+		next( $this->resources );
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @param string $offset The offset to check.
+	 *
+	 * @return bool
+	 */
+	public function offsetExists( $offset ): bool {
+		return array_key_exists( $offset, $this->resources );
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @param string $offset The offset to get.
+	 *
+	 * @return ?mixed
+	 */
+	#[ReturnTypeWillChange]
+	public function offsetGet( $offset ) {
+		return $this->resources[ $offset ] ?? null;
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @param string $offset The offset to set.
+	 * @param mixed  $value  The value to set.
+	 */
+	public function offsetSet( $offset, $value ): void {
+		if ( ! $offset ) {
+			$offset = (string) count( $this->resources );
+		}
+		$this->set( $offset, $value );
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @param string $offset The offset to unset.
+	 */
+	public function offsetUnset( $offset ): void {
+		unset( $this->resources[ $offset ] );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function rewind(): void {
+		reset( $this->resources );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function valid(): bool {
+		return key( $this->resources ) !== null;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function count(): int {
+		return count( $this->resources );
+	}
+
+	/**
+	 * Returns the collection as an array.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @return array
+	 */
+	public function jsonSerialize(): array {
+		return $this->resources;
+	}
+
+	/**
+	 * Maps the collection to an array.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param callable $callback The callback to map the collection to an array.
+	 *
+	 * @return self
+	 */
+	public function map( callable $callback ): self {
+		return new static( array_map( $callback, $this->resources ) );
+	}
+
+	/**
+	 * Filters the collection.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param callable $callback The callback to filter the collection.
+	 *
+	 * @return self
+	 */
+	public function filter( callable $callback ): self {
+		return new static( array_filter( $this->resources, $callback ) );
+	}
+
+	/**
+	 * Gets a resource from the collection.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param string $key The key to get.
+	 *
+	 * @return ?mixed
+	 */
+	#[ReturnTypeWillChange]
+	public function get( string $key ) {
+		return $this->offsetGet( $key );
+	}
+}