array-search-by-key-value-pairs

Simple functionality, that allows to search the array for a given key-value pair(s). For instance, it can be useful, when you need to filter result from database with some conditions.

How-to

$cars = [
 ['id' => 10, 'vendor' => 'Chevrolet', 'model' => 'Corvett', 'price' => 25965, 'color' => 'red', 'is_reserved' => true],
 ['id' => 12, 'vendor' => 'Chevrolet', 'model' => 'Corvett', 'price' => 34229, 'color' => 'blue', 'is_reserved' => false],
 ['id' => 15, 'vendor' => 'Chevrolet', 'model' => 'Camaro', 'price' => 27982, 'color' => 'blue', 'is_reserved' => true],
 ['id' => 22, 'vendor' => 'Chevrolet', 'model' => 'Camaro', 'price' => 30000, 'color' => '', 'is_reserved' => null],
 ['id' => 23, 'vendor' => 'Chevrolet', 'model' => 'Malibu', 'price' => 29999, 'color' => 'white', 'is_reserved' => true],
 ['id' => 105, 'vendor' => 'Ford', 'model' => 'Fiesta', 'price' => 15000, 'color' => 'gray', 'is_reserved' => false],
 ['id' => 1005, 'vendor' => 'Ford', 'model' => 'Mustang', 'price' => '50000', 'color' => 'white', 'is_reserved' => true],
];

$filteredCars = getElemsByKeyValPairs($cars, ['vendor' => 'Ford']);

Arguments:

$search MODES:

MODE 1. $search is one-dimensional array. For example:

// Search WHERE 'model' == 'Corvett' AND 'color' == 'blue'.
$search = ['model' => 'Corvett', 'color' => 'blue'];
$filteredCars = getElemsByKeyValPairs($cars, $search);

MODE 2. $search is 2-dimensional array.

// Search WHERE 'vendor' == 'Chevrolet' AND 'price' >= 30000.
$search = [ 
 ['==', 'vendor', 'Chevrolet'], 
 ['>=', 'price', 30000] 
];
$filteredCars = getElemsByKeyValPairs($cars, $search);

Explanatory examples

 // 'vendor' == 'Ford'. Result contains elements with IDs 105, 1005.
	$filteredCars = getElemsByKeyValPairs($cars, ['vendor' => 'Ford']);
	// 'vendor' == 'Ford'. IDs 105, 1005 ($filteredCars keys are 5, 6 instead of 0, 1).
	$filteredCars = getElemsByKeyValPairs($cars, ['vendor' => 'Ford'], 'and', false);
	// 'model' == 'Corvett' AND 'color' == 'blue'. ID 12.
	$filteredCars = getElemsByKeyValPairs($cars, ['model' => 'Corvett', 'color' => 'blue']);
	// 'model' == 'Corvett' OR 'color' == 'blue'. IDs 10, 12, 15.
	$filteredCars = getElemsByKeyValPairs($cars, ['model' => 'Corvett', 'color' => 'blue'], 'or');
	// 'vendor' == 'Chevrolet' AND 'price' >= 30000. IDs 12, 22.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['==', 'vendor', 'Chevrolet'],
			['>=', 'price', 30000]
		]
	);
	// 'vendor' == 'Ford' AND 'model' != 'Fiesta'. ID 1005.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['==', 'vendor', 'Ford'],
			['!=', 'model', 'Fiesta']
		]
	);
	// Two calls below do the same thing.
	// 'price' == 30000 OR 'price' == 50000. IDs 22, 1005.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['==', 'price', 30000],
			['==', 'price', 50000]
		],
		'or'
	);
	// in_array('price', [30000, 50000]). IDs 22, 1005.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['in', 'price', [30000, 50000]]
		]
	);
	// in_array('price', [30000, 50000], true). ID 1005.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['strict in', 'price', ['30000', '50000']]
		]
	);
	// in_array('color', ['blue', 'red']) AND 'is_reserved' == true. IDs 10, 15.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['in', 'color', ['blue', 'red']],
			['==', 'is_reserved', true]
		]
	);
	// Usage of 'IN' operator with non-array value is not really correct syntax.
	// However, in case below condition is: 'color' == 'blue' (notice, that 'red' is ignored
	// as it is fourth, unexpected parameter for array with conditions). IDs 12, 15.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['in', 'color', 'blue', 'red']
		]
	);
	// in_array('color', ['blue', 'red']) OR 'is_reserved' == true. IDs 10, 12, 15, 23, 1005.
	// Please note that the IN operator is in capital case. Thus, it does not matter 
	// in which case you specify the comparison operator.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['IN', 'color', ['blue', 'red']],
			['==', 'is_reserved', true]
		],
		'or'
	);
	// !in_array('model', ['Corvett', 'Camaro']) AND 'color' != 'white'. ID 105.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['not in', 'model', ['Corvett', 'Camaro']],
			['<>', 'color', 'white']
		]
	);
	// !in_array('is_reserved', [true, false], true). ID 22.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['strict not in', 'is_reserved', [true, false]],
		]
	);
	// All models, which begin with 'M' symbol. 3rd argument must be a valid regexp. IDs 23, 1005.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['preg', 'model', '/^M/']
		]
	);
	// 'price' === 50000. Result is empty array, because comparison is strict.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['===', 'price', 50000]
		]
	);
	// 'is_reserved' == null. ID 22 may be expected only, but result also contains IDs 12 and 105, where 'is_reserved' is false.
	// IDs 12 and 105 appeared, because comparison IS NOT STRICT! Look the next example.
	$filteredCars = getElemsByKeyValPairs($cars, ['is_reserved' => null]);
	// 'is_reserved' === null. ID 22 only, because comparison is strict.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['===', 'is_reserved', null]
		]
	);
	// Field with name 'undefinedField' is absent in $cars, so empty array is returned.
	$filteredCars = getElemsByKeyValPairs($cars, ['undefinedField' => 'Ford']);
	// 'price' === 30000 OR 'undefinedField' > 100. Field with name 'undefinedField' is absent in $cars, 
	// but 'price' = 30000 is found. Result contains element with ID 22.
	$filteredCars = getElemsByKeyValPairs(
		$cars,
		[
			['==', 'price', 30000],
			['>', 'undefinedField', 100]
		],
		'or'
	);