minnur/array-query

Array Query

v1.0.4 2022-10-16 13:06 UTC

MIT

• Mauro Cassani

• php
• array
• query

README

Array Query allows you to perform queries on multidimensional arrays.

Use Cases

This library is suitable for you if you need to perform some queries on:

• static php arrays
• in-memory stored arrays
• parsed json (or yaml) files

Basic Usage

To instantiate the QueryBuilder do the following:

use ArrayQuery\QueryBuilder;

$array = [
    [
        'id' => 1,
        'title' => 'Leanne Graham',
        'email' => '[e-mail]',
        'rate' => 5,
        'company' => [
            'name' => 'Romaguera-Jacobson',
            'catchPhrase' => 'Face to face bifurcated interface',
            'bs' => 'e-enable strategic applications'
        ]
    ],
    [
        'id' => 2,
        'title' => 'Ervin Howell',
        'email' => '[e-mail]',
        'rate' => 3,
        'company' => [
            'name' => 'Robel-Corkery',
            'catchPhrase' => 'Multi-tiered zero tolerance productivity',
            'bs' => 'transition cutting-edge web services'
        ]
    ],
    [
        'id' => 3,
        'title' => 'Clementine Bauch',
        'email' => '[e-mail]',
        'rate' => 4,
        'company' => [
            'name' => 'Keebler LLC',
            'catchPhrase' => 'User-centric fault-tolerant solution',
            'bs' => 'revolutionize end-to-end systems'
        ]
    ],
    // ..
]

QueryBuilder::create($array);

// to add an element to your array. Do this BEFORE make a query on the array
$element = [
   'id' => 4,
   'title' => 'Patricia Lebsack',
   'email' => '[e-mail]',
   'rate' => 2,
   'company' => [
       'name' => 'Robel-Corkery',
       'catchPhrase' => 'Multi-tiered zero tolerance productivity',
       'bs' => 'transition cutting-edge web services'
   ]
];
$qb->addElement($element, 4);

// to remove an element from array by his key. Do this BEFORE make a query on the array
$qb->removeElement(3);

Data consistency

QueryBuilder checks for your data consistency. If an inconsistency is detected a NotConsistentDataException will be raised:

use ArrayQuery\QueryBuilder;

$array = [
    [
        'id' => 1,
        'title' => 'Leanne Graham',
        'email' => '[e-mail]',
        'rate' => 5,
        'company' => [
            'name' => 'Romaguera-Jacobson',
            'catchPhrase' => 'Face to face bifurcated interface',
            'bs' => 'e-enable strategic applications'
        ]
    ],
    [
        'id' => 2,
        'title' => 'Ervin Howell',
        'email' => '[e-mail]',
        'rate' => 3,
        'company' => [
            'name' => 'Robel-Corkery',
            'catchPhrase' => 'Multi-tiered zero tolerance productivity',
            'bs' => 'transition cutting-edge web services'
        ]
    ],
    [
        'id' => 3,
        'title' => 'Clementine Bauch',
        'email' => '[e-mail]',
        'rate' => 4,
        'company' => [
            'name' => 'Keebler LLC',
            'catchPhrase' => 'User-centric fault-tolerant solution',
            'bs' => 'revolutionize end-to-end systems'
        ],
        'extra-field' => 'this is an extra field'
    ],
]

// NotConsistentDataException will be raised
QueryBuilder::create($array);

Quering, sorting and get results

You can perform queries on your array. You can concatenate criteria:

use ArrayQuery\QueryBuilder;

// ..

$qb = QueryBuilder::create($array);
$qb
    ->addCriterion('title', 'Leanne', 'CONTAINS')
    ->addCriterion('rate', '3', '>')
    ->sortedBy('title', 'DESC');

// you can search by nested keys    
$qb->addCriterion('company.name', 'Romaguera-Jacobson');

// get results    
foreach ($qb->getResults() as $element){
    // ...
}

// get first result
$first = $qb->getFirstResult();

// get last result
$last = $qb->getLastResult();

// get a result by index
$thirdResult = $qb->getResult(3);

Avaliable criteria operators

• = (default operator, can be omitted)
• >
• <
• <=
• >=
• !=
• ARRAY_MATCH
• CONTAINS (case insensitive)
• ENDS_WITH
• EQUALS_DATE
• GT_DATE
• GTE_DATE
• IN_ARRAY
• IN_ARRAY_INVERSED
• LT_DATE
• LTE_DATE
• STARTS_WITH

Avaliable sorting operators

• ASC (default operator, can be omitted)
• DESC
• DATE_ASC
• DATE_DESC

Joins

You can join arrays. Please consider this full example:

use ArrayQuery\QueryBuilder;

$users = [
    [
        'id' => 1,
        'name' => 'Mauro Cassani',
        'id_category' => 3,
        'email' => '[e-mail]'
    ],[
        'id' => 2,
        'name' => 'Mario Rossi',
        'id_category' => 3,
        'email' => '[e-mail]'
    ],[
        'id' => 3,
        'name' => 'Maria Bianchi',
        'id_category' => 1,
        'email' => '[e-mail]'
    ]
];
$category = [
    'id' => 3,
    'name' => 'Web Developer'
];

$qb = QueryBuilder::create($users)
    ->join($category, 'category', 'id_category', 'id')
    ->addCriterion('category.id', 3);

foreach ($qb->getResults() as $element){
    // ...
}

Limit and Offset

You can add criteria and specify limit and offset for your query results:

use ArrayQuery\QueryBuilder;

$qb = QueryBuilder::create($array);
$qb
    ->addCriterion('title', ['Leanne'], 'IN_ARRAY')
    ->addCriterion('rate', '3', '>')
    ->sortedBy('title')
    ->limit(0, 10);

foreach ($qb->getResults() as $element){
    // ...
}

Working with dates

You can perform queries based on datetime fields. You can use DATE_ASC or DATE_DESC operator to sort results by date. You must specify date format if your format is not YYYY-mm-dd:

use ArrayQuery\QueryBuilder;

$qb = QueryBuilder::create($array);
$qb
    ->addCriterion('registration_date', '01/05/2017', 'GT_DATE', 'd/m/Y')
    ->addCriterion('rate', '3', '>')
    ->sortedBy('registration_date', 'DATE_DESC', 'd/m/Y')
    ->limit(0, 10);

foreach ($qb->getResults() as $element){
    // ...
}

Aliases

You can use aliases by using the as keyword as a delimiter. Do the following:

use ArrayQuery\QueryBuilder;

$qb = QueryBuilder::create($array);
$qb
    ->addCriterion('name as n', 'Ervin Howell')
    ->addCriterion('username as user', 'Antonette')
    ->addCriterion('address.street as street', 'Victor Plains');

foreach ($qb->getResults() as $element){
    // ...
    // now you have
    // $element['n']
    // $element['user']
    // $element['street']
}

Shuffled results

You can shuffle query results by using getShuffledResults method:

use ArrayQuery\QueryBuilder;

$qb = QueryBuilder::create($array);

foreach ($qb->getShuffledResults() as $element){
    // ...
}

More examples

Please refer to QueryBuilderTest for more examples.

Support

If you found an issue or had an idea please refer to this section.

Authors

• Mauro Cassani - github

License

This project is licensed under the MIT License - see the LICENSE.md file for details