mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-08 18:51:12 +02:00
API Refactor ClassName into DBClassName API Update PolymorphicForeignKey to use new CompositeDBField and DBClassName CompositeDBField is now an interface to nested fields on an underlying dataobject, allowing field manipulation to be performed at the field and dataobject level without having to synchronise them manually.
360 lines
8.7 KiB
PHP
360 lines
8.7 KiB
PHP
<?php
|
|
/**
|
|
* Single field in the database.
|
|
*
|
|
* Every field from the database is represented as a sub-class of DBField.
|
|
*
|
|
* <b>Multi-value DBField objects</b>
|
|
*
|
|
* Sometimes you will want to make DBField classes that don't have a 1-1 match
|
|
* to database fields. To do this, there are a number of fields for you to
|
|
* overload:
|
|
*
|
|
* - Overload {@link writeToManipulation} to add the appropriate references to
|
|
* the INSERT or UPDATE command
|
|
* - Overload {@link addToQuery} to add the appropriate items to a SELECT
|
|
* query's field list
|
|
* - Add appropriate accessor methods
|
|
*
|
|
* <b>Subclass Example</b>
|
|
*
|
|
* The class is easy to overload with custom types, e.g. the MySQL "BLOB" type
|
|
* (http://dev.mysql.com/doc/refman/5.0/en/blob.html).
|
|
*
|
|
* <code>
|
|
* class Blob extends DBField {
|
|
* function requireField() {
|
|
* DB::requireField($this->tableName, $this->name, "blob");
|
|
* }
|
|
* }
|
|
* </code>
|
|
*
|
|
* @package framework
|
|
* @subpackage model
|
|
*/
|
|
abstract class DBField extends ViewableData {
|
|
|
|
protected $value;
|
|
|
|
protected $tableName;
|
|
|
|
protected $name;
|
|
|
|
protected $arrayValue;
|
|
|
|
/**
|
|
* The escape type for this field when inserted into a template - either "xml" or "raw".
|
|
*
|
|
* @var string
|
|
* @config
|
|
*/
|
|
private static $escape_type = 'raw';
|
|
|
|
/**
|
|
* Subclass of {@link SearchFilter} for usage in {@link defaultSearchFilter()}.
|
|
*
|
|
* @var string
|
|
* @config
|
|
*/
|
|
private static $default_search_filter_class = 'PartialMatchFilter';
|
|
|
|
/**
|
|
* @var $default mixed Default-value in the database.
|
|
* Might be overridden on DataObject-level, but still useful for setting defaults on
|
|
* already existing records after a db-build.
|
|
*/
|
|
protected $defaultVal;
|
|
|
|
public function __construct($name = null) {
|
|
$this->name = $name;
|
|
|
|
parent::__construct();
|
|
}
|
|
|
|
/**
|
|
* Create a DBField object that's not bound to any particular field.
|
|
*
|
|
* Useful for accessing the classes behaviour for other parts of your code.
|
|
*
|
|
* @param string $className class of field to construct
|
|
* @param mixed $value value of field
|
|
* @param string $name Name of field
|
|
* @param mixed $object Additional parameter to pass to field constructor
|
|
* @return DBField
|
|
*/
|
|
public static function create_field($className, $value, $name = null, $object = null) {
|
|
$dbField = Object::create($className, $name, $object);
|
|
$dbField->setValue($value, null, false);
|
|
|
|
return $dbField;
|
|
}
|
|
|
|
/**
|
|
* Set the name of this field.
|
|
*
|
|
* The name should never be altered, but it if was never given a name in
|
|
* the first place you can set a name.
|
|
*
|
|
* If you try an alter the name a warning will be thrown.
|
|
*
|
|
* @param string $name
|
|
*
|
|
* @return DBField
|
|
*/
|
|
public function setName($name) {
|
|
if($this->name && $this->name !== $name) {
|
|
user_error("DBField::setName() shouldn't be called once a DBField already has a name."
|
|
. "It's partially immutable - it shouldn't be altered after it's given a value.", E_USER_WARNING);
|
|
}
|
|
|
|
$this->name = $name;
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Returns the name of this field.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function getName() {
|
|
return $this->name;
|
|
}
|
|
|
|
/**
|
|
* Returns the value of this field.
|
|
*
|
|
* @return mixed
|
|
*/
|
|
public function getValue() {
|
|
return $this->value;
|
|
}
|
|
|
|
/**
|
|
* Set the value of this field in various formats.
|
|
* Used by {@link DataObject->getField()}, {@link DataObject->setCastedField()}
|
|
* {@link 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 {@link $markChanged}
|
|
* parameter.
|
|
*
|
|
* @param mixed $value
|
|
* @param DataObject|array $record An array or object that this field is part of
|
|
* @param boolean $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.
|
|
*/
|
|
public function setValue($value, $record = null, $markChanged = true) {
|
|
$this->value = $value;
|
|
}
|
|
|
|
|
|
/**
|
|
* Determines if the field has a value which is not considered to be 'null'
|
|
* in a database context.
|
|
*
|
|
* @return boolean
|
|
*/
|
|
public function exists() {
|
|
return (bool)$this->value;
|
|
}
|
|
|
|
/**
|
|
* Return the transformed value ready to be sent to the database. This value
|
|
* will be escaped automatically by the prepared query processor, so it
|
|
* should not be escaped or quoted at all.
|
|
*
|
|
* The field values could also be in paramaterised format, such as
|
|
* array('MAX(?,?)' => array(42, 69)), allowing the use of raw SQL values such as
|
|
* array('NOW()' => array()).
|
|
*
|
|
* @see SQLWriteExpression::addAssignments for syntax examples
|
|
*
|
|
* @param $value mixed The value to check
|
|
* @return mixed The raw value, or escaped parameterised details
|
|
*/
|
|
public function prepValueForDB($value) {
|
|
if($value === null || $value === "" || $value === false) {
|
|
return null;
|
|
} else {
|
|
return $value;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Prepare the current field for usage in a
|
|
* database-manipulation (works on a manipulation reference).
|
|
*
|
|
* Make value safe for insertion into
|
|
* a SQL SET statement by applying addslashes() -
|
|
* can also be used to apply special SQL-commands
|
|
* to the raw value (e.g. for GIS functionality).
|
|
* {@see prepValueForDB}
|
|
*
|
|
* @param array $manipulation
|
|
*/
|
|
public function writeToManipulation(&$manipulation) {
|
|
$manipulation['fields'][$this->name] = $this->exists()
|
|
? $this->prepValueForDB($this->value) : $this->nullValue();
|
|
}
|
|
|
|
/**
|
|
* Add custom query parameters for this field,
|
|
* mostly SELECT statements for multi-value fields.
|
|
*
|
|
* By default, the ORM layer does a
|
|
* SELECT <tablename>.* which
|
|
* gets you the default representations
|
|
* of all columns.
|
|
*
|
|
* @param SS_Query $query
|
|
*/
|
|
public function addToQuery(&$query) {
|
|
|
|
}
|
|
|
|
/**
|
|
* Assign this DBField to a table
|
|
*
|
|
* @param string $tableName
|
|
* @return $this
|
|
*/
|
|
public function setTable($tableName) {
|
|
$this->tableName = $tableName;
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Get the table this field belongs to, if assigned
|
|
*
|
|
* @return string|null
|
|
*/
|
|
public function getTable() {
|
|
return $this->tableName;
|
|
}
|
|
|
|
/**
|
|
* @return string
|
|
*/
|
|
public function forTemplate() {
|
|
return $this->XML();
|
|
}
|
|
|
|
public function HTMLATT() {
|
|
return Convert::raw2htmlatt($this->value);
|
|
}
|
|
|
|
public function URLATT() {
|
|
return urlencode($this->value);
|
|
}
|
|
|
|
public function RAWURLATT() {
|
|
return rawurlencode($this->value);
|
|
}
|
|
|
|
public function ATT() {
|
|
return Convert::raw2att($this->value);
|
|
}
|
|
|
|
public function RAW() {
|
|
return $this->value;
|
|
}
|
|
|
|
public function JS() {
|
|
return Convert::raw2js($this->value);
|
|
}
|
|
|
|
public function HTML(){
|
|
return Convert::raw2xml($this->value);
|
|
}
|
|
|
|
public function XML(){
|
|
return Convert::raw2xml($this->value);
|
|
}
|
|
|
|
/**
|
|
* Returns the value to be set in the database to blank this field.
|
|
* Usually it's a choice between null, 0, and ''
|
|
*
|
|
* @return mixed
|
|
*/
|
|
public function nullValue() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Saves this field to the given data object.
|
|
*/
|
|
public function saveInto($dataObject) {
|
|
$fieldName = $this->name;
|
|
if($fieldName) {
|
|
$dataObject->$fieldName = $this->value;
|
|
} else {
|
|
user_error("DBField::saveInto() Called on a nameless '" . get_class($this) . "' object", E_USER_ERROR);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns a FormField instance used as a default
|
|
* for form scaffolding.
|
|
*
|
|
* Used by {@link SearchContext}, {@link ModelAdmin}, {@link DataObject::scaffoldFormFields()}
|
|
*
|
|
* @param string $title Optional. Localized title of the generated instance
|
|
* @return FormField
|
|
*/
|
|
public function scaffoldFormField($title = null) {
|
|
$field = new TextField($this->name, $title);
|
|
|
|
return $field;
|
|
}
|
|
|
|
/**
|
|
* Returns a FormField instance used as a default
|
|
* for searchform scaffolding.
|
|
*
|
|
* Used by {@link SearchContext}, {@link ModelAdmin}, {@link DataObject::scaffoldFormFields()}.
|
|
*
|
|
* @param string $title Optional. Localized title of the generated instance
|
|
* @return FormField
|
|
*/
|
|
public function scaffoldSearchField($title = null) {
|
|
return $this->scaffoldFormField($title);
|
|
}
|
|
|
|
/**
|
|
* @todo documentation
|
|
*
|
|
* @todo figure out how we pass configuration parameters to
|
|
* search filters (note: parameter hack now in place to pass in the required full path - using $this->name
|
|
* won't work)
|
|
*
|
|
* @return SearchFilter
|
|
*/
|
|
public function defaultSearchFilter($name = false) {
|
|
$name = ($name) ? $name : $this->name;
|
|
$filterClass = $this->stat('default_search_filter_class');
|
|
return new $filterClass($name);
|
|
}
|
|
|
|
/**
|
|
* Add the field to the underlying database.
|
|
*/
|
|
abstract public function requireField();
|
|
|
|
public function debug() {
|
|
return <<<DBG
|
|
<ul>
|
|
<li><b>Name:</b>{$this->name}</li>
|
|
<li><b>Table:</b>{$this->tableName}</li>
|
|
<li><b>Value:</b>{$this->value}</li>
|
|
</ul>
|
|
DBG;
|
|
}
|
|
|
|
public function __toString() {
|
|
return $this->forTemplate();
|
|
}
|
|
}
|