PHPackages                             luchmewep/granular-search - 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. luchmewep/granular-search

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

luchmewep/granular-search
=========================

Granular Search and Aggregation provides four (4) usable traits for model controllers which are useful for searching and aggregation.

3.0(5y ago)0118MITPHP

Since Feb 17Pushed 5y ago1 watchersCompare

[ Source](https://github.com/luchmewep/granular-search)[ Packagist](https://packagist.org/packages/luchmewep/granular-search)[ Docs](https://github.com/luchmewep/granular-search)[ RSS](/packages/luchmewep-granular-search/feed)WikiDiscussions master Synced yesterday

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

GranularSearch
==============

[](#granularsearch)

[![Latest Version on Packagist](https://camo.githubusercontent.com/966e3f90111730a5232b626e398d37541fca0ab9888fcb7beb32e23626855356/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c7563686d657765702f6772616e756c61722d7365617263682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/luchmewep/granular-search)[![Total Downloads](https://camo.githubusercontent.com/07528e772890232c30ff1428bc919efa5887c62aef13c01335a1e363a7afa65b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c7563686d657765702f6772616e756c61722d7365617263682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/luchmewep/granular-search)

Granular Search is an Eloquent model utility for implementing searching, filtering, and sorting with fewer lines of code.

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

[](#installation)

Via Composer

```
$ composer require luchmewep/granular-search
```

Usage
-----

[](#usage)

To use this package, you have two options. You can either implement it on your Eloquent models, or you can just use the main method of this package which is the `getGranularSearch` (see `GranularSearchTrait`).

However, to fully utilize this package, the ***preferred way*** would be to implement the prepared Traits and Abstract Models. If still in doubt, you can just use the non-model intrusive way which is using the `GranularSearch` class itself.

### Implement on Eloquent Models

[](#implement-on-eloquent-models)

There are two (2) ways to implement Granular Search on Eloquent models:

1. By extending the `AbstractGranularModel` or `AbstractGranularUserModel` for User-based models. (**Highly Suggested**)

[![Using the Granular Abstract Class](images/implementing_abstract.jpg)](images/implementing_abstract.jpg)

2. By using the `GranularSearchableTrait` on your Eloquent models.

[![Using the GranularSearchableTrait](images/implementing_model_trait.jpg)](images/implementing_model_trait.jpg)

#### Extending the Abstract Models

[](#extending-the-abstract-models)

Currently, there are two (2) models to choose from. For models that are unrelated to authentication, you can just use the `AbstractGranularModel`. As for authentication-related ones, using `AbstractGranularUserModel` is advised.

These two abstract classes are not really hard to understand since they just use the `GranularSearchTrait` and `GranularSearchableTrait`. They are just prepared beforehand to minimize trait-related bugs.

[![Abstract class for auth-related models](images/abstract_user.jpg)](images/abstract_user.jpg)

[![Abstract class for non-auth related models](images/abstract_normal.jpg)](images/abstract_normal.jpg)

Once extended, you should set up these protected static fields.

```
// Model fields to be excluded from filtering
protected static $granular_excluded_keys = [];
// Model fields to use LIKE instead instead of equal
protected static $granular_like_keys = [];
// Relations to consider for filtering/searching
protected static $granular_allowed_relations = [];
// Relations to include on 'q' search (must be a subset of allowed relations array)
protected static $granular_q_relations = [];
```

[![](images/abstract_protected.jpg)](images/abstract_protected.jpg)

#### Tinker Examples

[](#tinker-examples)

- **Normal Search / Filter**

1. Filtering using model's own fields

[![tinker_model_search_non_q](images/tinker_model_search_non_q.jpg)](images/tinker_model_search_non_q.jpg)

2. Filtering using `q` as parameter

[![tinker_model_search_q](images/tinker_model_search_q.jpg)](images/tinker_model_search_q.jpg)

- **Relational Search / Filter**

3. Filtering through `relations` using other model's **prepended** fields

[![tinker_model_search_non_q_relations](images/tinker_model_search_non_q_relations.jpg)](images/tinker_model_search_non_q_relations.jpg)

4. Filtering through `relations` using `q` parameter

[![tinker_model_search_q_relations](images/tinker_model_search_q_relations.jpg)](images/tinker_model_search_q_relations.jpg)

### Implement Manually

[](#implement-manually)

If you are not prepared to try it out on your current Eloquent models, you might want to test it out first using the `GranularSearch` class itself. Since the getGranularSearch is a static method, we don't need to instantiate the GranularSearch class. Here are the parameters for the static method:

```
/**
 * Filter the model collection using the contents of the $request variable.
 *
 * @param Request|array $request Contains all the information regarding the HTTP request
 * @param Model|Builder $model Model or query builder that will be subjected to searching/filtering
 * @param string $table_name Database table name associated with the $model
 * @param array $excluded_keys Request keys or table column names to be excluded from $request
 * @param array $like_keys Request keys or table column names to be search with LIKE
 * @param string $prepend_key
 * @param bool $ignore_q
 * @return Model|Builder
 */

```

##### Tinker Examples

[](#tinker-examples-1)

1. Filtering using model's own fields

[![tinker_model_search_non_q](images/tinker_raw_search_non_q.jpg)](images/tinker_raw_search_non_q.jpg)

2. Filtering using `q` as parameter

[![tinker_model_search_q](images/tinker_raw_search_q.jpg)](images/tinker_raw_search_q.jpg)

Change log
----------

[](#change-log)

Please see the [changelog](changelog.md) for more information on what has changed recently.

Testing
-------

[](#testing)

```
$ composer test
```

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

[](#contributing)

Please see [contributing.md](contributing.md) for details and a todolist.

Security
--------

[](#security)

If you discover any security related issues, please email author email instead of using the issue tracker.

Credits
-------

[](#credits)

- [James Carlo Luchavez](https://github.com/luchmewep)
- [All Contributors](../../contributors)

License
-------

[](#license)

license. Please see the [license file](license.md) for more information.

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity56

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 ~16 days

Total

5

Last Release

1842d ago

Major Versions

1.0.1 → 2.0.02021-03-17

2.0.1 → 3.02021-04-26

### Community

Maintainers

![](https://www.gravatar.com/avatar/9751834583538187236ea6491879aa80263a43dd036aa4e4fd0a71f721a0bed4?d=identicon)[jamescarloluchavez](/maintainers/jamescarloluchavez)

---

Top Contributors

[![luchtech](https://avatars.githubusercontent.com/u/26067874?v=4)](https://github.com/luchtech "luchtech (15 commits)")

---

Tags

laravelGranularSearch

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/luchmewep-granular-search/health.svg)

```
[![Health](https://phpackages.com/badges/luchmewep-granular-search/health.svg)](https://phpackages.com/packages/luchmewep-granular-search)
```

###  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)[romanstruk/manticore-scout-engine

Laravel Manticore Scout Engine

4818.1k](/packages/romanstruk-manticore-scout-engine)[internachi/blade-alpine-instantsearch

Algolia instant search as Blade/Alpine.js components

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

A simple to implement Search for your Application

101.5k](/packages/remoblaser-search)

PHPackages © 2026

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