Skip to content

Commit 595ca6d

Browse files
ryanwelcherclaude
ryanwelcher
and
claude
committed
Add CLAUDE.md documentation file for Claude Code.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 12fc411 commit 595ca6d

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

‎CLAUDE.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Advanced Query Loop (AQL) is a WordPress plugin that extends the core Query Loop block with advanced querying capabilities. It provides a block variation with additional controls for taxonomy queries, post meta queries, date queries, post ordering, and more.
8+
9+
The plugin uses a hybrid architecture combining PHP server-side logic with TypeScript/React for the block editor interface.
10+
11+
## Development Commands
12+
13+
### Setup
14+
```bash
15+
npm run setup # Install PHP dependencies (runs composer run dev)
16+
composer run dev # Install PHP dev dependencies with autoload
17+
```
18+
19+
### Development
20+
```bash
21+
npm start # Start development mode (TypeScript watch + webpack)
22+
npm run start:webpack # Start webpack only
23+
npm run start:hot # Start with hot module replacement
24+
npm run tsc # Run TypeScript compiler once
25+
npm run tsc:watch # Run TypeScript compiler in watch mode
26+
```
27+
28+
### Building
29+
```bash
30+
npm run build # Build production JavaScript/TypeScript
31+
npm run release # Full release build (composer build + npm build + plugin-zip)
32+
npm run plugin-zip # Create distributable plugin ZIP
33+
composer run build # Production PHP build (no dev dependencies)
34+
```
35+
36+
### Testing
37+
```bash
38+
npm run test:unit # Run PHPUnit tests
39+
./vendor/bin/phpunit # Run PHPUnit directly
40+
```
41+
42+
### Local Environment
43+
```bash
44+
npm run wp-env start # Start local WordPress environment
45+
npm run wp-env stop # Stop local WordPress environment
46+
```
47+
48+
### Code Quality
49+
```bash
50+
npm run format # Format code using WordPress standards
51+
```
52+
53+
## Architecture
54+
55+
### PHP Architecture (Server-Side)
56+
57+
**Entry Point**: `index.php` - Main plugin file that loads the autoloader.
58+
59+
**Core Query Processing**:
60+
- `includes/Query_Params_Generator.php` - Central class that processes all custom query parameters using traits
61+
- `includes/query-loop.php` - Hooks into WordPress filters to modify queries on both frontend and REST API
62+
- Uses the `pre_render_block` filter to intercept Query Loop blocks with `namespace: 'advanced-query-loop'`
63+
- Uses `query_loop_block_query_vars` filter for non-inherited queries
64+
- Uses `rest_{post_type}_query` filters to enable custom parameters in the block editor
65+
66+
**Query Parameter Traits** (`includes/Traits/`):
67+
Each trait in the Traits directory handles a specific query modification:
68+
- `Date_Query.php` - Before/after/relative date filtering
69+
- `Disable_Pagination.php` - Performance optimization by disabling pagination
70+
- `Exclude_Current.php` - Remove current post from results
71+
- `Exclude_Taxonomies.php` - Exclude posts by taxonomy terms
72+
- `Include_Posts.php` - Manually select specific posts
73+
- `Meta_Query.php` - Post meta filtering with multiple conditions
74+
- `Multiple_Posts.php` - Multiple post type selection
75+
- `Post_Parent.php` - Child post filtering
76+
- `Tax_Query.php` - Advanced taxonomy queries with AND/OR logic
77+
78+
**Key Filter Hook**: `aql_query_vars` - This filter allows extensions to modify query arguments. It receives:
79+
1. `$query_args` - Arguments to be passed to WP_Query
80+
2. `$block_query` - The query attribute from the block
81+
3. `$inherited` - Whether the query is being inherited from template
82+
83+
### TypeScript/React Architecture (Block Editor)
84+
85+
**Entry Point**: `src/variations/index.ts` - Registers the block variation and exports SlotFills.
86+
87+
**Block Variation Registration**: Registers `advanced-query-loop` as a variation of `core/query` with custom namespace attribute.
88+
89+
**Controls System** (`src/variations/controls.tsx`):
90+
- Uses `addFilter` on `editor.BlockEdit` to inject custom controls
91+
- Conditionally renders different control sets based on `query.inherit` attribute
92+
- When `inherit: false` - Shows all advanced controls in the "Advanced Query Settings" panel
93+
- When `inherit: true` - Shows limited controls (only PostOrderControls and inherited query slot)
94+
95+
**UI Components** (`src/components/`):
96+
Each component corresponds to a query feature:
97+
- `post-meta-query-controls.js` - Complex meta query builder
98+
- `post-date-query-controls.js` - Date filtering UI
99+
- `multiple-post-select.js` - Post type selector
100+
- `post-order-controls.tsx` - Order/orderby controls
101+
- `post-exclude-controls.js` - Exclude current post, categories
102+
- `taxonomy-query-control.js` - Advanced taxonomy query builder
103+
- `post-include-controls.js` - Manual post selection
104+
- `pagination-toggle.js` - Enable/disable pagination
105+
- `child-items-toggle.js` - Show only child items
106+
107+
**SlotFill System** (`src/slots/`):
108+
Extensibility mechanism exposed via `window.aql`:
109+
- `AQLControls` - Slot for controls shown when NOT inheriting query
110+
- `AQLControlsInheritedQuery` - Slot for controls shown when inheriting query
111+
- `AQLLegacyControls` - Slot for legacy Gutenberg < 19 controls
112+
113+
### Build System
114+
115+
**Webpack Configuration** (`webpack.config.js`):
116+
- Extends `@wordpress/scripts` default configuration
117+
- Entry point: `src/variations/index.ts`
118+
- Additional entry for legacy pre-GB-19 controls: `src/legacy-controls/pre-gb-19.js`
119+
- Exports library to global `window.aql`
120+
- Dev server allows all hosts for cross-environment testing
121+
122+
**TypeScript Configuration**:
123+
- Strict mode enabled with `noUncheckedIndexedAccess`
124+
- Target: ES2022
125+
- No emit (webpack handles compilation)
126+
- Preserves JSX and modules
127+
128+
### Data Flow
129+
130+
1. **In Block Editor**:
131+
- User interacts with React controls in Inspector panel
132+
- Controls update block attributes via `setAttributes`
133+
- Attributes stored in block's `query` object with custom properties
134+
- REST API requests use `rest_{post_type}_query` filters to preview results
135+
- `Query_Params_Generator` processes custom params into WP_Query format
136+
137+
2. **On Frontend**:
138+
- `pre_render_block` filter catches blocks with `namespace: 'advanced-query-loop'`
139+
- For inherited queries: Modifies global `$wp_query` directly
140+
- For non-inherited queries: Hooks into `query_loop_block_query_vars`
141+
- `Query_Params_Generator` converts block attributes to WP_Query args
142+
- `aql_query_vars` filter allows final modifications before query execution
143+
144+
### Extensibility
145+
146+
Developers can extend AQL in two ways:
147+
148+
1. **JavaScript SlotFills**: Add custom controls via `window.aql.AQLControls` or `window.aql.AQLControlsInheritedQuery`
149+
2. **PHP Filter Hook**: Modify query arguments via `aql_query_vars` filter
150+
151+
See `extending-aql.md` for detailed examples.
152+
153+
## Testing
154+
155+
PHPUnit tests are located in `tests/unit/`. Configuration in `phpunit.xml` uses PHPUnit 8.5 with Yoast polyfills for PHP 7.4+ compatibility.
156+
157+
## Plugin Distribution
158+
159+
The plugin follows WordPress.org conventions:
160+
- `readme.txt` - WordPress.org plugin readme
161+
- `readme.md` - GitHub readme
162+
- Main branch: `trunk`
163+
- PHP namespace: `AdvancedQueryLoop\`
164+
- Text domain: `advanced-query-loop`

0 commit comments

Comments
 (0)