interface CompositeDBField (View source)

Apply this interface to any DBField that doesn't have a 1-1 mapping with a database field.

This includes multi-value fields and transformed fields

Unittests for loading and saving composite values (see GIS module for existing similiar unittests) Example with a combined street name and number: class Street extends DBField implements CompositeDBField { protected $streetNumber; protected $streetName; protected $isChanged = false; static $composite_db = return array( "Number" => "Int", "Name" => "Text" ); function requireField() { DB::requireField($this->tableName, "{$this->name}Number", 'Int'); DB::requireField($this->tableName, "{$this->name}Name", 'Text'); } function writeToManipulation(&$manipulation) { if($this->getStreetName()) { $manipulation['fields']["{$this->name}Name"] = $this->prepValueForDB($this->getStreetName()); } else { $manipulation['fields']["{$this->name}Name"] = DBField::create_field('Varchar', $this->getStreetName()) ->nullValue(); } if($this->getStreetNumber()) { $manipulation['fields']["{$this->name}Number"] = $this->prepValueForDB($this->getStreetNumber()); } else { $manipulation['fields']["{$this->name}Number"] = DBField::create_field('Int', $this->getStreetNumber()) ->nullValue(); } } function addToQuery(&$query) { parent::addToQuery($query); $query->setSelect("{$this->name}Number"); $query->setSelect("{$this->name}Name"); } function setValue($value, $record = null, $markChanged=true) { if ($value instanceof Street && $value->exists()) { $this->setStreetName($value->getStreetName(), $markChanged); $this->setStreetNumber($value->getStreetNumber(), $markChanged); if($markChanged) $this->isChanged = true; } else if($record && isset($record[$this->name . 'Name']) && isset($record[$this->name . 'Number'])) { if($record[$this->name . 'Name'] && $record[$this->name . 'Number']) { $this->setStreetName($record[$this->name . 'Name'], $markChanged); $this->setStreetNumber($record[$this->name . 'Number'], $markChanged); } if($markChanged) $this->isChanged = true; } else if (is_array($value)) { if (array_key_exists('Name', $value)) { $this->setStreetName($value['Name'], $markChanged); } if (array_key_exists('Number', $value)) { $this->setStreetNumber($value['Number'], $markChanged); } if($markChanged) $this->isChanged = true; } } function setStreetNumber($val, $markChanged=true) { $this->streetNumber = $val; if($markChanged) $this->isChanged = true; } function setStreetName($val, $markChanged=true) { $this->streetName = $val; if($markChanged) $this->isChanged = true; } function getStreetNumber() { return $this->streetNumber; } function getStreetName() { return $this->streetName; } function isChanged() { return $this->isChanged; } function exists() { return ($this->getStreetName() || $this->getStreetNumber()); } }

Methods

public
setValue(DBField|array $value, DataObject|array $record = null, bool $markChanged = true)

Set the value of this field in various formats.

public
writeToManipulation(array $manipulation)

Add the custom internal values to an INSERT or UPDATE request passed through the ORM with DataObject->write().

public
addToQuery(SQLQuery $query)

Add all columns which are defined through requireField() and $composite_db, or any additional SQL that is required to get to these columns. Will mostly just write to the SQLQuery->select array.

public
array
compositeDatabaseFields()

Return array in the format of $composite_db.

public
bool
isChanged()

Determines if the field has been changed since its initialization.

public
bool
exists()

Determines if any of the properties in this field have a value, meaning at least one of them is not NULL.

Details

setValue(DBField|array $value, DataObject|array $record = null, bool $markChanged = true)

Set the value of this field in various formats.

Used by DataObject->getField()}, {@link DataObject->setCastedField() DataObject->dbObject()} and {@link DataObject->write().

As this method is used both for initializing the field after construction, and actually changing its values, it needs a $markChanged parameter.

Parameters

DBField|array $value
DataObject|array $record

An array or object that this field is part of

bool $markChanged

Indicate wether this field should be marked changed. Set to FALSE if you are initializing this field after construction, rather than setting a new value.

writeToManipulation(array $manipulation)

Add the custom internal values to an INSERT or UPDATE request passed through the ORM with DataObject->write().

Fields are added in $manipulation['fields']. Please ensure these fields are escaped for database insertion, as no further processing happens before running the query. Use DBField->prepValueForDB(). Ensure to write NULL or empty values as well to allow unsetting a previously set field. Use DBField->nullValue() for the appropriate type.

Parameters

array $manipulation

addToQuery(SQLQuery $query)

Add all columns which are defined through requireField() and $composite_db, or any additional SQL that is required to get to these columns. Will mostly just write to the SQLQuery->select array.

Parameters

SQLQuery $query

array compositeDatabaseFields()

Return array in the format of $composite_db.

Used by DataObject->hasOwnDatabaseField().

Return Value

array

bool isChanged()

Determines if the field has been changed since its initialization.

Most likely relies on an internal flag thats changed when calling setValue() or any other custom setters on the object.

Return Value

bool

bool exists()

Determines if any of the properties in this field have a value, meaning at least one of them is not NULL.

Return Value

bool