Laravel Natural Where Laravel Package

Product Decisions This Supports

• Build vs. buy on query ergonomics: this package is a thin, low-cost dependency that converts verbose where(...)->orWhere(...) chains into readable, intent-revealing macros. For teams whose Eloquent scopes are the main source of review friction and bug reports, adopting is cheaper than building and maintaining an internal macro layer.
• Feature/roadmap input — filtering and search surfaces: the presence of a naturalOrWhere macro signals the package's core value is composing OR-conditions across user-driven filters (admin search screens, reporting filters, saved-view builders). If your roadmap includes richer filtering or "advanced search," this is a candidate primitive rather than a bespoke implementation.
• Support-matrix decision (v3.1.0): the release adds Laravel 13 while retaining Laravel 5.6 and 8. That is an unusually wide compatibility claim. Treat it as a decision point: adopt only if your application's actual Laravel version is explicitly covered by the package's CI, and record which version you validated on.
• Upgrade sequencing: because this is a dependency, the release gives you a low-risk path to evaluate Laravel 13 readiness in isolation, ahead of committing the framework upgrade. Useful as a canary for how much of your dependency graph blocks a major-version move.
• Defect-driven prioritization: naturalOrWhere previously not returning the query builder is a correctness issue, not cosmetics — broken chaining can silently drop or misapply conditions in filter logic. If any shipped code path uses this macro, schedule a patch-level bump and a targeted regression check.

When to Consider This Package

Adopt when:

• Your team writes and reviews many multi-condition OR filters in Eloquent, and readability/review speed is a measurable pain.
• You are on a Laravel version the package explicitly tests (verify against its CI matrix, not just the README), and you can pin a minor version.
• The macro surface you need is small and stable — a handful of conditions, not a full query DSL or a third-party filter API.
• You want a patch bump anyway for the naturalOrWhere return-value fix, and your existing usage benefits from correct chaining.

Look elsewhere or stay in-house when:

• You need complex boolean grouping semantics, guaranteed SQL-level control, or performance-sensitive queries where an abstraction layer obscures the generated SQL.
• You are on a Laravel version outside the tested matrix — a "supports 5.6 through 13" claim is a maintenance signal, not proof; each combination is unlikely to be equally exercised.
• Your organization restricts dependency count or requires active, recent release cadence for small utility packages.
• You have only a handful of OR conditions; plain Eloquent is clearer than introducing an abstraction with its own bug history.

How to Pitch It (Stakeholders)

To executives: a small, targeted library that makes our database query code easier to read and review, reducing the chance of subtle filter bugs in admin and reporting screens. The latest release adds compatibility with the newest Laravel version and fixes a defect where one of its query helpers failed to return the query object — the kind of bug that can quietly cause incorrect filter results. Cost is a dependency bump plus a short verification pass.

To engineering: v3.1.0 adds Laravel 13 support (5.6 and 8 retained) and corrects naturalOrWhere to return the builder, restoring chainability. Action: bump to the patch, add a regression test covering any OR-condition filter that uses the macro, and confirm our Laravel version is in the package's tested matrix before relying on it for new filtering work. No breaking API changes indicated in this release.