PHP Classes

PHP JSON Query: Query JSON data to find and extract information

Recommend this page to a friend!
     
  Info   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 76%Total: 1,060 All time: 3,501 This week: 41Up
Version License PHP version Categories
jsonq 1.0.22The PHP License5PHP 5, Parsers
Description 

Author

This package can query JSON data to find and extract information.

It can parse JSON strings and perform queries to find nodes by name of object and array elements.

It can also filter by values of child element values using a fluent interface to combine multiple filter conditions.

Innovation Award
PHP Programming Innovation award winner
March 2017
Winner


Prize: One downloadable copy of Komodo IDE
JSON has become the de facto standard format for exchanging structured data types in the form of readable text, thus replacing XML for similar purposes.

There are many XML libraries for creating, parsing and querying XML documents.

This package provides a pure PHP solution for parsing and querying JSON data similar to XML query libraries.

Manuel Lemos
Picture of Nahid Bin Azhar
  Performance   Level  
Name: Nahid Bin Azhar <contact>
Classes: 24 packages by
Country: United States United States
Age: 33
All time rank: 792109 in United States United States
Week rank: 146 Up19 in United States United States Up
Innovation award
Innovation award
Nominee: 6x

Winner: 2x

Details

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

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

Beerpay

Installation

composer require nahid/jsonq

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

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

List of API:

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)

  • `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.

from(path)

  • `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.

at(path)

This is an alias method of from() and will behave exactly like that. See example here.

where(key, 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
  • `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 givenkeyin data is Greater thanval* * `gt` : Same as `>` < : Check if value of givenkeyin data is Less thanval* * `lt` : Same as `<` >= : Check if value of givenkeyin data is Greater than or Equal ofval* * `gte` : Same as `>=` <= : Check if value of givenkeyin data is Less than or Equal ofval* * `lte` : Same as `<=` null : Check if the value of givenkeyin data isnull* (`val` parameter in `where()` can be omitted for this `op`) notnull : Check if the value of givenkeyin data isnot null* (`val` parameter in `where()` can be omitted for this `op`) in : Check if the value of givenkeyin data is exists in givenval.val* should be a plain _Array_. notin : Check if the value of givenkeyin data is not exists in givenval.val* should be a plain _Array_. startswith : Check if the value of givenkeyin data starts with (has a prefix of) the givenval*. This would only works for _String_ type data. endswith : Check if the value of givenkeyin data ends with (has a suffix of) the givenval*. This would only works for _String_ type data. contains : Check if the value of givenkeyin data has a substring of givenval*. This would only works for _String_ type data. match : Check if the value of givenkeyin data has a Regular Expression match with the givenval. The val parameter should be aRegExp* for this `op`. macro : It would try to match the value of givenkeyin data executing the given val. The val parameter should be aFunctionfor this op. This function should have a matching logic inside it and returntrueorfalse* based on that.

example:

Let's say you want to find the _'users'_ who has _id_ of 1. You can do it like this:

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

You can add multiple _where_ conditions. It'll give the result by AND-ing between these multiple where conditions.

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

See a detail example here.

orWhere(key, 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.

whereIn(key, 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)

  • `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)

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

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

whereNotNull(key)

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

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

whereStartsWith(key, 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)

  • `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)

  • `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)

  • `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

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.

size()

This is an alias method of count().

max(column)

  • `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

min(column)

  • `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

avg(column)

  • `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

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.

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.

nth(index)

  • `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.

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.

groupBy(column)

  • `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.

sort(order)

  • `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.

sortBy(column, 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.

reset(data)

  • `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.

copy()

It will return a complete clone of the Object instance.

See a detail example here.

Bugs and Issues

If you encounter any bugs or issues, feel free to open an issue at github.

Also, you can shoot me an email to <mailto:nahid.dns@gmail.com> for hugs or bugs.

Others Platform

This package has also different language support.

Support on Beerpay

Hey dude! Help me out for a couple of :beers:!

Beerpay Beerpay


  Files folder image Files (37)  
File Role Description
Files folder image.github (1 file)
Files folder imageconfig (1 file)
Files folder imageexamples (12 files)
Files folder imagesrc (4 files, 3 directories)
Files folder imagetests (5 files, 1 directory)
Accessible without login Plain text file .travis.yml Data Auxiliary data
Accessible without login Plain text file changelog.txt Doc. Documentation
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file phpunit.xml.dist Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files (37)  /  .github  
File Role Description
  Accessible without login Plain text file FUNDING.yml Data Auxiliary data

  Files folder image Files (37)  /  config  
File Role Description
  Accessible without login Plain text file jsonq.php Conf. Configuration script

  Files folder image Files (37)  /  examples  
File Role Description
  Accessible without login Plain text file copy.php Example Example script
  Accessible without login Plain text file count.php Example Example script
  Accessible without login Plain text file data.json Data Auxiliary data
  Accessible without login Plain text file exists.php Example Example script
  Accessible without login Plain text file find.php Example Example script
  Accessible without login Plain text file from.php Example Example script
  Accessible without login Plain text file get.php Example Example script
  Accessible without login Plain text file group-by.php Example Example script
  Accessible without login Plain text file index.php Example Example script
  Accessible without login Plain text file max.php Example Example script
  Accessible without login Plain text file min.php Example Example script
  Accessible without login Plain text file sum.php Example Example script

  Files folder image Files (37)  /  src  
File Role Description
Files folder imageExceptions (5 files)
Files folder imageFacades (1 file)
Files folder imageResults (1 file)
  Plain text file Condition.php Class Class source
  Plain text file Jsonq.php Class Class source
  Plain text file JsonqServiceProvider.php Class Class source
  Plain text file JsonQueriable.php Class Class source

  Files folder image Files (37)  /  src  /  Exceptions  
File Role Description
  Plain text file ConditionNotAllowedException.php Class Class source
  Plain text file FileNotFoundException.php Class Class source
  Plain text file InvalidJsonException.php Class Class source
  Plain text file InvalidNodeException.php Class Class source
  Plain text file NullValueException.php Class Class source

  Files folder image Files (37)  /  src  /  Facades  
File Role Description
  Plain text file Jsonq.php Class Class source

  Files folder image Files (37)  /  src  /  Results  
File Role Description
  Plain text file ValueNotFound.php Class Class source

  Files folder image Files (37)  /  tests  
File Role Description
Files folder imageFacades (1 file)
  Plain text file AbstractTestCase.php Class Class source
  Plain text file ConditionTest.php Class Class source
  Plain text file JsonqServiceProviderTest.php Class Class source
  Plain text file JsonQueriableTest.php Class Class source
  Plain text file TestCase.php Class Class source

  Files folder image Files (37)  /  tests  /  Facades  
File Role Description
  Plain text file Jsonq.php Class Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:1,060
This week:0
All time:3,501
This week:41Up
User Ratings User Comments (1)
 All time
Utility:97%StarStarStarStarStar
Consistency:92%StarStarStarStarStar
Documentation:90%StarStarStarStarStar
Examples:92%StarStarStarStarStar
Tests:-
Videos:-
Overall:76%StarStarStarStar
Rank:63
 
great work! thanks a lot for sharing!
6 years ago (Volkan K.)
80%StarStarStarStarStar