Eloquent Filter Laravel Package

Getting Started

The v1.2.0 release adds a single feature — an order rule — so treat this as a small, additive upgrade rather than a migration. Confirm it's non-breaking by checking the diff for changes to existing rule signatures before bumping in production.

Minimal path to first value:

1. composer update <vendor>/<package> and confirm v1.2.0 in composer.lock.
2. Read the new rule class and its test file first — the release note ("add order rule") is terse, and the tests are the authoritative spec for accepted inputs, comparison strictness, and failure messages.
3. Grep the package for how the rule is registered (validation rule string, Rule object, or query scope). This determines whether you use it as 'order', new OrderRule(...), or a builder method.
4. Apply it to one existing form request or query and run the test suite.

The most likely first use case: validating that a submitted collection or set of sort values is a contiguous/valid ordering before persisting it (reordering rows in an admin UI, drag-and-drop lists, sequenced line items). If instead it's a query-side ordering helper, the first use case is replacing hand-rolled orderBy whitelists in a listing endpoint.

Start where you already have ad-hoc ordering logic — that's where the rule pays for itself immediately and where a behavioural mismatch will surface fastest.

Implementation Patterns

Form request usage. Prefer the rule in a FormRequest over inline $request->validate() calls so the contract is reusable and testable. If the rule takes constructor arguments (a column, a list of allowed values, a sibling field), instantiate it explicitly — string aliases rarely expose parameters.

Pair with array/distinct rules. Ordering validation almost always needs companion rules. Validate the container shape first, then the ordering constraint, so failures read clearly rather than surfacing as a single opaque message.

Compose, don't replace. If the rule validates relative order only, keep your existing exists/integer/min rules alongside it. Rules that assume well-formed input fail confusingly when run against raw request data.

Wrap it for domain reuse. If you apply the same ordering constraint in multiple requests, extract a small Rule subclass or a trait method returning the configured rule. This keeps constructor arguments in one place when the package changes them.

Query-side integration. If the release adds ordering to a query builder, funnel all user-supplied sort input through it rather than passing request values into orderBy directly. Keep the rule adjacent to the pagination logic in a repository or scope so the mapping from request key to column lives in exactly one place.

Testing. Add a focused feature test asserting: valid order passes, a swapped pair fails, a gap/duplicate fails, and the failure message is the one users will see. Because the feature is new, pin the expected message — if a patch release rewords it, you want a failing test, not a silent UX change.

Progressive rollout. Additive rules are low risk; ship behind your normal release, but re-run any tests that assert on ValidationException message arrays, since a new rule can shift error bag keys.

Gotchas and Tips

The release note is thinner than the change. "Add order rule" tells you nothing about edge cases. Before relying on it, check: strict vs loose comparison ('1' vs 1), behaviour with nulls and empty arrays, whether ties are errors, and whether it's zero- or one-indexed. Each of these is a plausible bug source in a first release of a rule like this.

Nulls and gaps are the classic trap. Ordering rules frequently accept [1,2,3] and reject [1,3] — but many implementations silently allow nulls through. Test your own payloads rather than assuming.

Don't leak column names into messages. If the rule echoes user input back in the failure message, and that input reaches an admin UI, you've created a minor injection surface. Validate and sanitise before display.

Watch for implicit registration. If the rule is auto-discovered or aliased via a service provider, a cached config (php artisan config:cache) can mask the new rule until you clear it. If the rule "doesn't exist" after updating, clear caches before debugging code.

Localisation. New rules ship with English messages only, typically. Add translations for locales you serve, and verify pluralisation for list-style messages.

Debugging. For an opaque failure, dump $validator->errors()->toArray() rather than the boolean result — rules often fail for a companion-reason you didn't anticipate. For query-side behaviour, ->toSql() with bindings beats guessing.

Extension points. Look for a macro, a config array of accepted comparators, or a protected method you can override. If the rule doesn't support your case (e.g. ordering across nullable groups), subclass rather than forking the package — a fork makes the next composer update painful.

Pin the version. A single-feature release on a young rule is likely to get corrective patches. "^1.2" is reasonable; "*" is not, especially if you've written tests against its exact message strings.