2014-10-27 04:40:02 +01:00
title: Data Types, Overloading and Casting
2014-10-28 04:45:46 +01:00
summary: Learn how how data is stored going in and coming out of the ORM and how to modify it.
2014-10-27 04:40:02 +01:00
2012-06-23 00:32:43 +02:00
# Data Types and Casting
2011-02-07 07:48:44 +01:00
2017-07-03 03:22:12 +02:00
Each model in a SilverStripe [DataObject ](api:SilverStripe\ORM\DataObject ) will handle data at some point. This includes database columns such as
2014-10-27 04:40:02 +01:00
the ones defined in a `$db` array or simply a method that returns data for the template.
2019-05-23 12:09:59 +02:00
A Data Type is represented in SilverStripe by a [Field ](api:SilverStripe\ORM\FieldType\DBField ) subclass. The class is responsible for telling the ORM
2014-10-28 04:45:46 +01:00
about how to store its data in the database and how to format the information coming out of the database, i.e. on a template.
2014-10-27 04:40:02 +01:00
In the `Player` example, we have four database columns each with a different data type (Int, Varchar).
2018-06-25 00:39:53 +02:00
**app/code/Player.php**
2014-10-27 04:40:02 +01:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\DataObject;
class Player extends DataObject
{
private static $db = [
'PlayerNumber' => 'Int',
'FirstName' => 'Varchar(255)',
'LastName' => 'Text',
'Birthday' => 'Date'
];
}
2017-08-03 02:51:32 +02:00
```
2011-02-07 07:48:44 +01:00
2012-06-23 00:32:43 +02:00
## Available Types
2011-02-07 07:48:44 +01:00
2019-05-23 12:09:59 +02:00
* [Boolean ](api:SilverStripe\ORM\FieldType\DBBoolean ): A boolean field.
* [Currency ](api:SilverStripe\ORM\FieldType\DBCurrency ): A number with 2 decimal points of precision, designed to store currency values.
* [Date ](api:SilverStripe\ORM\FieldType\DBDate ): A date field
* [Decimal ](api:SilverStripe\ORM\FieldType\DBDecimal ): A decimal number.
* [Enum ](api:SilverStripe\ORM\FieldType\DBEnum ): An enumeration of a set of strings
* [HTMLText ](api:SilverStripe\ORM\FieldType\DBHTMLText ): A variable-length string of up to 2MB, designed to store HTML
* [HTMLVarchar ](api:SilverStripe\ORM\FieldType\DBHTMLVarchar ): A variable-length string of up to 255 characters, designed to store HTML
* [Int ](api:SilverStripe\ORM\FieldType\DBInt ): An integer field.
* [Percentage ](api:SilverStripe\ORM\FieldType\DBPercentage ): A decimal number between 0 and 1 that represents a percentage.
* [Datetime ](api:SilverStripe\ORM\FieldType\DBDatetime ): A date / time field
* [Text ](api:SilverStripe\ORM\FieldType\DBText ): A variable-length string of up to 2MB, designed to store raw text
* [Time ](api:SilverStripe\ORM\FieldType\DBTime ): A time field
* [Varchar ](api:SilverStripe\ORM\FieldType\DBVarchar ): A variable-length string of up to 255 characters, designed to store raw text.
See the [API documentation ](api:SilverStripe\ORM\FieldType\DBField ) for a full list of available Data Types. You can define your own [Field ](api:SilverStripe\ORM\FieldType\DBField ) instances if required as well.
2015-05-29 23:23:03 +02:00
## Default Values
### Default values for new objects
For complex default values for newly instantiated objects see [Dynamic Default Values ](how_tos/dynamic_default_fields ).
For simple values you can make use of the `$defaults` array. For example:
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\DataObject;
class Car extends DataObject
{
private static $db = [
'Wheels' => 'Int',
'Condition' => 'Enum(array("New","Fair","Junk"))'
];
private static $defaults = [
'Wheels' => 4,
'Condition' => 'New'
];
}
2017-08-03 02:51:32 +02:00
```
2015-05-29 23:23:03 +02:00
### Default values for new database columns
When adding a new `$db` field to a DataObject you can specify a default value
to be applied to all existing records when the column is added in the database
for the first time. This will also be applied to any newly created objects
going forward. You do this be passing an argument for the default value in your
2016-09-14 08:02:20 +02:00
`$db` items.
For integer values, the default is the first parameter in the field specification.
For string values, you will need to declare this default using the options array.
For enum values, it's the second parameter.
For example:
2015-05-29 23:23:03 +02:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\DataObject;
class Car extends DataObject
{
private static $db = [
'Wheels' => 'Int(4)',
'Condition' => 'Enum(array("New","Fair","Junk"), "New")',
2019-01-15 16:50:37 +01:00
'Make' => 'Varchar(["default" => "Honda"])',
2017-10-27 04:38:27 +02:00
);
}
2017-08-03 02:51:32 +02:00
```
2014-10-27 04:40:02 +01:00
## Formatting Output
The Data Type does more than setup the correct database schema. They can also define methods and formatting helpers for
output. You can manually create instances of a Data Type and pass it through to the template.
2017-07-03 03:22:12 +02:00
If this case, we'll create a new method for our `Player` that returns the full name. By wrapping this in a [DBVarchar ](api:SilverStripe\ORM\FieldType\DBVarchar )
2014-10-27 04:40:02 +01:00
object we can control the formatting and it allows us to call methods defined from `Varchar` as `LimitCharacters` .
2018-06-25 00:39:53 +02:00
**app/code/Player.php**
2017-10-27 04:38:27 +02:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\FieldType\DBField;
use SilverStripe\ORM\DataObject;
2017-08-05 00:45:24 +02:00
2017-10-27 04:38:27 +02:00
class Player extends DataObject
{
public function getName()
2017-08-07 05:11:17 +02:00
{
2017-10-27 04:38:27 +02:00
return DBField::create_field('Varchar', $this->FirstName . ' '. $this->LastName);
2017-08-07 05:11:17 +02:00
}
2017-10-27 04:38:27 +02:00
}
2017-08-03 02:51:32 +02:00
```
2014-10-27 04:40:02 +01:00
Then we can refer to a new `Name` column on our `Player` instances. In templates we don't need to use the `get` prefix.
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
$player = Player::get()->byId(1);
2014-10-27 04:40:02 +01:00
2017-10-27 04:38:27 +02:00
echo $player->Name;
// returns "Sam Minnée"
2014-10-27 04:40:02 +01:00
2017-10-27 04:38:27 +02:00
echo $player->getName();
// returns "Sam Minnée";
2014-10-27 04:40:02 +01:00
2017-10-27 04:38:27 +02:00
echo $player->getName()->LimitCharacters(2);
// returns "Sa.."
2017-08-03 02:51:32 +02:00
```
2014-10-27 04:40:02 +01:00
2015-05-29 23:23:03 +02:00
## Casting
2014-10-27 04:40:02 +01:00
Rather than manually returning objects from your custom functions. You can use the `$casting` property.
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\DataObject;
2014-10-27 04:40:02 +01:00
2017-10-27 04:38:27 +02:00
class Player extends DataObject
{
private static $casting = [
2017-08-07 05:11:17 +02:00
"Name" => 'Varchar',
2017-10-27 04:38:27 +02:00
];
2017-08-07 05:11:17 +02:00
2017-10-27 04:38:27 +02:00
public function getName()
{
return $this->FirstName . ' '. $this->LastName;
2017-08-07 05:11:17 +02:00
}
2017-10-27 04:38:27 +02:00
}
2017-08-03 02:51:32 +02:00
```
2014-10-27 04:40:02 +01:00
The properties on any SilverStripe object can be type casted automatically, by transforming its scalar value into an
2017-07-03 03:22:12 +02:00
instance of the [DBField ](api:SilverStripe\ORM\FieldType\DBField ) class, providing additional helpers. For example, a string can be cast as a [DBText ](api:SilverStripe\ORM\FieldType\DBText )
2014-10-27 04:40:02 +01:00
type, which has a `FirstSentence()` method to retrieve the first sentence in a longer piece of text.
On the most basic level, the class can be used as simple conversion class from one value to another, e.g. to round a
number.
2012-06-23 00:32:43 +02:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\FieldType\DBField;
DBField::create_field('Double', 1.23456)->Round(2); // results in 1.23
2017-08-03 02:51:32 +02:00
```
2012-06-23 00:32:43 +02:00
2017-07-03 03:22:12 +02:00
Of course that's much more verbose than the equivalent PHP call. The power of [DBField ](api:SilverStripe\ORM\FieldType\DBField ) comes with its more
2014-10-27 04:40:02 +01:00
sophisticated helpers, like showing the time difference to the current date:
2012-06-23 00:32:43 +02:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\FieldType\DBField;
DBField::create_field('Date', '1982-01-01')->TimeDiff(); // shows "30 years ago"
2017-08-03 02:51:32 +02:00
```
2012-06-23 00:32:43 +02:00
## Casting ViewableData
2017-07-03 03:22:12 +02:00
Most objects in SilverStripe extend from [ViewableData ](api:SilverStripe\View\ViewableData ), which means they know how to present themselves in a view
2014-10-27 04:40:02 +01:00
context. Through a `$casting` array, arbitrary properties and getters can be casted:
2012-06-23 00:32:43 +02:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\View\ViewableData;
class MyObject extends ViewableData
{
private static $casting = [
'MyDate' => 'Date'
];
2017-08-07 05:11:17 +02:00
2017-10-27 04:38:27 +02:00
public function getMyDate()
2017-08-07 05:11:17 +02:00
{
2017-10-27 04:38:27 +02:00
return '1982-01-01';
2017-08-07 05:11:17 +02:00
}
2017-10-27 04:38:27 +02:00
}
2017-08-07 05:11:17 +02:00
2017-10-27 04:38:27 +02:00
$obj = new MyObject;
$obj->getMyDate(); // returns string
$obj->MyDate; // returns string
$obj->obj('MyDate'); // returns object
$obj->obj('MyDate')->InPast(); // returns boolean
2017-08-03 02:51:32 +02:00
```
2012-06-23 00:32:43 +02:00
2014-10-27 04:40:02 +01:00
## Casting HTML Text
2017-07-03 03:22:12 +02:00
The database field types [DBHTMLVarchar ](api:SilverStripe\ORM\FieldType\DBHTMLVarchar )/[DBHTMLText](api:SilverStripe\ORM\FieldType\DBHTMLText) and [DBVarchar ](api:SilverStripe\ORM\FieldType\DBVarchar )/[DBText](api:SilverStripe\ORM\FieldType\DBText) are exactly the same in
2014-10-27 04:40:02 +01:00
the database. However, the template engine knows to escape fields without the `HTML` prefix automatically in templates,
to prevent them from rendering HTML interpreted by browsers. This escaping prevents attacks like CSRF or XSS (see
"[security](../security)"), which is important if these fields store user-provided data.
2012-06-23 00:32:43 +02:00
2016-06-03 10:51:02 +02:00
See the [Template casting ](/developer_guides/templates/casting ) section for controlling casting in your templates.
2012-06-23 00:32:43 +02:00
2014-10-27 04:40:02 +01:00
## Overloading
2012-06-23 00:32:43 +02:00
2017-07-03 03:22:12 +02:00
"Getters" and "Setters" are functions that help us save fields to our [DataObject ](api:SilverStripe\ORM\DataObject ) instances. By default, the
2014-10-27 04:40:02 +01:00
methods `getField()` and `setField()` are used to set column data. They save to the protected array, `$obj->record` .
We can overload the default behavior by making a function called "get`< fieldname > `" or "set`< fieldname > `".
2012-06-23 00:32:43 +02:00
2014-10-27 04:40:02 +01:00
The following example will use the result of `getStatus` instead of the 'Status' database column. We can refer to the
database column using `dbObject` .
2011-02-07 07:48:44 +01:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\ORM\DataObject;
2017-08-05 00:45:24 +02:00
2017-10-27 04:38:27 +02:00
class Player extends DataObject
{
private static $db = [
2017-08-07 05:11:17 +02:00
"Status" => "Enum(array('Active', 'Injured', 'Retired'))"
2017-10-27 04:38:27 +02:00
];
public function getStatus()
{
return (!$this->obj("Birthday")->InPast()) ? "Unborn" : $this->dbObject('Status')->Value();
}
}
2017-08-03 02:51:32 +02:00
```
2011-02-07 07:48:44 +01:00
2014-10-27 04:40:02 +01:00
## API Documentation
2011-02-07 07:48:44 +01:00
2017-07-03 03:22:12 +02:00
* [DataObject ](api:SilverStripe\ORM\DataObject )
* [DBField ](api:SilverStripe\ORM\FieldType\DBField )