Skip to content

Filter conditions: ?field[neq]=x, ?field[empty]=1, ?field[not_empty]=1, ?field[contains]=x - #35

Merged
daedeloth merged 3 commits into
masterfrom
claude/project-thread-dgci68
Nov 20, 2026
Merged

daedeloth merged 3 commits into
masterfrom
claude/project-thread-dgci68

Conversation

@daedeloth

@daedeloth daedeloth commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Requested by Thijs · project thread

First of a chain of four (charon → charon-laravel → laravel-table → laravel-charon-frontend) so the catlab-events admin can list e.g. every event whose event_url is filled in.

Syntax

A plain parameter still filters on equality (?name=Foo), and a list (?status[]=a) is passed on as before. A condition is an array key, one parameter per condition, so several combine:

Request Matches
?name[eq]=Bolt same as ?name=Bolt
?name[neq]=Bolt not Bolt, rows without a value included (adapter)
?name[contains]=ol only on searchable() fields
?url[empty]=1 / ?url[not_empty]=1 null or '' / the opposite

With JSON:API: filter[status][neq]=sold.

Safety (from the review)

  • An unknown condition, or one the field does not allow, throws InvalidFilterException, which is an InputDataException and becomes a 400 in charon-laravel.
  • Entity filter methods opt in by type. A filter<Name>() method whose second parameter is typed ConditionFilter (new subclass of Filter, detected with reflection) gets the filter object for every operator: filter<Name>($query, ConditionFilter $filter, $context, $entityClass). A method with the old ($query, $value, $operator, …) signature keeps getting = and SEARCH, and NEQ / EMPTY / NOT_EMPTY on its field are refused. Old methods may ignore $operator; Eukles' Event::filterTypeString would return X for "is not X".
  • FilterCollection::getFromName() / getFromDisplayName() return only an EQ or SEARCH filter, so a policy checking "owner is me" can't be fooled by owner[neq]=me. getAllFromName() returns every filter on a field.
  • Transformers run on compared values only, not on empty, not_empty or contains.
  • conflict: charon-laravel <1.13: the old adapter would turn EMPTY into col = 'EMPTY' and return nothing.
  • The OpenAPI filter description names the conditions.
  • Docs: docs/050-filters.md.

Tests

tests/FilterOperatorTest.php; full suite 153 tests OK locally. The ConditionFilter opt-in is covered by integration tests in charon-laravel#9: one method that takes a ConditionFilter and one with the old signature.

Release

Suggested tag v1.13.0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WpWbf8G82YF31PfRq1ggTi

A filterable field still filters on equality with a plain parameter
(?name=Foo). An array picks the operator: ?name[op]=contains&name[value]=Foo,
?url[op]=not_empty. FilterOperator maps the request names to the operators a
QueryAdapter receives (catlab/base EQ, NEQ and SEARCH, plus new EMPTY and
NOT_EMPTY). An unknown operator, or one without the value it needs, filters
nothing. RequestResolver transforms only the value of such an array.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WpWbf8G82YF31PfRq1ggTi
Replaces the field[op]/field[value] shape from the previous commit, after
review: one parameter per condition, so several combine (a range later) and
JSON:API reads filter[status][neq]=sold.

- An unknown condition, or one the field does not allow, throws
  InvalidFilterException (400) instead of silently returning everything.
- contains only on searchable() fields; a searchable-only field only searches.
- A list (?status[]=a) is passed on with the plain operator, as before.
- Entity filter<Name>() methods only get NEQ/EMPTY/NOT_EMPTY when the entity
  implements FiltersWithOperators; otherwise the condition is refused, since
  such methods may ignore the operator.
- FilterCollection::getFromName()/getFromDisplayName() only return an EQ or
  SEARCH filter, so a policy checking 'owner is me' cannot be fooled with
  owner[neq]=me; getAllFromName() returns every filter on a field.
- Transformers run on each compared value, not on empty/not_empty/contains.
- The OpenAPI filter description names the conditions.
- conflict with charon-laravel <1.13, which would run EMPTY as col = 'EMPTY'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WpWbf8G82YF31PfRq1ggTi
@daedeloth daedeloth changed the title Filter operators: is not, contains, is empty, is not empty Filter conditions: ?field[neq]=x, ?field[empty]=1, ?field[not_empty]=1, ?field[contains]=x Nov 19, 2026
Replaces the FiltersWithOperators marker interface (Thijs' suggestion): a
filter<Name>() method whose second parameter is typed ConditionFilter (a new
subclass of Filter, found with reflection) gets the filter object for every
operator: filter<Name>($query, ConditionFilter $filter, $context, $entityClass).
A method with the old ($query, $value, $operator, ...) signature keeps getting
= and SEARCH; NEQ / EMPTY / NOT_EMPTY on its field are refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WpWbf8G82YF31PfRq1ggTi
@daedeloth
daedeloth merged commit 1c3087b into master Nov 20, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants