interface Relation implements SS_List, Filterable, Sortable, Limitable (View source)

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

Below methods will be added in 5.x

Methods

public
T[]
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
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
T|null
first()

Returns the first item in the list.

from  SS_List
public
T|null
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
T|null
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
T>
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.

public
T>
filter()

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

public
T>
filterAny()

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

public
T>
exclude()

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

public
T>
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
T|null
byID(int $id)

Return the first item with the given ID

public
T>
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.

from  Sortable
public
T>
sort()

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  Sortable
public
T>
reverse()

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

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

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

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
dbObject(string $fieldName)

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

relation(mixed $relationName)

No description

forForeignID(mixed $id)

No description

string
dataClass()

No description

Details

T[] toArray()

Returns all the items in the list in an array.

Return Value

T[]

array toNestedArray()

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

Return Value

array

add(mixed $item)

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

Parameters

mixed $item

remove(mixed $item)

Removes an item from the list.

Parameters

mixed $item

T|null first()

Returns the first item in the list.

Return Value

T|null

T|null last()

Returns the last item in the list.

Return Value

T|null

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

T|null 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

T|null

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

T> each(callable $callback)

Walks the list using the specified callback

Parameters

callable $callback

Return Value

T>

bool canFilterBy(string $by)

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

Parameters

string $by

Return Value

bool

T> filter()

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

Return Value

T>

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

T> filterAny()

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

Return Value

T>

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

T> exclude()

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

Return Value

T>

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

T> 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

T>

Examples

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

T|null byID(int $id)

Return the first item with the given ID

Parameters

int $id

Return Value

T|null

T> byIDs(array $ids)

Filter this list to only contain the given Primary IDs

Parameters

array $ids

Array of integers

Return Value

T>

bool canSortBy(string $by)

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

Parameters

string $by

Return Value

bool

T> sort()

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.

Return Value

T>

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

T> reverse()

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

Return Value

T>

Examples

$list = $list->reverse();

Limitable 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

Limitable

Exceptions

InvalidArgumentException

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.

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[]

DBField dbObject(string $fieldName)

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

Parameters

string $fieldName

Name of the field

Return Value

DBField

The field as a DBField object

Relation relation(mixed $relationName)

No description

Parameters

mixed $relationName

Return Value

Relation

Relation forForeignID(mixed $id)

No description

Parameters

mixed $id

Return Value

Relation

string dataClass()

No description

Return Value

string