PHPackages                             hongxunpan/eloquent-query-dsl - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. hongxunpan/eloquent-query-dsl

ActiveLibrary[Database & ORM](/categories/database)

hongxunpan/eloquent-query-dsl
=============================

Adapter-friendly Eloquent query DSL core for list search, filters, sorting, and pagination facts

0.3.1(1mo ago)017MITPHPPHP ^8.0.20CI passing

Since May 28Pushed 1mo agoCompare

[ Source](https://github.com/HongXunPan/eloquent-query-dsl)[ Packagist](https://packagist.org/packages/hongxunpan/eloquent-query-dsl)[ Docs](https://github.com/HongXunPan/eloquent-query-dsl)[ RSS](/packages/hongxunpan-eloquent-query-dsl/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (10)Versions (6)Used By (0)

Eloquent Query DSL
==================

[](#eloquent-query-dsl)

[简体中文文档](./README.zh-CN.md)

`hongxunpan/eloquent-query-dsl` is an adapter-friendly Eloquent / Builder query DSL core for list endpoints. It turns recurring list-query concerns—`search`, `filter`, `between`, `sort`, and pagination input—into explicit, testable, reusable query definitions.

It does **not** own HTTP requests, response envelopes, business exceptions, pagination responses, authorization, tenant rules, or resource-specific field policies. Those concerns belong in your application adapter or service layer.

Current Status
--------------

[](#current-status)

This repository is in **pre-1.0** development.

Already in place:

- Composer package and namespace `HongXunPan\EloquentQueryDsl\`;
- recommended entrypoint: `QueryDsl` / `QueryDslResult`;
- query capability declaration model: `DslQueryDefinition`;
- default input parser, custom parameter maps, flat input, and fully custom parser contracts;
- `search / filter / between / sort` readers and builder appliers;
- neutral filter normalizer contract and filter-value facts;
- safe identifier validation for fields, entity aliases, and each segment in relation paths;
- pagination facts and pagination policy limits;
- PHPUnit, legacy smoke tests, PHPStan level 8, PHP-CS-Fixer, Composer audit, and GitHub Actions matrix;
- release checklist and `0.1.0` pre-release changelog section.

Still required before public release:

- final commit and remote CI observation;
- `0.1.0` tag and GitHub Release;
- Packagist synchronization;
- application-side integration against a pinned tag and application smoke tests.

Documentation
-------------

[](#documentation)

- [CHANGELOG](./CHANGELOG.md)
- [Contribution Guide](./CONTRIBUTING.md)
- [Security Policy](./SECURITY.md)
- [Public Contracts and Stability](./docs/public-contracts.md)
- [API Reference and Extension Points](./docs/api-reference.md)
- [Integration Guide](./docs/integration-guide.md)
- [Query Capability Matrix](./docs/query-capability-matrix.md)
- [High-value Canonical Examples](./docs/high-value-canonical-examples.md)
- [Release Checklist (Chinese)](./docs/%E5%8F%91%E5%B8%83%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95.zh-CN.md)
- [MIT License](./LICENSE)

If you are evaluating whether a list-query abstraction belongs in a shared Composer package, start with the selection summary and boundaries below. If you are ready to integrate the package, read the integration guide and canonical examples.

Selection Summary
-----------------

[](#selection-summary)

This package is not an API framework, a repository layer, or a response-format library. It is a low-business-coupling query protocol core for Eloquent list queries.

Typical reasons to choose it:

- you repeatedly implement keyword search, field filters, range filters, sorting, and pagination input across list endpoints;
- you want a declarative definition to own allowed fields, sort directions, required filters, default sorts, and strict mode;
- you want shared core logic to return neutral query facts while application code keeps responses, exceptions, authorization, and pagination execution;
- you need one query protocol and regression suite across multiple Eloquent-based projects;
- you want relation search/filter, derived filters, keyword search, and default sorting semantics to be explicit and testable.

Typical reasons not to choose it:

- you only have one temporary list endpoint and no reuse or maintenance pressure;
- you expect the package to return `{ page, list }`, HTTP responses, or business error codes;
- you want to put authorization, tenant isolation, resource field policies, or business defaults into shared core;
- you need DTO/projection/presentation restructuring. Use a projection layer or application presenter instead.

Core vs Application Responsibilities
------------------------------------

[](#core-vs-application-responsibilities)

Shared core owns:

- parsing external input into `DslQueryInput / DslPageInput`;
- query capability declarations;
- applying `search / filter / between / sort` to an Eloquent Builder;
- neutral filter values and pagination facts;
- extension contracts such as `DslInputParser`, `DslInputMap`, `DslFilterNormalizer`, and `DslPaginationPolicy`.

Application code owns:

- reading HTTP requests;
- adapting application validation / normalization into `DslFilterNormalizer`;
- translating exceptions;
- executing `count`, `paginate`, cursor pagination, export limits, or response wrapping;
- authorization, tenant isolation, and business default scopes;
- resource-specific field allowlists.

Do not push the following into shared core:

- `App\` namespace classes;
- framework-specific adapters;
- `ApiException`, HTTP status, or response envelopes;
- application pagination traits;
- legacy compatibility runtimes;
- resource permissions or field policies.

30-second Quick Start
---------------------

[](#30-second-quick-start)

```