Download the PHP package omaressaouaf/query-builder-criteria without Composer

Query Builder Criteria

Introduction:

Query Builder Criteria is a Laravel package that extends Spatie's Laravel Query Builder, providing a structured way to define query filters, sorting, includes, and search functionality using reusable criteria classes.

With this package, you can:

• ✅ Define query logic in a clean, structured manner
• ✅ Apply filters, sorts, includes, and field selections effortlessly
• ✅ Support search and full-text search and custom query aliases
• ✅ Merge multiple criteria dynamically for flexible querying

Built on top of Spatie’s Query Builder, this package removes repetitive query logic, keeping your controllers and models clean and maintainable. 🚀

🔗 Example:

Instead of manually handling query parameters, just define a Criteria Class:

And apply it with one line of code:

✨ No more manual query handling – just define once and reuse!

Table of Contents

• Installation
• Get Started
• Criteria configuration
  • Filters
  • Sorting
  • Includes
  • Field Selection
  • Search
  • Aliases
  • Advanced Features
• Applying Criteria to a Model
• Querying Data
• Passing Criteria to Scope
• Credits
• License

Installation

Install via Composer:

Publishing the Configuration

After installation, you can publish the package configuration file using:

This will create a configuration file in config/query-builder-criteria.php, allowing you to customize the default behavior.

Get Started

This package allows you to define query criteria for your models, enabling filtering, sorting, field selection, and more.

Example: Post Criteria

Let's say we have a Post model. We want to allow users to:

• Filter by title, id, and slug.
• Include related user model.
• Sort by published_at.
• Select specific fields like title and body.

We define these rules in a criteria class:

Now, in our Post model:

Then we can call the scope

Now we can query posts like this:

Criteria configuration

Filters

URL Query Example:

Configuration:

• filters: Allows filtering by title.
• exactFilters: Enables exact filtering on id and slug.
• belongsToFilters: Supports filtering by related user model.
• scopeFilters: Uses model scopes like published_before.
• trashedFilter: Enables soft-deleted filter. (Possible values : with, only)

Sorting

URL Query Example:

Configuration:

• defaultSorts: Defaults to sorting by created_at in descending order.
• sorts: Allows sorting by published_at and created_at.

Includes

URL Query Example:

Configuration:

• includes: Enables including related models (user).
• countIncludes: Enables including only count of related records (comments_count).
• existsIncludes: Enables including only whether related models exist (has_comments).

Field Selection

URL Query Example:

Configuration:

• defaultFields: Default fields returned in queries when nothing specified in query param.
• fields: Lists all fields that can be selected.

Search

URL Query Example:

Configuration:

• searches: Supports searching in slug, title, and user.name.
• fullTextSearches: Full-text search columns body and user.bio.
• splitSearchIntoTerms: Enable or Disable term splitting in searches.

Aliases

You can define an alias for a filter to keep your database structure hidden and make URLs more readable. For example, if your users table has a user_passport_full_name column, exposing it directly in the API isn't ideal. Instead, you can assign a more user-friendly alias:

URL Query Example:

Configuration:

This pattern is applicable for all filters, sorts and includes

Advanced Features

Advanced Filters, Sorting, and Includes

For more complex filters, sorts, and includes like specifying ignored and default values, custom callback filters and more you can override the following methods in your Criteria class, these will be merged with the declared properties

Example Configuration

Refer to the Spatie Query Builder Documentation for more details on defining advanced filters, sorts, and includes.

Applying Criteria to a Model

Use the QueryableByCriteria trait in your model:

Querying Data

Passing Criteria to Scope

You can also pass a criteria class directly to the queryByCriteria scope. This allows you to merge additional criteria with the default criteria for flexibility and reusability:

Credits

This package is based on Spatie's Laravel Query Builder.

Testing

Run unit tests:

License

This package is open-source and licensed under the MIT License.