Getting Started

Update to v1.5.0 and review the package config first: the new subscription toggle is the quickest win if you are not using Mercure.
First use case: add a custom filter that compares enum values, or expose a string filter that accepts multiple values via StringComparisonExpression::values.
Minimal setup: publish/update config, register any custom filter or list resolver in a Laravel service provider, then test a list endpoint with enum, multi-value, and sort query parameters.
Look first at: custom filter docs, list/orderBy resolver docs, service-container binding docs, and subscription config.
No breaking changes are called out in v1.5.0; the release is mostly additive, with Symfony/Mercure-specific features that may not apply to every Laravel app.

Implementation Patterns

Enum filters: accept the request value, map it with Enum::tryFrom(), then compare against the enum in your custom filter. Return a clear 400 for invalid values.
Advanced orderBy: implement a custom list resolver and wire it into the list configuration. Keep an explicit allowlist of sortable fields before applying order clauses.
Multi-value string filters: pass an array into StringComparisonExpression::values and build IN/OR conditions deliberately; validate operators and value count.
Service-based filters: bind filter classes in Laravel’s container and reference them by class name as the service ID. This is useful when filters need repositories, config, or other dependencies.
Subscriptions: upgrade to mercure-bundle ^0.2 only if you use Mercure subscriptions; otherwise disable subscriptions through configuration to avoid unnecessary dependencies.
Symfony App namespace support: relevant only to Symfony ^4 bridge usage. In Laravel, keep using Laravel’s namespace and service-provider registration rather than relying on Symfony app-namespace behavior.
Integration tip: register filters/resolvers in a dedicated service provider and add feature tests that exercise enum comparison, multi-value filtering, and custom ordering together.

Do not assume the Symfony ^4 App namespace feature applies to Laravel; it is a Symfony integration feature.
Mercure subscription upgrades can require config or bundle changes. If subscriptions are not used, disable them explicitly.
Custom orderBy resolvers must whitelist sortable columns; never pass user input directly into order clauses.
Enum comparison depends on PHP enum support and how your ORM/database stores values. Handle invalid or missing enum cases gracefully.
Multi-value string filtering can grow query complexity quickly; cap the number of accepted values and validate input early.
Class-name service IDs only work if the class is resolvable in the container; missing bindings will fail at runtime.
For debugging, log the resolved filter/resolver and the final query; clear config cache after changing subscription settings.
Main extension points in v1.5.0: custom filters, custom list resolvers, StringComparisonExpression::values, service-container filter resolution, and subscription configuration.