1. interface
  2. SilverStripe
  3. \
  4. ORM
  5. \
  6. Relation

Relation

interface Relation implements SS_List (View source)

Abstract representation of a DB relation field, either saved or in memory

Below methods will be added in 5.x

Methods

public
array
toArray()

Returns all the items in the list in an array.

from  SS_List
public
array
toNestedArray()

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

from  SS_List
public
void
add(mixed $item)

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

from  SS_List
public
remove(mixed $item)

Removes an item from the list.

from  SS_List
public
mixed
first()

Returns the first item in the list.

from  SS_List
public
mixed
last()

Returns the last item in the list.

from  SS_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.

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

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

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

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

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

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

from  SS_List
public
SS_List
each(callable $callback)

Walks the list using the specified callback

from  SS_List
public
bool
canFilterBy(string $by)

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

from  SS_List
public
bool
exists()

Returns true if this list has items

from  SS_List
public
SS_List
filter(...$args)

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

from  SS_List
public
SS_List
filterAny(...$args)

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

from  SS_List
public
SS_List
exclude(...$args)

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

from  SS_List
public
SS_List
excludeAny(...$args)

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

from  SS_List
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.

from  SS_List
public
mixed
byID(mixed $id)

Return the first item with the given ID

from  SS_List
public
SS_List
byIDs(array $ids)

Filter this list to only contain the given Primary IDs

from  SS_List
public
bool
canSortBy(string $by)

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

from  SS_List
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.

from  SS_List
public
SS_List
reverse()

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

from  SS_List
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.

from  SS_List
public
setByIDList(int[] $idList)

Sets the ComponentSet to be the given ID list.

public
int[]
getIDList()

Returns an array with both the keys and values set to the IDs of the records in this list.

public
DBField|null
dbObject(string $fieldName)

Return the DBField object that represents the given field on the related class.

Relation
relation(mixed $relationName)

No description

Relation
forForeignID(mixed $id)

No description

string
dataClass()

No description

Details

in SS_List at line 24
array toArray()

Returns all the items in the list in an array.

Return Value

array

in SS_List at line 29
array toNestedArray()

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

Return Value

array

in SS_List 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

in SS_List 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

in SS_List at line 50
mixed first()

Returns the first item in the list.

Return Value

mixed

in SS_List at line 57
mixed last()

Returns the last item in the list.

Return Value

mixed

in SS_List 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

in SS_List 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

in SS_List 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

in SS_List 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

in SS_List at line 88
SS_List each(callable $callback)

Walks the list using the specified callback

Parameters

callable $callback

Return Value

SS_List

in 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

in SS_List at line 98
bool exists()

Returns true if this list has items

Return Value

bool

in SS_List 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

in SS_List 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'))

in SS_List 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

in SS_List 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

in 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; })

in SS_List at line 174
mixed byID(mixed $id)

Return the first item with the given ID

Parameters

mixed $id

Return Value

mixed

in SS_List 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

in 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

in SS_List 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'));

in SS_List 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();

in SS_List 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

at line 29
setByIDList(int[] $idList)

Sets the ComponentSet to be the given ID list.

Records will be added and deleted as appropriate.

Parameters

int[] $idList

List of IDs.

at line 38
int[] getIDList()

Returns an array with both the keys and values set to the IDs of the records in this list.

Does not return the IDs for unsaved DataObjects

Return Value

int[]

at line 43
DBField|null dbObject(string $fieldName)

Return the DBField object that represents the given field on the related class.

Parameters

string $fieldName

Return Value

DBField|null

at line 20
Relation relation(mixed $relationName)

No description

Parameters

mixed $relationName

Return Value

Relation

at line 20
Relation forForeignID(mixed $id)

No description

Parameters

mixed $id

Return Value

Relation

at line 20
string dataClass()

No description

Return Value

string