PHPackages                             offline/jsonq - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. offline/jsonq

ActiveLibrary[Parsing & Serialization](/categories/parsing)

offline/jsonq
=============

JsonQ is a PHP based json data query library

v5.2.7(4y ago)24.4kCC0-1.0PHPPHP >=5.5.0

Since Jun 13Pushed 4y ago3 watchersCompare

[ Source](https://github.com/OFFLINE-GmbH/jsonq)[ Packagist](https://packagist.org/packages/offline/jsonq)[ Docs](https://github.com/nahid/jsonq)[ RSS](/packages/offline-jsonq/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (3)Versions (20)Used By (0)

php-jsonq
=========

[](#php-jsonq)

**JsonQ** is a simple, elegant PHP package to Query over any type of JSON Data. It'll make your life easier by giving the flavour of an ORM-like query on your JSON.

Support For This Project
------------------------

[](#support-for-this-project)

Hey due, please help me out for daily improve this project

[![Beerpay](https://camo.githubusercontent.com/8b9ce0a7da7ddfff88fcd97836765227f1b7ede2e55a914e99ee69e06559eb93/68747470733a2f2f626565727061792e696f2f6e616869642f6a736f6e712f62616467652e737667)](https://beerpay.io/nahid/jsonq)

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

[](#installation)

```
composer require nahid/jsonq

```

Usage
-----

[](#usage)

You can start using this package right away by importing your JSON data from a file:

```
use Nahid/JsonQ/Jsonq;
$jsonq = new Jsonq('data.json');
```

Or from a JSON String:

```
$json->json('{"id": 1, "name": "Nahid"}');
```

Or from a PHP Array:

```
$json->collect(['id'=>1, 'name'=>'Nahid']);
```

You can start Query your data using the various query methods such as **find**, **where**, **orWhere**, **whereIn**, **whereStartsWith**, **whereEndsWith**, **whereContains** and so on. Also you can aggregate your data after query using **sum**, **count**, **groupBy**, **max**, **min** etc.

Let's see a quick example:

```
//data.json
{
	"name": "products",
	"description": "Features product list",
	"vendor":{
		"name": "Computer Source BD",
		"email": "info@example.com",
		"website":"www.example.com"
	},
	"users":[
		{"id":1, "name":"Johura Akter Sumi", "location": "Barisal"},
		{"id":2, "name":"Mehedi Hasan Nahid", "location": "Barisal"},
		{"id":3, "name":"Ariful Islam", "location": "Barisal"},
		{"id":4, "name":"Suhel Ahmed", "location": "Sylhet"},
		{"id":5, "name":"Firoz Serniabat", "location": "Gournodi"},
		{"id":6, "name":"Musa Jewel", "location": "Barisal", "visits": [
			{"name": "Sylhet", "year": 2011},
			{"name": "Cox's Bazar", "year": 2012},
			{"name": "Bandarbar", "year": 2014}
		]}
	],
	"products": [
		{"id":1, "user_id": 2, "city": "bsl", "name":"iPhone", "cat":1, "price": 80000},
		{"id":2, "user_id": 2, "city": null, "name":"macbook pro", "cat": 2, "price": 150000},
		{"id":3, "user_id": 2, "city": "dhk", "name":"Redmi 3S Prime", "cat": 1, "price": 12000},
		{"id":4, "user_id": 1, "city": null, "name":"Redmi 4X", "cat":1, "price": 15000},
		{"id":5, "user_id": 1, "city": "bsl", "name":"macbook air", "cat": 2, "price": 110000},
		{"id":6, "user_id": 2, "city": null, "name":"macbook air 1", "cat": 2, "price": 81000}
	]
}
```

```
use Nahid\JsonQ\Jsonq;

$q = new Jsonq('data.json');
$res = $q->from('products')
    ->where('cat', '=', 2)
    ->get();
dump($res);

//This will print
/*
array:3 [▼
  1 => {#7 ▼
    +"id": 2
    +"user_id": 2
    +"city": null
    +"name": "macbook pro"
    +"cat": 2
    +"price": 150000
  }
  4 => {#8 ▼
    +"id": 5
    +"user_id": 1
    +"city": "bsl"
    +"name": "macbook air"
    +"cat": 2
    +"price": 110000
  }
  5 => {#9 ▼
    +"id": 6
    +"user_id": 2
    +"city": null
    +"name": "macbook air 1"
    +"cat": 2
    +"price": 81000
  }
]
*/
```

Let's say we want to get the Summation of *price* of the Queried result. We can do it easily by calling the **sum()** method instead of **get()**:

```
$result = $json->from('products')
        ->where('cat', '=', 2)
        ->sum('price');
dump($result);

//It will print:
/*
365000
*/
```

Pretty neat, huh?

Let's explore the full API to see what else magic this library can do for you. Shall we?

API
---

[](#api)

Following API examples are shown based on the sample JSON data given [here](examples/data.json). To get a better idea of the examples see that JSON data first. Also detailed examples of each API can be found [here](examples/).

**List of API:**

- [fetch](#fetch)
- [find](#findpath)
- [at](#atpath)
- [from](#frompath)
- [select](#select)
- [except](#except)
- [then](#then)
- [collect](#collect)
- [json](#json)
- [import](#import)
- [where](#wherekey-op-val)
- [orWhere](#orwherekey-op-val)
- [whereIn](#whereinkey-val)
- [whereNotIn](#wherenotinkey-val)
- [whereNull](#wherenullkey)
- [whereNotNull](#wherenotnullkey)
- [whereStartsWith](#wherestartswithkey-val)
- [whereEndsWith](#whereendswithkey-val)
- [whereContains](#wherecontainskey-val)
- [whereMatch](#wherematch-val)
- [sum](#sumproperty)
- [count](#count)
- [size](#size)
- [max](#maxproperty)
- [min](#minproperty)
- [avg](#avgproperty)
- [first](#first)
- [last](#last)
- [nth](#nthindex)
- [column](#column)
- [implode](#implode)
- [exists](#exists)
- [groupBy](#groupbyproperty)
- [sort](#sortorder)
- [sortBy](#sortbyproperty-order)
- [reset](#resetdata)
- [copy](#copy)
- [toJson](#tojson)
- [keys](#keys)
- [values](#values)
- [filter](#filter)
- [transform](#transform)
- [each](#each)
- [pipe](#pipe)
- [chunk](#chunk)
- [macro](#macro)

### `fetch()`

[](#fetch)

This method will execute queries and will return the resulted data. You need to call it finally after using some query methods. Details can be found in other API examples.

### `find(path)`

[](#findpath)

- `path` -- the path hierarchy of the data you want to find.

You don't need to call `fetch()` method after this. Because this method will fetch and return the data by itself.

**caveat:** You can't chain further query methods after it. If you need that, you should use `at()` or `from()` method.

**example:**

Let's say you want to get the value of *'cities'* property of your Json Data. You can do it like this:

```
$q = new Jsonq('data.json');
echo $q->find('vendor.name');
```

If you want to traverse to more deep in hierarchy, you can do it like:

```
$q = new Jsonq('data.json');
echo $q->find('vendor.name');
```

See a detail example [here](examples/find.js).

### `from(path)`

[](#frompath)

- `path` (optional) -- the path hierarchy of the data you want to start query from.

By default, query would be started from the root of the JSON Data you've given. If you want to first move to a nested path hierarchy of the data from where you want to start your query, you would use this method. Skipping the `path` parameter or giving **'.'** as parameter will also start query from the root Data.

Difference between this method and `find()` is that, `find()` method will return the data from the given path hierarchy. On the other hand, this method will return the Object instance, so that you can further chain query methods after it.

**example:**

Let's say you want to start query over the values of *'vendor.name'* property of your JSON Data. You can do it like this:

```
$q = new Jsonq('data.json');
echo $q->from('vendor.name')->get();
```

If you want to traverse to more deep in hierarchy, you can do it like:

```
$q = new Jsonq('data.json');
echo $q->from('users.5.visits')->get();
```

See a detail example [here](examples/from.php).

### `at(path)`

[](#atpath)

This is an alias method of `from()` and will behave exactly like that. See example [here](examples/from.php).

### `where(key, condition, val)`

[](#wherekey-condition-val)

- `key` -- the property name of the data. Or you can pass a Function here to group multiple query inside it. See details in [example](examples/where.js)
- `val` -- value to be matched with. It can be a *int*, *string*, *bool* or even *Function* - depending on the `op`.
- `op` -- operand to be used for matching. The following operands are available to use:

    - `=` : For weak equality matching
    - `eq` : Same as `=`
    - `!=` : For weak not equality matching
    - `neq` : Same as `!=`
    - `==` : For strict equality matching
    - `seq` : Same as `==`
    - `!==` : For strict not equality matching
    - `sneq` : Same as `!==`
    - `>` : Check if value of given **key** in data is Greater than **val**
    - `gt` : Same as `>`
    - `=`
    - `from('users')
->where('id', '=', 1)
->where('location', '=', 'barisal')
->get();
```

See a detail example [here](examples/where.php).

### `orWhere(key, op, val)`

[](#orwherekey-op-val)

Parameters of `orWhere()` are the same as `where()`. The only difference between `where()` and `orWhere()` is: condition given by the `orWhere()` method will OR-ed the result with other conditions.

For example, if you want to find the users with *id* of `1` or `2`, you can do it like this:

```
$q = new Jsonq('data.json');
$res = $q->from('users')
->where('id', '=', 1)
->orWhere('id', '=', 2)
->get();
```

See detail example [here](examples/or-where.php).

### `whereIn(key, val)`

[](#whereinkey-val)

- `key` -- the property name of the data
- `val` -- it should be an **Array**

This method will behave like `where(key, 'in', val)` method call.

### `whereNotIn(key, val)`

[](#wherenotinkey-val)

- `key` -- the property name of the data
- `val` -- it should be an **Array**

This method will behave like `where(key, 'notin', val)` method call.

### `whereNull(key)`

[](#wherenullkey)

- `key` -- the property name of the data

This method will behave like `where(key, 'null')` or `where(key, '=', null)` method call.

### `whereNotNull(key)`

[](#wherenotnullkey)

- `key` -- the property name of the data

This method will behave like `where(key, 'notnull')` or `where(key, '!=', null)` method call.

### `whereStartsWith(key, val)`

[](#wherestartswithkey-val)

- `key` -- the property name of the data
- `val` -- it should be a String

This method will behave like `where(key, 'startswith', val)` method call.

### `whereEndsWith(key, val)`

[](#whereendswithkey-val)

- `key` -- the property name of the data
- `val` -- it should be a String

This method will behave like `where(key, 'endswith', val)` method call.

### `whereContains(key, val)`

[](#wherecontainskey-val)

- `key` -- the property name of the data
- `val` -- it should be a String

This method will behave like `where(key, 'contains', val)` method call.

### `sum(column)`

[](#sumcolumn)

- `column` -- the property name of the data

**example:**

Let's say you want to find the sum of the *'price'* of the *'products'*. You can do it like this:

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->sum('price');
```

If the data you are aggregating is plain array, you don't need to pass the 'column' parameter. See detail example [here](examples/sum.php)

### `count()`

[](#count)

It will return the number of elements in the collection.

**example:**

Let's say you want to find how many elements are in the *'products'* property. You can do it like:

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->count();
```

See detail example [here](examples/count.php).

### `size()`

[](#size)

This is an alias method of `count()`.

### `max(column)`

[](#maxcolumn)

- `column` -- the property name of the data

**example:**

Let's say you want to find the maximum of the *'price'* of the *'products'*. You can do it like this:

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->max('price);
```

If the data you are querying is plain array, you don't need to pass the 'column' parameter. See detail example [here](examples/max.php)

### `min(column)`

[](#mincolumn)

- `column` -- the property name of the data

**example:**

Let's say you want to find the minimum of the *'price'* of the *'products'*. You can do it like this:

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->min('price');
```

If the data you are querying is plain array, you don't need to pass the 'property' parameter. See detail example [here](examples/min.php)

### `avg(column)`

[](#avgcolumn)

- `column` -- the property name of the data

**example:**

Let's say you want to find the average of the *'price'* of the *'products'*. You can do it like this:

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->avg('price');
```

If the data you are querying is plain array, you don't need to pass the 'column' parameter. See detail example [here](examples/avg.php)

### `first()`

[](#first)

It will return the first element of the collection.

**example:**

```
$q = new jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->first();
```

See detail example [here](examples/first.php).

### `last()`

[](#last)

It will return the last element of the collection.

**example:**

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->last();
```

See detail example [here](examples/last.php).

### `nth(index)`

[](#nthindex)

- `index` -- index of the element to be returned.

It will return the nth element of the collection. If the given index is a **positive** value, it will return the nth element from the beginning. If the given index is a **negative** value, it will return the nth element from the end.

**example:**

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->nth(2);
```

See detail example [here](examples/nth.php).

### `exists()`

[](#exists)

It will return **true** if the element is not **empty** or not **null** or not an **empty array** or not an **empty object**.

**example:**

Let's say you want to find how many elements are in the *'products'* property. You can do it like:

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->exists();
```

See detail example [here](examples/exists.php).

### `groupBy(column)`

[](#groupbycolumn)

- `column` -- The property by which you want to group the collection.

**example:**

Let's say you want to group the *'users'* data based on the *'location'* property. You can do it like:

```
$q = new Jsonq('data.json');
$res = $q->from('users')
->groupBy('location')
->get();
```

See detail example [here](examples/group-by.php).

### `sort(order)`

[](#sortorder)

- `order` -- If you skip the *'order'* property the data will be by default ordered as **ascending**. You need to pass **'desc'** as the *'order'* parameter to sort the data in **descending** order. Also, you can pass a compare function in *'order'* parameter to define your own logic to order the data.

**Note:** This method should be used for plain Array. If you want to sort an Array of Objects you should use the **sortBy()** method described later.

**example:**

Let's say you want to sort the *'arr'* data. You can do it like:

```
$q = new Jsonq();
$res = $q->collect([7, 5, 9, 1, 3])
->sort();
```

See detail example [here](examples/sort.php).

### `sortBy(column, order)`

[](#sortbycolumn-order)

- `column` -- You need to pass the column name on which the sorting will be done.
- `order` -- If you skip the *'order'* property the data will be by default ordered as **ascending**. You need to pass **'desc'** as the *'order'* parameter to sort the data in **descending** order. Also, you can pass a compare function in *'order'* parameter to define your own logic to order the data.

**Note:** This method should be used for Array of Objects. If you want to sort a plain Array you should use the **sort()** method described earlier.

**example:**

Let's say you want to sort the *'price'* data of *'products'*. You can do it like:

```
$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->sortBy('price', 'desc');
```

See detail example [here](examples/sort-by.php).

### `reset(data)`

[](#resetdata)

- `data` -- can be a JSON file path, or a JSON string or a JSON Object. If no data passed in the `data` parameter, the `jsonQ` Object instance will be reset to previously initialized data.

At any point, you might want to reset the Object instance to a completely different set of data and then query over it. You can use this method in that case.

See a detail example [here](examples/reset.php).

### `copy()`

[](#copy)

It will return a complete clone of the Object instance.

See a detail example [here](examples/copy.php).

Bugs and Issues
---------------

[](#bugs-and-issues)

If you encounter any bugs or issues, feel free to [open an issue at github](https://github.com/nahid/jsonq/issues).

Also, you can shoot me an email to  for hugs or bugs.

Others Platform
---------------

[](#others-platform)

This package has also different language support.

- [JavaScript JsonQ](https://github.com/me-shaon/js-jsonq) developed by [Ahmed shamim](https://github.com/me-shaon)
- [Python JsonQ](https://github.com/s1s1ty/py-jsonq) developed by [Shaon Shaonty](https://github.com/s1s1ty)
- [Go JsonQ](https://github.com/thedevsaddam/gojsonq) developed by [Saddam H](https://github.com/thedevsaddam) - Upcoming

Support on Beerpay
------------------

[](#support-on-beerpay)

Hey dude! Help me out for a couple of 🍻!

[![Beerpay](https://camo.githubusercontent.com/e0133eac6b6c33b81edaba52ee48fc37d9c3d7ec19d8f7324d448dbbeaf53b54/68747470733a2f2f626565727061792e696f2f6e616869642f6a736f6e712f62616467652e7376673f7374796c653d626565722d737175617265)](https://beerpay.io/nahid/jsonq) [![Beerpay](https://camo.githubusercontent.com/4805c229e516427072432b980b0f928aef2dbe9775f777972f38be805f139354/68747470733a2f2f626565727061792e696f2f6e616869642f6a736f6e712f6d616b652d776973682e7376673f7374796c653d666c61742d737175617265)](https://beerpay.io/nahid/jsonq?focus=wish)

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity24

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 64.8% 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 ~122 days

Recently: every ~264 days

Total

17

Last Release

1665d ago

Major Versions

v1.0.0 → v2.0.02017-04-27

v2.0.2 → v3.0.02018-05-05

v3.0.0 → v5.0.02018-05-15

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8600029?v=4)[Tobias Kündig](/maintainers/tobias-kuendig)[@tobias-kuendig](https://github.com/tobias-kuendig)

---

Top Contributors

[![nahid](https://avatars.githubusercontent.com/u/3167309?v=4)](https://github.com/nahid "nahid (70 commits)")[![GitHubHubus](https://avatars.githubusercontent.com/u/11797167?v=4)](https://github.com/GitHubHubus "GitHubHubus (12 commits)")[![me-shaon](https://avatars.githubusercontent.com/u/831997?v=4)](https://github.com/me-shaon "me-shaon (9 commits)")[![tobias-kuendig](https://avatars.githubusercontent.com/u/8600029?v=4)](https://github.com/tobias-kuendig "tobias-kuendig (8 commits)")[![lo00l](https://avatars.githubusercontent.com/u/6896941?v=4)](https://github.com/lo00l "lo00l (4 commits)")[![SolStis86](https://avatars.githubusercontent.com/u/9559480?v=4)](https://github.com/SolStis86 "SolStis86 (3 commits)")[![svenluijten](https://avatars.githubusercontent.com/u/11269635?v=4)](https://github.com/svenluijten "svenluijten (1 commits)")[![atefBB](https://avatars.githubusercontent.com/u/10966925?v=4)](https://github.com/atefBB "atefBB (1 commits)")

---

Tags

jsonqueryjsonq

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/offline-jsonq/health.svg)

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

###  Alternatives

[justinrainbow/json-schema

A library to validate a json schema.

3.6k316.9M612](/packages/justinrainbow-json-schema)[mtdowling/jmespath.php

Declaratively specify how to extract elements from a JSON document

2.0k472.8M135](/packages/mtdowling-jmespathphp)[nahid/jsonq

JsonQ is a PHP based json data query library

873651.3k7](/packages/nahid-jsonq)[jms/serializer

Library for (de-)serializing data of any complexity; supports XML, and JSON.

2.3k135.8M851](/packages/jms-serializer)[jms/serializer-bundle

Allows you to easily serialize, and deserialize data of any complexity

1.8k89.3M627](/packages/jms-serializer-bundle)[colinodell/json5

UTF-8 compatible JSON5 parser for PHP

30422.2M45](/packages/colinodell-json5)

PHPackages © 2026

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