Version 4 supported
This version of Silverstripe CMS is still supported though will not receive any additional features. Go to documentation for the most recent stable version.

Managing lists

Whenever using the ORM to fetch records or navigate relationships you will receive an SS_List instance commonly as either DataList or RelationList. This object gives you the ability to iterate over each of the results or modify.

Iterating over the list

SS_List implements IteratorAggregate, allowing you to loop over the instance.

use SilverStripe\Security\Member;

$members = Member::get();

foreach ($members as $member) {
    echo $member->Name;
}

Or in the template engine:

<% loop $Members %>
    <!-- -->
<% end_loop %>

Finding an item by value

// $list->find($key, $value);

$members = Member::get();

echo $members->find('ID', 4)->FirstName;
// returns 'Sam'

Maps

A map is an array where the array indexes contain data as well as the values. You can build a map from any list

$members = Member::get()->map('ID', 'FirstName');

// $members = [
//    1 => 'Sam'
//    2 => 'Sig'
//    3 => 'Will'
// ];

This functionality is provided by the Map class, which can be used to build a map around any SS_List.

$members = Member::get();
$map = new Map($members, 'ID', 'FirstName');

Column

$members = Member::get();

echo $members->column('Email');

// returns [
//    'sam@silverstripe.com',
//    'sig@silverstripe.com',
//    'will@silverstripe.com'
// ];

Iterating over a large list

When iterating over a DataList, all DataObjects in the list will be loaded in memory. This can consume a lot of memory when working with a large data set.

To limit the number of DataObjects loaded in memory, you can use the chunkedFetch() method on your DataList. In most cases, you can iterate over the results of chunkedFetch() the same way you would iterate over your DataList. Internally, chunkedFetch() will split your DataList query into smaller queries and keep running through them until it runs out of results.

$members = Member::get();
foreach ($members as $member) {
    echo $member->Email;
}

// This call will produce the same output, but it will use less memory and run more queries against the database
$members = Member::get()->chunkedFetch();
foreach ($members as $member) {
    echo $member->Email;
}

chunkedFetch() will respect any filter or sort condition applied to the DataList. By default, chunk will limit each query to 1000 results. You can explicitly set this limit by passing an integer to chunkedFetch().

$members = Member::get()
    ->filter('Email:PartialMatch', 'silverstripe.com')
    ->sort('Email')
    ->chunkedFetch(10);
foreach ($members as $member) {
    echo $member->Email;
}

There are some limitations:

  • chunkedFetch() will ignore any limit or offset you have applied to your DataList
  • you cannot "count" a chunked list or do any other call against it aside from iterating it
  • while iterating over a chunked list, you cannot perform any operation that would alter the order of the items.

ArrayList

ArrayList exists to wrap a standard PHP array in the same API as a database backed list.

$sam = Member::get()->byId(5);
$sig = Member::get()->byId(6);

$list = new ArrayList();
$list->push($sam);
$list->push($sig);

echo $list->Count();
// returns '2'

Related lessons

API documentation

Edit on Github