README

SQL-like fluent query builder for filtering, sorting, and transforming arrays.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/php-array-query

Usage

Basic Filtering

use PhilipRehberger\ArrayQuery\ArrayQuery;

$users = [
    ['name' => 'Alice', 'age' => 30, 'city' => 'NYC', 'score' => 85],
    ['name' => 'Bob', 'age' => 25, 'city' => 'LA', 'score' => 92],
    ['name' => 'Charlie', 'age' => 35, 'city' => 'NYC', 'score' => 78],
    ['name' => 'Diana', 'age' => 28, 'city' => 'Chicago', 'score' => null],
    ['name' => 'Eve', 'age' => 22, 'city' => 'LA', 'score' => 95],
];

$results = ArrayQuery::from($users)
    ->where('city', '=', 'NYC')
    ->where('age', '>', 25)
    ->get();
// [['name' => 'Alice', ...], ['name' => 'Charlie', ...]]

Sorting

$results = ArrayQuery::from($users)
    ->sort('age', 'desc')
    ->get();
// Sorted by age descending: Charlie, Alice, Diana, Bob, Eve

Limit & Offset

$results = ArrayQuery::from($users)
    ->sort('age')
    ->offset(1)
    ->limit(3)
    ->get();
// Skip first, take next 3

Select Specific Keys

$results = ArrayQuery::from($users)
    ->select(['name', 'age'])
    ->get();
// [['name' => 'Alice', 'age' => 30], ...]

Pluck a Single Column

$names = ArrayQuery::from($users)
    ->where('city', '=', 'LA')
    ->pluck('name');
// ['Bob', 'Eve']

Group By

$groups = ArrayQuery::from($users)
    ->groupBy('city');
// ['NYC' => [...], 'LA' => [...], 'Chicago' => [...]]

Aggregates

$query = ArrayQuery::from($users)->whereNotNull('score');

$query->sum('score');   // 350
$query->avg('score');   // 87.5
$query->min('score');   // 78
$query->max('score');   // 95
$query->count();        // 4

Additional Filters

// Where In
ArrayQuery::from($users)->whereIn('city', ['NYC', 'LA'])->get();

// Where Null / Not Null
ArrayQuery::from($users)->whereNull('score')->get();
ArrayQuery::from($users)->whereNotNull('score')->get();

// Where Between
ArrayQuery::from($users)->whereBetween('age', 25, 30)->get();

// Like (case-insensitive)
ArrayQuery::from($users)->where('name', 'like', '%ali%')->get();

Distinct

$items = [
    ['name' => 'Alice', 'city' => 'NYC'],
    ['name' => 'Bob', 'city' => 'LA'],
    ['name' => 'Charlie', 'city' => 'NYC'],
];

// Remove duplicates by city (keeps first occurrence)
ArrayQuery::from($items)->distinct('city')->get();
// [['name' => 'Alice', 'city' => 'NYC'], ['name' => 'Bob', 'city' => 'LA']]

// Remove fully duplicate rows
ArrayQuery::from($items)->distinct()->get();

Chunk

$results = ArrayQuery::from($users)
    ->sort('age')
    ->chunk(2);
// [[['name' => 'Eve', ...], ['name' => 'Bob', ...]], [['name' => 'Diana', ...], ['name' => 'Alice', ...]], [['name' => 'Charlie', ...]]]

Contains Operator

$items = [
    ['name' => 'Alice', 'tags' => ['php', 'javascript']],
    ['name' => 'Bob', 'tags' => ['python', 'go']],
];

ArrayQuery::from($items)->where('tags', 'contains', 'php')->get();
// [['name' => 'Alice', ...]]

ArrayQuery::from($items)->where('tags', 'not_contains', 'php')->get();
// [['name' => 'Bob', ...]]

Dot Notation for Nested Arrays

$items = [
    ['name' => 'Alice', 'address' => ['city' => 'NYC']],
    ['name' => 'Bob', 'address' => ['city' => 'LA']],
];

ArrayQuery::from($items)
    ->where('address.city', '=', 'NYC')
    ->get();

API

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT