nahid/qarray

QArray is a PHP abstraction for querying array

v2.1.0 2024-12-18 12:24 UTC

Requires

• php: >=7.4
• ext-json: *
• myclabs/deep-copy: ^1.8

Requires (Dev)

• phpunit/phpunit: ^5.0 || ^6.0
• symfony/var-dumper: ^3.4

MIT

• Nahid Bin Azhar

• php
• array
• query

README

# QArray - Query Engine For Array

QArray is query engine for PHP array data. It helps to developers querying any kind of array data with ORM like feel.

Installation

composer require nahid/qarray

Implementation

Since QArray is an abstract layer of code, so you have to implement your own system with a lots of pre build functionality.

Lets start our first implementation for JSON data.

class JsonQueryEngine extends \Nahid\QArray\QueryEngine
{
    public function readPath($path)
    {
        $data = file_get_contents($path);

        return json_decode($data, true);
    }

    public function parseData($data)
    {
        return json_decode($data, true);
    }
}

Here you see we implement a new engine for JSON data. QueryEngine is an abstract class, so we have to implement its two abstract function readPath and parseData

Usage

Our implementation were complete, now we can use this implementation.

class Product
{
    protected $query;

    public function __construct(\Nahid\QArray\QueryEngine $query)
    {
        $this->query = $query;
    }

    public function getMacbook()
    {
        try {
            return $this->query
                ->from('.')
                ->where('cat', 2)
                ->get();
        } catch (\Exception $e) {
           return false;
        }

    }
}

Here we develop a class for Products and this class use JsonQueryEngine for fetch data from JSON file.

Lets see, how to use it.

here is our JSON file data.json

[
  {"id":1, "name":"iPhone", "cat":1, "price": 80000},
  {"id":2, "name":"macbook pro 2017", "cat": 2, "price": 210000},
  {"id":3, "name":"Redmi 3S Prime", "cat": 1, "price": 12000},
  {"id":4, "name":"Redmi 4X", "cat":1, "price": 15000},
  {"id":5, "name":"macbook air", "cat": 2, "price": 110000}
]

And now we read it to querying data.

$data = new JsonQueryEngine('data.json');
$query = new SomethingBuilder($data);

dump($query->getMacbook()->toArray());

Output

array:2 [
  1 => array:4 [
    "id" => 2
    "name" => "macbook pro 2017"
    "cat" => 2
    "price" => 210000
  ]
  4 => array:4 [
    "id" => 5
    "name" => "macbook air"
    "cat" => 2
    "price" => 110000
  ]
]

Pretty neat, huh?

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

API

List of API:

• fetch
• find
• at
• from
• select
• except
• then
• collect
• json
• import
• where
• orWhere
• whereIn
• whereNotIn
• whereNull
• whereNotNull
• whereStartsWith
• whereEndsWith
• whereContains
• whereMatch
• whereInstance
• whereDataType
• sum
• count
• size
• max
• min
• avg
• first
• last
• nth
• column
• implode
• exists
• groupBy
• sort
• sortBy
• reset
• copy
• toJson
• keys
• values
• filter
• transform
• each
• pipe
• chunk
• macro

Available operation for where clause

• 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 given key in data is Greater than val
  • gt : Same as >
  • < : Check if value of given key in data is Less than val
  • lt : Same as <
  • >= : Check if value of given key in data is Greater than or Equal of val
  • gte : Same as >=
  • <= : Check if value of given key in data is Less than or Equal of val
  • lte : Same as <=
  • null : Check if the value of given key in data is null (val parameter in where() can be omitted for this op)
  • notnull : Check if the value of given key in data is not null (val parameter in where() can be omitted for this op)
  • in : Check if the value of given key in data is exists in given val. val should be a plain Array.
  • notin : Check if the value of given key in data is not exists in given val. val should be a plain Array.
  • startswith : Check if the value of given key in data starts with (has a prefix of) the given val. This would only works for String type data.
  • endswith : Check if the value of given key in data ends with (has a suffix of) the given val. This would only works for String type data.
  • contains : Check if the value of given key in data has a substring of given val. This would only works for String type data.
  • match : Check if the value of given key in data has a Regular Expression match with the given val. The val parameter should be a RegExp for this op.
  • instance : Check it the value of given key in data has an instance.

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.

whereDataType(key, val)

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

This method will behave like whereDataType(key, 'type', val) method call.

sum(column)

• column -- the property name of the data

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:[e-mail] for hugs or bugs.