/
DBField.php
382 lines (335 loc) · 9.12 KB
/
DBField.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
<?php
namespace SilverStripe\ORM\FieldType;
use FormField;
use SearchFilter;
use SilverStripe\ORM\Connect\SS_Query;
use SilverStripe\ORM\DataObject;
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 orm
*/
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 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.
*/
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);
}
/**
* Return JSON encoded value
* @return string
*/
public function JSON() {
return Convert::raw2json($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)
*
* @param string|bool $name
* @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();
}
}