How ryanwelcher/advanced-query-loop works
Project type and purpose
• This is a WordPress plugin (“Advanced Query Loop”) that provides an enhanced variation of the core Gutenberg Query Loop block.
• It consists of a PHP “backend” that hooks into WordPress, generates modified query parameters, and registers server-side assets, plus a React/JavaScript “frontend” that extends the block editor UI.
File structure
• Top level:
• index.php – main plugin bootstrap
• composer.json / package.json – PHP and JavaScript dependency manifests
• webpack.config.js – JavaScript build configuration
• .github / tests / phpunit.xml – CI and testing setup
• includes/ directory (PHP):
• Query_Params_Generator.php – central class that assembles WP_Query args
• Traits/ – reusable filters (Date_Query, Meta_Query, Tax_Query, etc.)
• enqueues.php – registers PHP assets and block scripts/styles
• query-loop.php, taxonomy.php, utilities.php – support functions
• src/ directory (JS):
• components/ – individual React controls (post-include, exclude, order, pagination toggle, etc.)
• slots/ – slot fills for injecting controls into the Query Loop sidebar
• hooks/ – custom hooks (useDebouncedInputValue)
• legacy-controls/ – polyfills for older Gutenberg versions
• utils/variations/ – block variation registration and default settings
• tests/ – PHPUnit tests for PHP classes
• .github/workflows – automated linting, testing, release.
Architectural insights from README
• Plugin adds new Query Loop block variation with additional controls for taxonomy, post-meta, date, pagination, etc.
• It is extensible (see extending-aql.md) – third-party code can hook into the generator or add custom traits.
Main components and their relationships
A. WordPress Core
• Provides block editor environment, REST API endpoints, and WP_Query engine.
B. Plugin Bootstrap (index.php)
• Registers block variation, loads includes/enqueues, hooks into render process.
C. PHP Query_Params_Generator
• Combines enabled traits based on block attributes to produce final WP_Query args.
D. Traits (Date_Query, Meta_Query, etc.)
• Encapsulate individual query modifications; attached dynamically to the generator.
E. JavaScript Block Variation
• React code in src/variations registers a new block type with custom attribute schema.
F. Editor UI Components
• Each control (components/*) reads/writes specific block attributes.
• slots/* inject those controls into the Query Loop sidebar via Gutenberg Slot/Fill API.
G. Build System
• webpack bundles React code into editor.js and front-end.js.
• composer and npm manage PHP/JS dependencies.
H. Tests & CI
• PHPUnit runs tests on PHP classes.
• GitHub Actions orchestrates lint, test, and release.
Architectural patterns and design principles
• Plugin modularity via Traits – each query feature is decoupled.
• Separation of Concerns – PHP handles data generation and render; JS handles editor configuration and UI.
• Gutenberg Slot/Fill pattern for non-intrusive UI extension.
• Block variation registration to reuse core block behavior with extra attributes.
Final checklist
• All main components (WordPress core, plugin bootstrap, PHP classes, React UI, build & CI).
• Clear data flows: user input → block editor → server render → front-end output.
• Technology labels: PHP, WP_Query, React, Gutenberg Slot/Fill, webpack, PHPUnit, GitHub Actions.