1. interface
  2. SilverStripe
  3. \
  4. Model
  5. \
  6. List
  7. \
  8. SS_List

SS_List

interface SS_List implements ArrayAccess, Countable, IteratorAggregate (View source)

An interface that a class can implement to be treated as a list container.

Methods

public
array
toArray()

Returns all the items in the list in an array.

public
array
toNestedArray()

Returns the contents of the list as an array of maps.

public
void
add(mixed $item)

Adds an item to the list, making no guarantees about where it will appear.

public
remove(mixed $item)

Removes an item from the list.

public
mixed
first()

Returns the first item in the list.

public
mixed
last()

Returns the last item in the list.

public
Map
map(string $keyfield = 'ID', string $titlefield = 'Title')

Returns a map of a key field to a value field of all the items in the list.

public
mixed
find(string $key, mixed $value)

Returns the first item in the list where the key field is equal to the value.

public
array
column(string $colName = "ID")

Returns an array of a single field value for all items in the list.

public
array
columnUnique(string $colName = 'ID')

Returns a unique array of a single field value for all items in the list.

public
SS_List
each(callable $callback)

Walks the list using the specified callback

public
bool
canFilterBy(string $by)

Returns TRUE if the list can be filtered by a given field expression.

public
bool
exists()

Returns true if this list has items

public
SS_List
filter(...$args)

Return a new instance of this list that only includes items with these characteristics

public
SS_List
filterAny(...$args)

Return a copy of this list which contains items matching any of these characteristics.

public
SS_List
exclude(...$args)

Return a new instance of this list that excludes any items with these characteristics

public
SS_List
excludeAny(...$args)

Return a copy of this list which does not contain any items with any of these params

public
SS_List
filterByCallback(callable $callback)

Return a new instance of this list that excludes any items with these characteristics Filter this List by a callback function. The function will be passed each record of the List in turn, and must return true for the record to be included. Returns the filtered list.

public
mixed
byID(mixed $id)

Return the first item with the given ID

public
SS_List
byIDs(array $ids)

Filter this list to only contain the given Primary IDs

public
bool
canSortBy(string $by)

Returns TRUE if the list can be sorted by a field.

public
SS_List
sort(...$args)

Return a new instance of this list that is sorted by one or more fields. You can either pass in a single field name and direction, or a map of field names to sort directions.

public
SS_List
reverse()

Return a new instance of this list based on reversing the current sort.

public
SS_List
limit(int|null $length, int $offset = 0)

Returns a new instance of this list where no more than $limit records are included.

Details

at line 24
array toArray()

Returns all the items in the list in an array.

Return Value

array

at line 29
array toNestedArray()

Returns the contents of the list as an array of maps.

Return Value

array

at line 35
void add(mixed $item)

Adds an item to the list, making no guarantees about where it will appear.

Parameters

mixed $item

Return Value

void

at line 43
remove(mixed $item)

Removes an item from the list.

Note that a return type is not specified on the interface as different impelementations have different return types.

Parameters

mixed $item

at line 50
mixed first()

Returns the first item in the list.

Return Value

mixed

at line 57
mixed last()

Returns the last item in the list.

Return Value

mixed

at line 63
Map map(string $keyfield = 'ID', string $titlefield = 'Title')

Returns a map of a key field to a value field of all the items in the list.

Parameters

string $keyfield
string $titlefield

Return Value

Map

at line 71
mixed find(string $key, mixed $value)

Returns the first item in the list where the key field is equal to the value.

Parameters

string $key
mixed $value

Return Value

mixed

at line 76
array column(string $colName = "ID")

Returns an array of a single field value for all items in the list.

Parameters

string $colName

Return Value

array

at line 81
array columnUnique(string $colName = 'ID')

Returns a unique array of a single field value for all items in the list.

Parameters

string $colName

Return Value

array

at line 88
SS_List each(callable $callback)

Walks the list using the specified callback

Parameters

callable $callback

Return Value

SS_List

at line 93
bool canFilterBy(string $by)

Returns TRUE if the list can be filtered by a given field expression.

Parameters

string $by

Return Value

bool

at line 98
bool exists()

Returns true if this list has items

Return Value

bool

at line 112
SS_List filter(...$args)

Return a new instance of this list that only includes items with these characteristics

Parameters

...$args

Return Value

SS_List

Examples

$list = $list->filter('Name', 'bob'); // only bob in the list
 
$list = $list->filter('Name', array('aziz', 'bob'); // aziz and bob in list
 
$list = $list->filter(array('Name'=>'bob, 'Age'=>21)); // bob with the age 21
 
$list = $list->filter(array('Name'=>'bob, 'Age'=>array(21, 43))); // bob with the Age 21 or 43
 
$list = $list->filter(array('Name'=>array('aziz','bob'), 'Age'=>array(21, 43)));
// aziz with the age 21 or 43 and bob with the Age 21 or 43

at line 136
SS_List filterAny(...$args)

Return a copy of this list which contains items matching any of these characteristics.

Parameters

...$args

Return Value

SS_List

Examples

// only bob in the list
$list = $list->filterAny('Name', 'bob');
// SQL: WHERE "Name" = 'bob'
 
// azis or bob in the list
$list = $list->filterAny('Name', array('aziz', 'bob');
// SQL: WHERE ("Name" IN ('aziz','bob'))
 
// bob or anyone aged 21 in the list
$list = $list->filterAny(array('Name'=>'bob, 'Age'=>21));
// SQL: WHERE ("Name" = 'bob' OR "Age" = '21')
 
// bob or anyone aged 21 or 43 in the list
$list = $list->filterAny(array('Name'=>'bob, 'Age'=>array(21, 43)));
// SQL: WHERE ("Name" = 'bob' OR ("Age" IN ('21', '43'))
 
// all bobs, phils or anyone aged 21 or 43 in the list
$list = $list->filterAny(array('Name'=>array('bob','phil'), 'Age'=>array(21, 43)));
// SQL: WHERE (("Name" IN ('bob', 'phil')) OR ("Age" IN ('21', '43'))

at line 150
SS_List exclude(...$args)

Return a new instance of this list that excludes any items with these characteristics

Parameters

...$args

Return Value

SS_List

Examples

$list = $list->exclude('Name', 'bob'); // exclude bob from list
 
$list = $list->exclude('Name', array('aziz', 'bob'); // exclude aziz and bob from list
 
$list = $list->exclude(array('Name'=>'bob, 'Age'=>21)); // exclude bob that has Age 21
 
$list = $list->exclude(array('Name'=>'bob, 'Age'=>array(21, 43))); // exclude bob with Age 21 or 43
 
$list = $list->exclude(array('Name'=>array('bob','phil'), 'Age'=>array(21, 43)));
// bob age 21 or 43, phil age 21 or 43 would be excluded

at line 157
SS_List excludeAny(...$args)

Return a copy of this list which does not contain any items with any of these params

Parameters

...$args

Return Value

SS_List

at line 167
SS_List filterByCallback(callable $callback)

Return a new instance of this list that excludes any items with these characteristics Filter this List by a callback function. The function will be passed each record of the List in turn, and must return true for the record to be included. Returns the filtered list.

Parameters

callable $callback

Return Value

SS_List

Examples

$list = $list->filterByCallback(function($item, $list) { return $item->Age == 9; })

at line 174
mixed byID(mixed $id)

Return the first item with the given ID

Parameters

mixed $id

Return Value

mixed

at line 181
SS_List byIDs(array $ids)

Filter this list to only contain the given Primary IDs

Parameters

array $ids

Return Value

SS_List

at line 186
bool canSortBy(string $by)

Returns TRUE if the list can be sorted by a field.

Parameters

string $by

Return Value

bool

at line 199
SS_List sort(...$args)

Return a new instance of this list that is sorted by one or more fields. You can either pass in a single field name and direction, or a map of field names to sort directions.

Parameters

...$args

Return Value

SS_List

Examples

$list = $list->sort('Name'); // default ASC sorting
 
$list = $list->sort('Name DESC'); // DESC sorting
 
$list = $list->sort('Name', 'ASC');
 
$list = $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));

at line 209
SS_List reverse()

Return a new instance of this list based on reversing the current sort.

Return Value

SS_List

Examples

$list = $list->reverse();

at line 221
SS_List limit(int|null $length, int $offset = 0)

Returns a new instance of this list where no more than $limit records are included.

If $offset is specified, then that many records at the beginning of the list will be skipped. This matches the behaviour of the SQL LIMIT clause.

If $length is null, then no limit is applied. If $length is 0, then an empty list is returned.

Parameters

int|null $length
int $offset

Return Value

SS_List

Exceptions

InvalidArgumentException