PHPackages                             alimousavi/filoquent - 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. [Search & Filtering](/categories/search)
4. /
5. alimousavi/filoquent

ActiveLibrary[Search & Filtering](/categories/search)

alimousavi/filoquent
====================

A powerful Laravel package for filtering Eloquent models using HTTP query parameters.

v1.2.1(9mo ago)13774↓48%MITPHPPHP >=8.0

Since Jun 21Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/alimousavidev/filoquent)[ Packagist](https://packagist.org/packages/alimousavi/filoquent)[ Docs](https://github.com/alimousavidev/filoquent)[ RSS](/packages/alimousavi-filoquent/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (1)Versions (15)Used By (0)

Filoquent
=========

[](#filoquent)

Filoquent is a powerful Laravel package that allows you to filter Eloquent models using HTTP query parameters seamlessly. This package simplifies the process of building dynamic query filters in your Laravel applications, making it easier to handle complex filtering logic directly through query strings.

Features
--------

[](#features)

- **Dynamic Query Filtering:** Filter Eloquent models dynamically based on HTTP query parameters.
- **Easy Integration:** Quickly integrate with your existing models and controllers.
- **Extensible:** Create custom filters to extend the package functionality.
- **Supports Relationships:** Filter models based on relationships and nested relationships.
- **Flexible and Configurable:** Configure default behaviors and override them as needed.

Installation
------------

[](#installation)

You can install the package via Composer:

```
composer require alimousavi/filoquent
```

Usage
-----

[](#usage)

### Use the Trait

[](#use-the-trait)

To start using the package, simply use the `Filterable` trait in your Eloquent models:

```
use AliMousavi\Filoquent\Filterable;

class Post extends Model
{
    use Filterable;
}
```

### Create a Filter Class

[](#create-a-filter-class)

Filoquent provides an artisan command to generate filter classes easily:

```
php artisan make:filter Blog\PostFilter
```

This command creates a new filter class in the `app/Filters` directory.

### Defining Custom Filters

[](#defining-custom-filters)

You can define custom filters by creating filter classes. Each filter class should extend the `FilterAbstract` class:

```
namespace App\Filters\Blog;

use AliMousavi\Filoquent\Filters\FilterAbstract;

class PostFilter extends FilterAbstract
{

    /**
     * @var array
     *
     * An array of fields that can be filtered.
     * They key of array is the field being filtered and the value is the type of the field.
     */
    protected array $filterables = [
        'title' => self::TYPE_STRING,
        'author' => self::TYPE_STRING,
    ];

    /**
     * @var array
     *
     * An array of fields that can be searched.
     */
    protected array $searchables = [
        'title',
        'content'
    ];

    /**
     * @var array
     *
     * An array of fields that can be used for ordering.
     */
    protected array $orderBy = [
        'published_at' => 'desc',
        'title'
    ];

    public function title(string $title){
        $this->builder->where('title', 'like', "%$title%");
    }

    public function author(string $author){
        $this->builder->whereHas('author', function ($query) use ($author) {
            $query->where('name', 'like', "%$author%");
        });
    }
}
```

### Applying Filters

[](#applying-filters)

In your controller, you can now apply filters based on query parameters:

```
use Illuminate\Http\Request;
use App\Models\Blog\Post;
use Filters\Blog\PostFilter;
use Http\Resources\Blog\PostResource;

class PostController extends Controller
{
    public function index(Request $request, PostFilter $filter)
    {
        $posts = Post::query()->filter($filter)->paginate();

        return PostResource::collection($posts);
    }
}
```

### Search Feature

[](#search-feature)

Filoquent supports searching across multiple columns, including relationships using dot notation.

#### Example: Basic Search

[](#example-basic-search)

To search across specified fields, include the search query parameter in your request:

```
GET /api/users?search=john
```

In your filter class, define the `searchables` array:

```
protected array $searchables = ['name', 'email'];
```

#### Example: Nested Search with Dot Notation

[](#example-nested-search-with-dot-notation)

To search within relationships, use dot notation:

```
GET /api/users?search=doe
```

Define nested searchable fields in your filter class:

```
protected array $searchables = ['name', 'profile.bio', 'profile.location'];
```

This will search the `name` field on the `users` table and the `bio` and `location` fields on the related `profile` model.

---

### Ordering

[](#ordering)

Filoquent allows ordering results by fields that **you explicitly allow**, and supports both **simple column sorting** and **custom method-based sorting**.

#### Usage (Request Example)

[](#usage-request-example)

```
GET /users?order_by=name:asc,created_at:desc

```

- You can provide multiple sort instructions separated by commas.
- Each field can be sorted `asc` or `desc` (`asc` is default if not specified).

#### Define Allowed Fields

[](#define-allowed-fields)

In your filter class, define:

```
protected array $orderables = [
    'name',
    'created_at',
    'custom_field' => 'sortByCustomField',
];
```

Optionally define default sort if the user provides no sort params:

```
protected array $orderBy = [
    'name' => 'asc',
];
```

#### Custom Sorting Methods

[](#custom-sorting-methods)

If you need advanced logic, define a method and pass its name in `orderables`.

```
protected array $orderables = [
    'score' => 'sortByScore',
];

public function sortByScore(string $direction): void
{
    $this->builder->orderByRaw("some_custom_expression $direction");
}
```

Contributing
------------

[](#contributing)

Contributions are welcome!

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT](https://choosealicense.com/licenses/mit/).

Credits
-------

[](#credits)

- [Ali Mousavi](https://github.com/alimousavidev)

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance57

Moderate activity, may be stable

Popularity24

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~68 days

Recently: every ~94 days

Total

7

Last Release

285d ago

PHP version history (2 changes)v1.1.0PHP ^8.0

v1.1.2PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/490876a92d510a97e9a9251f9b10a27282a948c9a7f542e8ae859842a18c0c6e?d=identicon)[alimousavidev](/maintainers/alimousavidev)

---

Top Contributors

[![alimousavidev](https://avatars.githubusercontent.com/u/7754232?v=4)](https://github.com/alimousavidev "alimousavidev (19 commits)")

### Embed Badge

![Health badge](/badges/alimousavi-filoquent/health.svg)

```
[![Health](https://phpackages.com/badges/alimousavi-filoquent/health.svg)](https://phpackages.com/packages/alimousavi-filoquent)
```

###  Alternatives

[mailerlite/laravel-elasticsearch

An easy way to use the official PHP ElasticSearch client in your Laravel applications.

934529.3k2](/packages/mailerlite-laravel-elasticsearch)[jeroen-g/explorer

Next-gen Elasticsearch driver for Laravel Scout.

397612.3k](/packages/jeroen-g-explorer)[swisnl/laravel-fulltext

Fulltext indexing and searching for Laravel

184104.5k6](/packages/swisnl-laravel-fulltext)[romanstruk/manticore-scout-engine

Laravel Manticore Scout Engine

4818.1k](/packages/romanstruk-manticore-scout-engine)[statamic-rad-pack/meilisearch

meilisearch search driver for Statamic

1661.7k](/packages/statamic-rad-pack-meilisearch)[internachi/blade-alpine-instantsearch

Algolia instant search as Blade/Alpine.js components

1940.9k](/packages/internachi-blade-alpine-instantsearch)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)