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

[dpanta94]

Summary

This PR introduces support for nested sub-WHERE clauses in query methods and standardizes hook naming to align with the StellarWP namespace. These changes enable more flexible and complex database queries while maintaining backward compatibility through semantic versioning.

Key Changes

1. Nested Sub-WHERE Clauses - Adds the ability to build complex queries with grouped conditions and custom operators (AND/OR) within the paginate() and get_total_items() methods.

2. Hook Naming Standardization - Renamed all hooks from tec_common_* prefix to stellarwp_schema_* prefix for namespace consistency (breaking change, documented in CHANGELOG).

Technical Details

Sub-WHERE Clause Implementation

The implementation extracts sub-where clause logic into a new private method build_sub_wheres_from_args() that recursively builds grouped query conditions. This allows developers to construct queries like:

// Query: WHERE (type = 'classic' OR type = 'premium') AND price_cents < 1500
$results = Model::paginate([
    [
        'query_operator' => 'OR',
        [
            'column' => 'type',
            'value' => 'classic',
            'operator' => '=',
        ],
        [
            'column' => 'type',
            'value' => 'premium',
            'operator' => '=',
        ],
    ],
    [
        'column' => 'price_cents',
        'value' => 1500,
        'operator' => '<',
    ],
], 20, 1);

Architecture Decision: The recursive approach allows for arbitrary nesting depth without code duplication. Each sub-where group is wrapped in parentheses and joined with its specified operator, maintaining SQL precedence rules.

Breaking Changes

Hook names have been changed to reflect the correct namespace:

• 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

Migration Path: Consumers using these hooks must update their code. The change is documented in CHANGELOG.md with clear before/after examples.

Documentation

Updated documentation includes:

• CHANGELOG.md: Comprehensive entry for v3.2.0 with feature description and breaking changes
• docs/query-methods.md: Extended with sub-WHERE clause examples and updated hook references

Areas Requiring Review Attention

1. Recursive Logic: Verify the recursive sub-where building logic handles edge cases correctly
2. SQL Injection: Confirm that the prepared statement handling remains secure with nested conditions
3. Breaking Changes: Validate that the hook renaming is properly documented for consumers
4. Test Coverage: Review test cases for completeness, particularly around operator precedence

[Rahmon]

@dpanta94 you are checking if the hooks are fired here, right? Have you considered using did_filter or did_action to check if a hook was fired? This is a pattern used in WordPress: https://github.com/WordPress/wordpress-develop/blob/trunk/tests/phpunit/tests/template.php#L596

That way, for the hook stellarwp_schema_custom_table_query_pre_results, for example, you can remove this:

$pre_results_fired = false;

[...]

add_action( 'stellarwp_schema_custom_table_query_pre_results', function() use ( &$pre_results_fired ) {
	$pre_results_fired = true;
} );

and make this change:

- $this->assertTrue( $pre_results_fired, 'stellarwp_schema_custom_table_query_pre_results action should fire' );
+ $this->assertSame( 1, did_action('stellarwp_schema_custom_table_query_pre_results'), 'stellarwp_schema_custom_table_query_pre_results action should fire' );

[lucatume]

These tests could provide more value in their current form by asserting the values passed to them are the expected ones. Else they can be simplified as suggested by @Rahmon.

[dpanta94]

Good suggestion. Thank you. I have simplified those checks. I did the patter of storing the did_action before and asserting that after is equal than stored + 1.

[lucatume]

Two requests:

1. Add a test to cover malformed sub-WHERE inputs where one or more keys are missing or the operator is not correct.
2. The changelog mentions a but-fix, is there a test for this?

[lucatume]

These tests could provide more value in their current form by asserting the values passed to them are the expected ones. Else they can be simplified as suggested by @Rahmon.

[dpanta94]

@lucatume this is ready for a second look when you can !