docs(filters): document enhanced QueryParameter syntax on old filters

[vinceAmstoutz]

Completes #2203

And here to avoid these issues:

• ExistsFilter: properties must be associative array when used with QueryParameter, but not with ApiFilter core#7483
• With QueryParameter, it is not possible to set multiple filters for the same property core#7493
• :property key cannot be used in SearchFilter (Symfony only) core#7495

Main changes:

• Added examples for Date, Boolean, Numeric, Range, Exists, and Order filters using the QueryParameter approach. Included notes on configuring custom strategies, handling null values, and enabling filters for nested properties.
• Add other warnings to promote the QueryParameter attribute over ApiFilter, as the latter is deprecated and scheduled for removal in API Platform 5.0.
• Fix several typos

[ttskch]

@vinceAmstoutz

Thank you for improving the documentation. Please allow me to share my insights.

In v4.2.3, when setting filters using QueryParameter, declaring the key using the associative array index in the parameters argument is not possible, resulting in a 500 error with the message "A Parameter should have a key." Instead, you must use the key argument of QueryParameter.

- parameters: [
-     'search[:property]' => new QueryParameter(/* ... */)
+ parameters: [
+     new QueryParameter(key: 'search[:property]', /* ... */)

Also, directly passing a filter instance to the filter argument still mostly does not work correctly. Defining the filter service in services.yaml and passing the service ID works correctly in most cases (excluding #7493, #7494, and #7495).

For example, I have observed the following issues in my environment.

new QueryParameter(key: 'date', filter: new DateFilter())

• date[<after|before|strictly_after|strictly_before>] is not output in OpenAPI or Hydra's search.template, only date is output.
• Searching works.

new QueryParameter(key: 'id', filter: new RangeFilter())

• id[<lt|gt|lte|gte|between>] is not output in OpenAPI or Hydra's search.template, only id is output.
• Searching works.

new QueryParameter(key: ':property', filter: new PartialSearchFilter(), properties: ['title', 'note'])

• The query parameter :property is output in OpenAPI instead of title or note.
• {?title,note} is correctly output in Hydra's search.template.
• Searching does not work even when requesting with ?title={query} or ?note={query}.

new QueryParameter(key: 'title', filter: new PartialSearchFilter(), property: 'title')

• Both OpenAPI and Hydra output correctly, and searching works.
• However, in the case of BooleanFilter, NumericFilter, RangeFilter, etc., if the key is the property name itself, it works even if the property argument is omitted, but in the above case, omitting property causes an error because $property becomes null here.

new QueryParameter(key: 'comments.content', filter: new PartialSearchFilter(), property: 'comments.content')

• Nested properties are not parsed, and an error such as Error: Class App\\Entity\\Foo has no field or association named comments.content occurs at the DB layer.

new QueryParameter(key: 'exists[:property]', filter: new ExistsFilter(), properties: ['content', 'comments'])

• In OpenAPI... - The query parameter exists[:property] is output instead of exists[content] or exists[comments].
• Hydra's search.template correctly outputs {?exists[content],exists[comments]}.
• Searching does not work even when requesting with ?exists[content]=true or ?exists[comments]=false.
• Defining the following two parameters instead makes it work completely:

new QueryParameter(key: 'exists[content]', filter: new ExistsFilter(), property: 'content'),
new QueryParameter(key: 'exists[comments]', filter: new ExistsFilter(), property: 'comments'),

new QueryParameter(key: 'order[:property]', filter: new OrderFilter(), properties: ['id', 'date'])

• The query parameter order[:property] is output in OpenAPI instead of order[id] or order[date].
• Hydra's search.template correctly outputs {?order[id],order[date]}.
• Searching does not work even when requesting with ?order[id]=asc or ?order[date]=desc.
• Defining the following two parameters instead makes it work completely:

new QueryParameter(key: 'order[id]', filter: new OrderFilter(), property: 'id'),
new QueryParameter(key: 'order[date]', filter: new OrderFilter(), property: 'date'),

[aegypius]

Suggested change

	// This WILL restricts to only title and author properties
	// This WILL restrict to only title and author properties

restrict is a verb in this context

[aegypius]

Suggested change

	// This WILL restricts to only title and author properties
	// This WILL restrict to only title and author properties

Same as above

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

the section is actually called defaults

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

Same as above

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

Suggested change

	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the default section)
	# You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the "defaults" section)

[aegypius]

polish: I made a bunch of suggestions regarding spelling.‏