qinq
PHP 5.5+ quasi integrated query
Installation
Install via cli using composer:
php composer.phar require jgswift/qinq:0.1.*
Install via composer.json using composer:
{
"require": {
"jgswift/qinq": "0.1.*"
}
}
Description
qinq is a lightweight array handling component that provides support for complex array manipulation with queries and built-in query caching
This package does not parse PHP or do any AST handling. qinq only manipulates arrays using php's built-in array functionality.
Dependency
- php 5.5+
- jgswift/qtil - general utility library
- jgswift/kenum - enumerator implementation
- jgswift/kfiltr - filter/map/hook implementation
Usage
The following is a basic example
$richPeople = $people
->where(function($person) { return $person['money'] > 1000000; })
->order(function($personA,$personB) { return ($personA['money'] < $personB['money']) ? -1 : 1; })
->index(function($person) { return $person['lastName']; })
->select(function($person) {
return [
'fullName' => $person['firstName'].' '.$person['lastName'],
'money' => $person['money'],
'networth' => $person['money'] - $person['debt']
];
});
Populating a qinq collection
$integers = new qinq\Collection(range(1,50));
$names = new qinq\Collection(['bob','joe','sam','john','jake']);
Filter
// Retrieve all integers divisible by 5
foreach($integers->where(function($n) { return $n % 5 === 0; }) as $integer) {
// 5, 10, 15, 20 ...
}
// Retrieve all names with a character length of 3
foreach($names->where(function($n) { return strlen($n) === 3; }) as $name) {
// bob, joe, sam
}
Map
Applies a callback to the collection elements
foreach($numbers
->filter(function($v) {
return (bool)($v & 1); // filter out even values
})
->map(function($v) {
return $v * $v * $v; // cube all remaining odd values
}) as $number) {
// 1, 27, 125, 343, 729 ...
}
Order
// Retrieves all integers in descending order
foreach($integers->order(qinq\Order::DESCENDING) as $integer) {
// 50, 49, 48, 47 ...
}
// Retrieves all names in order of character length
foreach($names->order(function($n) { return strlen($n); } ) as $name ) {
// john, jake, bob ...
}
Sort
// Retrieve all names in order of character length (with compare function)
foreach($names->sort(function($a,$b) { return (strlen($a) > strlen($b)) ? -1 : 1; } ) as $name ) {
// john, jake, bob ...
}
Group
// Group values by divisibility of 2
foreach($integers->group(function($n) { return $n % 2; }) as $group) {
// [ 2, 4, 6, 8 ... ], [ 1, 3, 5, 7 ... ]
}
// Group names by to character length
foreach($names->group(function($n) { return strlen($n); }) as $group) {
// [ bob, joe, sam ], [ john, jake ]
}
Join
// Join integer collections using comparison method (on) and output method (to)
foreach($integers
->join($integers)
->on(function($outer,$inner) {
return ($outer >= $inner) ? true : false;
})
->to(function($outer,qinq\Collection $innerGroup) {
return $outer.':'.implode(',',$innerGroup->toArray());
}) as $integer ) {
// 1:1 , 2:1,2 , 3:1,2,3 ...
}
// Join integer and name collection, grouping names with integer that matches the character length
foreach($integers
->join($names)
->on(function($outer) {
return $outer;
}, 'strlen')
->to(function($outer,$inner) {
return $outer.':'.$inner;
}) as $number ) {
// 3:bob, 3:joe, 3:sam, 4:john, 4:jake
}
Difference
Computes the difference between collection and argument
foreach($integers
->difference(range(25,50))
as $number) {
// 1, 2, 3, ..., 24
}
Except
Alias of Difference
foreach($integers
->except(range(25,50))
as $number) {
// 1, 2, 3, ..., 24
}
First
Retrieves first item in collection.
echo $integers->first(); // 1
Last
Retrieves last item in collection
echo $integers->last(); // 50
Pluck
Aggregate specific array key or object property
$users = new qinq\Collection([
[
'name' => 'bob'
'email' => 'bob@example.com'
],
[
'name' => 'jim'
'email' => 'jim@example.com'
]
]);
foreach($users->pluck('name') as $name) {
// bob, jim
}
class User {
public $name, $email;
function __construct($name, $email) { /* ... */ }
}
$users = new qinq\Collection([
new User('bob','bob@example.com'),
new User('jim','jim@example.com'),
]);
foreach($users->pluck('email') as $email) {
// bob@example.com, jim@example.com
}
From
Replaces entire collection with given arguments. A single array/Iterator/Collection may also be given.
foreach($integers
->from([3,4])
as $number) {
// 3, 4
}
foreach($integers
->from(3,4,5)
as $number) {
// 3, 4, 5
}
Intersect
Retrieves values that exist in both arrays
foreach($integers
->intersect(range(25,100))
as $number) {
// 25, 26, 27, ..., 50
}
Reduce
Reduces array to single value using callback function
$q = new qinq\Collection([1,2,3,4,5]);
foreach($q
->reduce(function($carry,$item) {
return $carry * $item; // 1 * 2 * 3 * 4 * 5
})
as $result) {
// 120
}
Shuffle
Mix all items in collection to new random positions
foreach($integers
->shuffle()
as $result) {
// random number between 1 and 50
}
Values
Retrieves all values from collection
foreach($integers
->values()
as $result) {
// 1, 2, 3, ..., 50
}
Keys
Retrieves all collection keys
foreach($integers
->keys()
as $number) {
// 1, 2, 3, ..., 50
}
Pack
Removes all data from collection that is weakly equivalent to false or 0
$junk = new qinq\Collection([
false, 0, false, '0', 'hello'
]);
foreach($junk
->pack()
as $item) {
// 'hello'
}
Random
Selects a number of random items from collection
foreach($integers
->random(5)
as $result) {
// 5 random items from array
}
Recursive
Recursive maps through nested collections with a callback function
$numbers = new qinq\Collection([
1, 2, [3, 4, [5, 6]], 7, [8, [9, 10]] // multidimensional array
]);
foreach($numbers
->recursive(function($value) {
return $value * $value; // square(^2) values
}) as $number) {
// [ 1, 4, [ 9, 16, [ 25, 36 ] ] , 49, [ 64, [ 81, 100 ] ] ]
}
Search
Search filters through nested collections with a callback function
$numbers = new qinq\Collection([
1, 2, [3, 4, [5, 6]], 7, [8, [9, 10]] // multidimensional array
]);
foreach($numbers
->search(function($value) {
return ($value & 1) ? true : false; // only include odd values
}) as $number) {
// [ 1, [ 3, [ 5 ] ] , 7, [ 9 ] ]
}
Selector
Selector filters through nested collections using common string selectors
$ages = new qinq\Collection([
'joe' => 26,
'jim' => 40
'john' => 16
]);
foreach($ages
->selector('joe|jim') as $age) {
// [ 26, 40 ]
}
$favorites = new qinq\Collection([
'joe' => [
'color' => 'red',
'hat' => 'fedora'
]
]);
foreach($favorites
->selector('[joe][color]') as $favorite) {
// [ 'color' => 'red' ]
}
Flatten
Retrieves every value from a multidimensional collection tree and transforms it into a single dimensional collection
$tree = new qinq\Collection([
[1,2,[8,9],3,4],
[4,5,6,[1,2,3]],
[8,[9,10],[4,5]]
]);
foreach($tree
->flatten()
as $number) {
// 1, 2, 8, 9, 3, 4, 4, 5..
}
A flag argument may be provided to limit the flattening to certain types of collections or only arrays. The following example will leave the ArrayObject intact and avoid descending into any collections that are not strictly arrays.
use qinq\Object\Query\Flatten;
$tree = new qinq\Collection([
[1,2,[3,4]
[5,new ArrayObject([6,7,8])],
]);
foreach($tree
->flatten(Flatten::ARRAYONLY)
as $number) {
// 1, 2, 3, 4, ArrayObject()
}
Flatten Flags
- Flatten::ARRAYONLY
Flattens strictly php arrays, cancels all other flags
- Flatten::COLLECTION
Flattens objects implementing the qtil Traversable interface
- Flatten::TRAVERSABLE
Flattens objects implementing the built-in php Traversable interface.
- Flatten::ITERATOR
Flattens objects implementing the built-in php Iterator interface
Note: You may combine or exclude flags using
bitwise logic.
The default flatten flag setting descends into any known collection type by default, namely
COLLECTION, TRAVERSABLE, and ITERATOR.
Storing
qinq requires jgswift/delegatr to serialize and store queries.
$query = new \qinq\Object\Query($integers);
$query->select(function($n) {
return $n * 3;
})->where(function($n) {
return $n % 2 === 0;
});
$query_to_cache = serialize($query);
$query_from_cache = unserialize($query_to_cache);
var_dump( $query_from_cache->execute() === $query->execute() ) // true
Note: Query storing relies on eval to unserialize Closures.
Do not rely on users to provide serialized queries to your application as this
can make your application vulnerable to code injection.
You can verify a queries authenticity by performing a cryptographic checksum on
the serialized contents every time a client sends the query.
However said functionality is not implemented in this package.