Add support for nested sub-WHERE clauses and update hook naming

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file. This project adhere to the [Semantic Versioning](http://semver.org/) standard.
 
+## [3.2.0] 2026-01-05
+
+* Feature - Add support for nested sub-WHERE clauses in `paginate()` and `get_total_items()` methods. This allows building complex queries like `WHERE (col1 = 'a' OR col2 = 'b') AND col3 = 'c'`.
+* Feature - Add new `stellarwp_schema_custom_table_paginate_query` filter to allow modification of the paginate query before execution.
+* Feature - Add new `stellarwp_schema_custom_table_total_items_query` filter to allow modification of the total items count query before execution.
+* Tweak - Rename hooks from `tec_common_*` prefix to `stellarwp_schema_*` prefix for consistency with the StellarWP namespace.
+
+### Breaking Changes
+
+The following hooks have been renamed:
+- `tec_common_custom_table_query_pre_results` → `stellarwp_schema_custom_table_query_pre_results`
+- `tec_common_custom_table_query_post_results` → `stellarwp_schema_custom_table_query_post_results`
+- `tec_common_custom_table_query_results` → `stellarwp_schema_custom_table_query_results`
+- `tec_common_custom_table_query_where` → `stellarwp_schema_custom_table_query_where`
+
+[3.2.0]: https://github.com/stellarwp/schema/releases/tag/3.2.0
+
 ## [3.1.4] 2025-10-16
 
 * Fix - Handle array values correctly in the `get_*` query methods.

composer.json

@@ -30,7 +30,8 @@
     "symfony/event-dispatcher-contracts": "^2.5.1",
     "symfony/string": "^5.4",
     "szepeviktor/phpstan-wordpress": "^1.1",
-    "php-stubs/wp-cli-stubs": "^2.11"
+    "php-stubs/wp-cli-stubs": "^2.11",
+    "lucatume/codeception-snapshot-assertions": "^0.5.0"
   },
   "minimum-stability": "stable",
   "autoload": {

docs/query-methods.md

@@ -271,7 +271,7 @@ $args = [
 	'orderby' => 'created_at',  // Column to sort by.
 	'order' => 'DESC',  // ASC or DESC.
 	'offset' => 0,  // Starting offset.
-	'query_operator' => 'AND',  // AND or OR.
+	'query_operator' => 'AND',  // AND or OR for top-level conditions.
 
 	// Column filters.
 	[
@@ -284,6 +284,21 @@ $args = [
 		'value' => 1000,
 		'operator' => '<',
 	],
+
+	// Sub-WHERE clauses (v3.2.0+) - group conditions with their own operator.
+	[
+		'query_operator' => 'OR',  // Operator for this group.
+		[
+			'column' => 'type',
+			'value' => 'classic',
+			'operator' => '=',
+		],
+		[
+			'column' => 'type',
+			'value' => 'premium',
+			'operator' => '=',
+		],
+	],
 ];
 ```
 
@@ -321,6 +336,33 @@ $results = Sandwiches::paginate(
 	1
 );
 
+// Sub-WHERE clauses (v3.2.0+).
+// Query: WHERE (type = 'classic' OR type = 'premium') AND price_cents < 1500
+$results = Sandwiches::paginate(
+	[
+		[
+			'query_operator' => 'OR',
+			[
+				'column' => 'type',
+				'value' => 'classic',
+				'operator' => '=',
+			],
+			[
+				'column' => 'type',
+				'value' => 'premium',
+				'operator' => '=',
+			],
+		],
+		[
+			'column' => 'price_cents',
+			'value' => 1500,
+			'operator' => '<',
+		],
+	],
+	20,
+	1
+);
+
 // With JOIN.
 $results = Sandwiches::paginate(
 	$args,
@@ -498,28 +540,46 @@ Query methods provide hooks for customization:
 
 ```php
 // Before query execution.
-add_action( 'tec_common_custom_table_query_pre_results', function( $args, $class ) {
+add_action( 'stellarwp_schema_custom_table_query_pre_results', function( $args, $class ) {
 	// Modify args, log, etc.
 }, 10, 2 );
 
 // After query execution.
-add_action( 'tec_common_custom_table_query_post_results', function( $results, $args, $class ) {
+add_action( 'stellarwp_schema_custom_table_query_post_results', function( $results, $args, $class ) {
 	// Log, analyze, etc.
 }, 10, 3 );
 
 // Filter results.
-add_filter( 'tec_common_custom_table_query_results', function( $results, $args, $class ) {
+add_filter( 'stellarwp_schema_custom_table_query_results', function( $results, $args, $class ) {
 	// Modify results.
 	return $results;
 }, 10, 3 );
 
 // Filter WHERE clause.
-add_filter( 'tec_common_custom_table_query_where', function( $where, $args, $class ) {
+add_filter( 'stellarwp_schema_custom_table_query_where', function( $where, $args, $class ) {
 	// Add custom WHERE conditions.
 	return $where;
 }, 10, 3 );
+
+// Filter the paginate query before execution (v3.2.0+).
+add_filter( 'stellarwp_schema_custom_table_paginate_query', function( $query ) {
+	// Modify the SQL query string before execution.
+	// Useful for debugging, logging, or query modifications.
+	error_log( "Paginate query: {$query}" );
+	return $query;
+} );
+
+// Filter the total items count query before execution (v3.2.0+).
+add_filter( 'stellarwp_schema_custom_table_total_items_query', function( $query ) {
+	// Modify the SQL count query string before execution.
+	// Useful for debugging, logging, or query modifications.
+	error_log( "Total items query: {$query}" );
+	return $query;
+} );
 ```
 
+> **Note (v3.2.0):** The hook names were changed from `tec_common_*` prefix to `stellarwp_schema_*` prefix. If you're upgrading from an earlier version, update your hook callbacks accordingly.
+
 ## Performance Tips
 
 1. **Batch Operations**: Use `insert_many()` and `update_many()` for bulk operations
@@ -533,4 +593,4 @@ add_filter( 'tec_common_custom_table_query_where', function( $where, $args, $cla
 - [Column System](columns.md)
 - [Index System](indexes.md)
 - [Table Schemas](schemas-table.md)
-- [Migrating from v2 to v3](migrating-from-v2-to-v3.md)
+- [Migrating from v2 to v3](migrating-from-v2-to-v3.md)