PHPackages                             query-grid/query-grid - 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. query-grid/query-grid

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

query-grid/query-grid
=====================

Query builder and DataGrid

0101[3 issues](https://github.com/query-grid/query-grid/issues)PHP

Since Oct 17Pushed 7y ago3 watchersCompare

[ Source](https://github.com/query-grid/query-grid)[ Packagist](https://packagist.org/packages/query-grid/query-grid)[ RSS](/packages/query-grid-query-grid/feed)WikiDiscussions master Synced 3d ago

READMEChangelogDependenciesVersions (2)Used By (0)

Query Grid
----------

[](#query-grid)

Framework Agnostic DataGrid / Query Builder implementation.

*Everybody loves badges, check ours out:*

[![Build Status](https://camo.githubusercontent.com/5144ccfacd461d5ed72d15149f89d3197d1b09af0d577a2d338c0c039bd4cb5d/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f71756572792d677269642f71756572792d677269642f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/query-grid/query-grid)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/f00612224b94af6fa3154be792d2dd888f28172593d0e46e6e2aef67eae8316e/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f71756572792d677269642f71756572792d677269642f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/query-grid/query-grid/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/b65aca44d83cffa58954f15af22371c4088624a93b356ca4f5ecafa45ad9c105/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f71756572792d677269642f71756572792d677269642f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/query-grid/query-grid/?branch=master)[![StyleCI](https://camo.githubusercontent.com/4ef9695f26bf243f8c16f7ce8757fe380cf5b32f54555e200ff917f60e2f0f60/68747470733a2f2f7374796c6563692e696f2f7265706f732f3135313838353437322f736869656c64)](https://styleci.io/repos/151885472)

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

[](#installation)

`composer require query-grid/query-grid`

Usage
-----

[](#usage)

*You'll need to create an implementation of the `QueryGrid\QueryGrid\Contracts\DataProvider` interface in order to query the data.*

```
$grid = new \QueryGrid\QueryGrid\Grid($dataProvider);

$grid->setResource('users'); // The resource sent to the data provider for the query.

$grid->addColumn('id', '#');
$grid->addColumn('name', 'Name');
$grid->addColumn('started', 'Start Date');

$result = $grid->getResult();
```

if you need to do more with columns, the `addColumn` method returns the column, so you can set the field mapping, filters, formatting, mark as sortable or queryable:

```
$column = $grid->addColumn('age', 'Age');
$column->fromField('dob');
$column->sortable();
$column->addFilter(Filter::LESS_THAN);
$column->formatter(new DateDiff('Y-m-d', '%y'));
```

Filters and queries
-------------------

[](#filters-and-queries)

What are filters and what are queries?

In this package, a filter is a field which, when set, it's value MUST match, so if you have 5 filters, and they've all been provided, all 5 of the filters must match.

A query is one string which can match many fields, but only one of the fields need to match.

For example, if you have a user with 'hobbies' and 'work\_history' fields, you could mark them both as queryable, then provide a query string which will search both fields return the row if either field matches.

If the user also as `date_of_birth`, `role`, and `name` fields, and you apply filters to them, if the filter is provided, it `MUST` match.

You can provide a query and filters in the same request too.

*Just because this is how I say that they should work in the package, unless you're using an officially supported `DataProvider` then I can not guarantee this be the case, in fact, if you would rather it worked a different way, I recommend creating your own data provider to treat filters, sorting and queries any way you want.*

Using queries, filters and sorting
----------------------------------

[](#using-queries-filters-and-sorting)

when you call `$grid->getResult()` you can optionally pass through an array represending the query. The array can have four optional params:

- filters
- query
- sort
- page

Of these, page is related to pagination, telling the grid the current page for data.

### Filters

[](#filters)

Filters are a `key:value` representation of a filter query.

The filter key is defined automatically when you add a filter to the grid column.

```
$column = $grid->addColumn('name', 'Full Name');
$column->fromField('full_name');
$column->addFilter(Filter::CONTAINS);
$column->addFilter(Filter::STARTS_WITH);
$column->addFilter(Filter::ENDS_WITH);
```

This definition does three things:

- Defines a grid column with the key `name` and label `Full Name`
- Defines a field `full_name` which we map the field from
- adds a `CONTAINS` filter to the query.

when you call `$grid->getResult()`, if you pass the following array:

```
$grid->getResult([
    'filters' => [
        'name.con' => 'dre',
    ],
]);
```

This will create a `Filter::CONTAINS` query on the `full_name` field with the value `dre`.

```
$grid->getResult([
    'filters' => [
        'name.st' => 'and',
    ],
]);
```

Will create a `Filter::STARTS_WITH` query.

The dot syntax for keys, as you probably can tell, follows a `{key}.{filter}` syntax.

When converting the columns to arrays, it includes an array of filters on the fields:

```
[
    [
        'key' => 'name',
        'label' => 'First Name',
        'sortable' => false,
        'queryable' => false,
        'filterable' => true,
        'filters' => [
            'name.con' => [
                'type' => 'con', // Filter::CONTAINS
                'name' => '',
            ],
            'name.st' => [
                'type' => 'st', // Filter::STARTS_WITH
                'name' => '',
            ],
           'name.enw' => [
                'type' => 'enw', // Filter::ENDS_WITH
                'name' => '',
            ],
        ],
    ],
];
```

if your filters have options, they will be present too:

```
'name.enw' => [
    'type' => 'm1', // Filter::MATCH_ONE
    'name' => '',
    'options' => [
        [
            'value' => '',
            'label' => ''
        ],
        ...
    ],
],
```

This enables you to create the UI for the grid based on a filters type and options.

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 97.3% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/9e16a979f062ee9a01f53d23dc34dd4fcfc0ac32df859827174bc7782d2e1aa5?d=identicon)[willishq](/maintainers/willishq)

---

Top Contributors

[![willishq](https://avatars.githubusercontent.com/u/1564903?v=4)](https://github.com/willishq "willishq (71 commits)")[![scrutinizer-auto-fixer](https://avatars.githubusercontent.com/u/6253494?v=4)](https://github.com/scrutinizer-auto-fixer "scrutinizer-auto-fixer (2 commits)")

### Embed Badge

![Health badge](/badges/query-grid-query-grid/health.svg)

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

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90340.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)

PHPackages © 2026

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