First of all list() is not an unknown method in the PHP community, where almost every PHP developer knows what it does. The pity is that it has, perhaps, remained useless, although there is hidden power in it!

What is list()?

Let’s assume you’ve two variables and one array with two elements:

$arr = array(1, 2);
$a = $arr[0];
$b = $arr[1];
// now a == 1, and b == 2

Maybe the easiest way to assign to the first variable the value of the first element of the array, and to the second variable the value of the second element of the array is to use list():

list($a, $b) = array(1, 2);
// again a == 1, and b == 2

Note that you can do the same with as many variables/array elements you want.

The funny thing is that nobody use it, while I see at least one perfect usage. You can think of a typical admin panel of any web system. For sure any developer has programmed the typical table page containing a list of “things” and a paging to switch the result set page. It’s like the posts page from the WordPress admin panel, or a search result page in Google, where you’ve one page of results and at the bottom – a number of pages where you can go to another page of the search results.

What I’ve seen in almost every project is that typically the developers prefer to set the results for the page into one list returned from one method and the count of the entire result set is returned by another method.

Thus most of the times there are two methods, performing most commonly a database queries. Something like – getList($offset, $limit) and getCount() where the first one returns the page and the second one returns the count of the result set.

This will result into two methods, two calls and two lines of code:

function getList($offset, $limit)
{
	...
	// although the entire result set contains
	// 5 elements by limiting it from the parameters
	// only three are returned
	return $list; // where $list = array('title1', 'title2', 'title3');	
}
 
function getCount()
{
	...
	// here's returned the count
	// of the entire result set
	return $count; // where $count = 5;	
}
 
$list  = getList(0, 3);
$count = getCount();

What actually you can do is to perform both queries in one method, perhaps called getItems($offset, $limit) where the returned value is an array containing both the list of results and the count:

function getItems($offset, $limit)
{
	...
	return array('list' => $list, 'count' => $count);
}

And finally when calling this method to list() that into the two variables – single lined.

list($list, $count) = getItems(0, 3);