Add aql_query_id field to identify blocks in the aql_query_vars filter

[ryanwelcher]

Adds a Query identifier text control that stores an aql_query_id string in the block's query attribute, making it available in both the $query_args and $block_query parameters of the aql_query_vars filter so individual AQL blocks can be targeted.

Fixes #122

[Copilot]

🟡 Changes recommended

A couple of small input-normalization/robustness issues should be addressed to prevent whitespace-only or non-scalar aql_query_id values from flowing into query vars and filter consumers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds an optional “Query identifier” field to the Advanced Query Loop (AQL) block so individual AQL blocks can be identified and targeted when customizing queries via the aql_query_vars filter (fixes #122).

Changes:

• Added a new block editor TextControl to store aql_query_id on the block’s query attribute.
• Added a new PHP trait + allowed control mapping so aql_query_id is propagated into generated query args.
• Documented the new query_id control and added unit tests covering the new trait behavior.

File summaries

File	Description
tests/unit/Query_Id_Tests.php	Adds unit tests for the new Query ID processing + allowed control registration.
src/variations/controls.js	Registers the new query_id control and renders the new Query ID UI in the inspector.
src/components/query-id-control.js	Introduces the “Query identifier” TextControl that writes aql_query_id into block attributes.
readme.txt	Documents query_id in the supported controls list (with description).
readme.md	Documents query_id in the supported controls list.
includes/Traits/Query_Id.php	Adds server-side processing to pass aql_query_id into generated query args.
includes/Query_Params_Generator.php	Wires the new trait and maps query_id → aql_query_id in ALLOWED_CONTROLS.
extending-aql.md	Adds documentation/example for targeting a specific block by aql_query_id.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

includes/Traits/Query_Id.php currently has a PHP parse error (missing closing braces), which would break runtime loading.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The new identifier should be normalized/validated (e.g., trimming whitespace and rejecting non-scalar values) and corresponding edge-case tests should be added to prevent brittle targeting behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

src/components/query-id-control.js:33

• The control currently stores the raw TextControl value; whitespace-only identifiers (e.g. " ") will be treated as valid and persisted, which makes block targeting brittle. Consider trimming the value and clearing the attribute when the trimmed value is empty.

			onChange={ ( value ) =>
				setAttributes( {
					query: {
						...attributes.query,
						aql_query_id: value !== '' ? value : undefined,

includes/Traits/Query_Id.php:12

• process_aql_query_id() currently passes through whatever value is present, including whitespace-only strings or non-scalar types (e.g. arrays from REST params). That can lead to hard-to-debug identifiers and unexpected types being exposed in aql_query_vars / merged into query vars; trim and ensure the identifier is a non-empty scalar string before setting aql_query_id.

	public function process_aql_query_id() {
		$this->custom_args['aql_query_id'] = $this->get_custom_param( 'aql_query_id' );
	}

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite