mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-08-26 12:36:07 +02:00
API: Deprecate SS_Datetime. The DBField subclasses are have all been renamed to start with “DB” and be in the SilverStripe\Model\FieldType namespace. To keep DataObject definitions concise, the original short variations of their names are preserved as service definitions. Most of the field generation code doesn’t need to change, but where field classes are referenced directly, changes will be needed. SS_Datetime, which is commonly referenced outside the model system itself, has been preserved as a subclass of DBDatetime. This has been marked as deprecated and can be removed in SilverStripe 5. A few places that referred to $db and $casting values weren’t using the Injector to instantiate the relevant classes. This meant that the remapping we have created as part of moving classes into a namespace didn’t work.
370 lines
8.9 KiB
PHP
370 lines
8.9 KiB
PHP
<?php
|
|
|
|
namespace SilverStripe\Model\FieldType;
|
|
|
|
use ViewableData;
|
|
use Convert;
|
|
use Object;
|
|
use TextField;
|
|
|
|
/**
|
|
* 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>
|
|
*
|
|
* @todo remove MySQL specific code from subclasses
|
|
*
|
|
* @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();
|
|
}
|
|
}
|