mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-08-29 22:16:01 +02:00
In 3.0 there was some confusion about whether DataLists and ArrayLists were mutable or not. If DataLists were immutable, they'd return the result, and your code would look like $list = $list->filter(....); If DataLists were mutable, they'd operate on themselves, returning nothing, and your code would look like $list->filter(....); This makes all DataLists and ArrayList immutable for all _searching_ operations. Operations on DataList that modify the underlying SQL data store remain mutating. - These functions no longer mutate the existing object, and if you do not capture the value returned by them will have no effect: ArrayList#reverse ArrayList#sort ArrayList#filter ArrayList#exclude DataList#dataQuery (use DataList#alterDataQuery to modify dataQuery in a safe manner) DataList#where DataList#limit DataList#sort DataList#addFilter DataList#applyFilterContext DataList#innerJoin DataList#leftJoin DataList#find DataList#byIDs DataList#reverse - DataList#setDataQueryParam has been added as syntactic sugar around the most common cause of accessing the dataQuery directly - setting query parameters - RelationList#setForeignID has been removed. Always use RelationList#forForeignID when querying, and overload RelationList#foreignIDList when subclassing. - Relatedly,the protected variable RelationList->foreignID has been removed, as the ID is now stored on a query parameter. Use RelationList#getForeignID to read it.
422 lines
11 KiB
PHP
422 lines
11 KiB
PHP
<?php
|
|
|
|
/**
|
|
* An ArrayList that represents an unsaved relation.
|
|
*
|
|
* has_many and many_many relations cannot be saved until after the DataObject they're
|
|
* on has been written. This List pretends to be a RelationList and stores the related
|
|
* objects in memory.
|
|
*
|
|
* It can store both saved objects (as IDs) or unsaved objects (as instances of
|
|
* $dataClass). Unsaved objects are then written when the list is saved into an instance
|
|
* of RelationList.
|
|
*
|
|
* Most methods that alter the list of objects throw LogicExceptions.
|
|
*/
|
|
class UnsavedRelationList extends ArrayList {
|
|
/**
|
|
* The DataObject class name that this relation is on
|
|
*
|
|
* @var string
|
|
*/
|
|
protected $baseClass;
|
|
|
|
/**
|
|
* The name of the relation
|
|
*
|
|
* @var string
|
|
*/
|
|
protected $relationName;
|
|
|
|
/**
|
|
* The DataObject class name that this relation is querying
|
|
*
|
|
* @var string
|
|
*/
|
|
protected $dataClass;
|
|
|
|
/**
|
|
* The extra fields associated with the relation
|
|
*
|
|
* @var array
|
|
*/
|
|
protected $extraFields = array();
|
|
|
|
/**
|
|
* Create a new UnsavedRelationList
|
|
*
|
|
* @param string $dataClass The DataObject class used in the relation
|
|
*/
|
|
public function __construct($baseClass, $relationName, $dataClass) {
|
|
$this->baseClass = $baseClass;
|
|
$this->relationName = $relationName;
|
|
$this->dataClass = $dataClass;
|
|
}
|
|
|
|
/**
|
|
* Add an item to this relationship
|
|
*
|
|
* @param $extraFields A map of additional columns to insert into the joinTable in the case of a many_many relation
|
|
*/
|
|
public function add($item, $extraFields = null) {
|
|
$this->push($item, $extraFields);
|
|
}
|
|
|
|
/**
|
|
* Save all the items in this list into the RelationList
|
|
*
|
|
* @param RelationList $list
|
|
*/
|
|
public function changeToList(RelationList $list) {
|
|
foreach($this->items as $key => $item) {
|
|
if(is_object($item)) {
|
|
$item->write();
|
|
}
|
|
$list->add($item, $this->extraFields[$key]);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Pushes an item onto the end of this list.
|
|
*
|
|
* @param array|object $item
|
|
*/
|
|
public function push($item, $extraFields = null) {
|
|
if((is_object($item) && !$item instanceof $this->dataClass)
|
|
|| (!is_object($item) && !is_numeric($item))) {
|
|
throw new InvalidArgumentException(
|
|
"UnsavedRelationList::add() expecting a $this->dataClass object, or ID value",
|
|
E_USER_ERROR);
|
|
}
|
|
if(is_object($item) && $item->ID) {
|
|
$item = $item->ID;
|
|
}
|
|
$this->extraFields[] = $extraFields;
|
|
parent::push($item);
|
|
}
|
|
|
|
/**
|
|
* Get the dataClass name for this relation, ie the DataObject ClassName
|
|
*
|
|
* @return string
|
|
*/
|
|
public function dataClass() {
|
|
return $this->dataClass;
|
|
}
|
|
|
|
/**
|
|
* Returns an Iterator for this relation.
|
|
*
|
|
* @return ArrayIterator
|
|
*/
|
|
public function getIterator() {
|
|
return new ArrayIterator($this->toArray());
|
|
}
|
|
|
|
/**
|
|
* Return an array of the actual items that this relation contains at this stage.
|
|
* This is when the query is actually executed.
|
|
*
|
|
* @return array
|
|
*/
|
|
public function toArray() {
|
|
$items = array();
|
|
foreach($this->items as $key => $item) {
|
|
if(is_numeric($item)) {
|
|
$item = DataObject::get_by_id($this->dataClass, $item);
|
|
}
|
|
if(!empty($this->extraFields[$key])) {
|
|
$item->update($this->extraFields[$key]);
|
|
}
|
|
$items[] = $item;
|
|
}
|
|
return $items;
|
|
}
|
|
|
|
/**
|
|
* Add a number of items to the relation.
|
|
*
|
|
* @param array $items Items to add, as either DataObjects or IDs.
|
|
* @return DataList
|
|
*/
|
|
public function addMany($items) {
|
|
foreach($items as $item) {
|
|
$this->add($item);
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Returns true if the given column can be used to filter the records.
|
|
*/
|
|
public function canFilterBy($by) {
|
|
return false;
|
|
}
|
|
|
|
|
|
/**
|
|
* Returns true if the given column can be used to sort the records.
|
|
*/
|
|
public function canSortBy($by) {
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Remove all items from this relation.
|
|
*/
|
|
public function removeAll() {
|
|
$this->items = array();
|
|
$this->extraFields = array();
|
|
}
|
|
|
|
/**
|
|
* Remove the items from this list with the given IDs
|
|
*
|
|
* @param array $idList
|
|
*/
|
|
public function removeMany($items) {
|
|
$this->items = array_diff($this->items, $items);
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Removes items from this list which are equal.
|
|
*
|
|
* @param string $field unused
|
|
*/
|
|
public function removeDuplicates($field = 'ID') {
|
|
$this->items = array_unique($this->items);
|
|
}
|
|
|
|
/**
|
|
* Sets the Relation to be the given ID list.
|
|
* Records will be added and deleted as appropriate.
|
|
*
|
|
* @param array $idList List of IDs.
|
|
*/
|
|
public function setByIDList($idList) {
|
|
$this->removeAll();
|
|
$this->addMany($idList);
|
|
}
|
|
|
|
/**
|
|
* Returns the first item in the list
|
|
*
|
|
* @return mixed
|
|
*/
|
|
public function first() {
|
|
$item = reset($this->items);
|
|
if(is_numeric($item)) {
|
|
$item = DataObject::get_by_id($this->dataClass, $item);
|
|
}
|
|
if(!empty($this->extraFields[key($this->items)])) {
|
|
$item->update($this->extraFields[key($this->items)]);
|
|
}
|
|
return $item;
|
|
}
|
|
|
|
/**
|
|
* Returns the last item in the list
|
|
*
|
|
* @return mixed
|
|
*/
|
|
public function last() {
|
|
$item = end($this->items);
|
|
if(!empty($this->extraFields[key($this->items)])) {
|
|
$item->update($this->extraFields[key($this->items)]);
|
|
}
|
|
return $item;
|
|
}
|
|
|
|
/**
|
|
* Returns an array of a single field value for all items in the list.
|
|
*
|
|
* @param string $colName
|
|
* @return array
|
|
*/
|
|
public function column($colName = 'ID') {
|
|
$list = new ArrayList($this->toArray());
|
|
return $list->column('ID');
|
|
}
|
|
|
|
/**
|
|
* Returns a copy of this list with the relationship linked to the given foreign ID.
|
|
* @param $id An ID or an array of IDs.
|
|
*/
|
|
public function forForeignID($id) {
|
|
$class = singleton($this->baseClass);
|
|
$class->ID = 1;
|
|
return $class->{$this->relationName}()->forForeignID($id);
|
|
}
|
|
|
|
/**
|
|
* Return the DBField object that represents the given field on the related class.
|
|
*
|
|
* @param string $fieldName Name of the field
|
|
* @return DBField The field as a DBField object
|
|
*/
|
|
public function dbObject($fieldName) {
|
|
return singleton($this->dataClass)->dbObject($fieldName);
|
|
}
|
|
|
|
/**#@+
|
|
* Prevents calling DataList methods that rely on the objects being saved
|
|
*/
|
|
public function addFilter() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function alterDataQuery() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function avg() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function byIDs() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function byID($id) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function dataQuery() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function exclude() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function filter() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function getIDList() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function getRange($offset, $length) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function getRelationName() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function innerJoin() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function insertFirst() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function join() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function leftJoin() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function limit($length, $offset = 0) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function map($keyField = 'ID', $titleField = 'Title') {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function max() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function merge($with) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function min() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function newObject() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function offsetExists($offset) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function offsetGet($offset) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function offsetSet($offset, $value) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function offsetUnset($offset) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function pop() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function relation() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function removeByFilter() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function removeByID() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function reverse() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function setDataModel() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function setDataQuery() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function setQueriedColumns() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function shift() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function sql() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function subtract() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function sum() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function unshift($item) {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
|
|
public function where() {
|
|
throw new LogicException(__FUNCTION__ . " can't be called on an UnsavedRelationList.");
|
|
}
|
|
/**#@-*/
|
|
}
|