Skip to content

docs(filters): present-tense 5.0 filter changes - #2332

Merged
soyuka merged 1 commit into
api-platform:mainfrom
soyuka:docs/filters-5.0-present-tense
Sep 13, 2026
Merged

docs(filters): present-tense 5.0 filter changes#2332
soyuka merged 1 commit into
api-platform:mainfrom
soyuka:docs/filters-5.0-present-tense

Conversation

@soyuka

@soyuka soyuka commented Sep 12, 2026

Copy link
Copy Markdown
Member

Summary

The 5.0 filter docs still spoke about main (5.0) in the future tense and never documented what
actually shipped in api-platform/core#8351 (d37a75379). This PR aligns core/filters.md,
core/doctrine-filters.md, and core/jsonapi.md with the shipped code.

  • ComparisonFilter [between] is real: documented as a first-class operator with a worked example
    and its generated SQL, replacing the "In 4.4 there is no dedicated between operator" / "in 5.0 it
    also gains…" future-tense language. Also fixed a stale "five OpenAPI parameters" count (now six,
    between included).
  • RangeFilter is deprecated since 4.4, removed in 6.0 (not 5.0) — added a proper [!WARNING]
    deprecation callout on the ## Range Filter section itself and synced the core/filters.md list
    entry, which only said "legacy" before.
  • DateFilter and ExistsFilter no longer extend AbstractFilter (standalone classes as of 5.0).
    Documented this as an internal rewrite only — URL syntax and behavior are unchanged; it only
    matters for anyone who subclassed those filters directly.
  • PropertyAwareFilterInterface::getProperties() is now a real interface method (previously a
    commented-out // TODO: 5.x uncomment method). Updated the custom-filter example under "Decorate
    a Doctrine filter using Symfony" so SearchTextAndDateFilter actually implements the interface
    with both setProperties()/getProperties(), and explained what getProperties() returns.
  • core/jsonapi.md: use_iri_as_id already defaults to false on main (5.0) —
    Configuration.php:103-104 (booleanNode('use_iri_as_id')->defaultFalse()). Rewrote the "will
    become the default in 5.x" line to describe the current default and pointed to
    core/upgrade-guide.md for the migration (kept minimal — another agent owns that section).
  • core/filters.md: enable_link_security was removed from Configuration.php entirely in 5.0
    (feat!: remove deprecated APIs scheduled for 5.0 core#8367 — the 4.4 deprecation said "always enabled and will be removed in API
    Platform 5.0"). Replaced the "enable it first" instructions for ReadLinkParameterProvider with a
    one-line note, matching the phrasing used for the same change in docs: remove config keys deleted in 5.0, document %param% resolution #2334
    (core/subresources.md).

Verified against source (core upstream/main @ d37a75379, PR #8351)

  • ComparisonFilter::OPERATOR_BETWEEN = 'between' — both
    src/Doctrine/Orm/Filter/ComparisonFilter.php and the ODM equivalent.
  • Value separator is a literal .. (explode('..', $value, 2)), both bounds must be is_numeric
    (coerced to int/float) — [between] does not accept DateTime bounds, only combining
    gte/lte does.
  • ORM: ExactFilter::apply() emits sprintf('%1$s.%2$s BETWEEN :%3$s_1 AND :%3$s_2', ...) when
    $context['operator'] === ComparisonFilter::OPERATOR_BETWEEN, or collapses to = when both
    bounds are equal.
  • ODM: no native BETWEEN; ComparisonFilter::applyBetween() expands to a gte/lte pair instead.
  • RangeFilter docblock: @deprecated since API Platform 4.4: ... This filter is removed in 6.0
    (both ORM and ODM RangeFilter.php).
  • DateFilter/ExistsFilter class declarations changed from extends AbstractFilter (4.4) to
    standalone final class ... implements FilterInterface, ..., PropertyAwareFilterInterface (main).
  • PropertyAwareFilterInterface::getProperties(): ?array is a real abstract method on main.
  • Configuration.php:103->booleanNode('use_iri_as_id')->defaultFalse().
  • git grep -n enable_link_security upstream/main -- src/ returns nothing (only a hit on
    upstream/4.4, where it's still present but deprecated).

A note on commit 1 and pre-existing Prettier drift

core/doctrine-filters.md and core/filters.md came into main via #2316 already Prettier-dirty
(npx prettier@3.9.5 --check fails on upstream/main for these two files before this PR). Since
Prettier reformats the whole file rather than just touched hunks, commit 1
(docs(filters): present-tense 5.0 filter changes) unavoidably carries that pre-existing reflow
alongside the content changes — there wasn't a safe way to isolate a prettier-only commit ahead of
it without a history rewrite, which I avoided. The repo-wide prettier --check passes clean as of
this PR's tip.

Left untouched (per scope)

  • The #[ApiFilter] "scheduled for removal in API Platform 5.0" [!WARNING] blocks at
    core/doctrine-filters.md (Nested Properties / Enabling a Filter for All Properties sections) —
    another agent is fixing this wording on the 4.3 branch; touching it here would conflict on
    merge-up.
  • core/configuration.md and core/subresources.md — owned by another agent on this same
    workstream.

Test plan

  • npx prettier@3.9.5 --check "**/*.md" --prose-wrap always passes repo-wide.
  • Docs build/preview (not run locally; CI covers this).

@soyuka
soyuka force-pushed the docs/filters-5.0-present-tense branch from e80481d to 9a8f31e Compare September 13, 2026 07:50
@soyuka
soyuka merged commit 880e2ef into api-platform:main Sep 13, 2026
3 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.

1 participant