Versions
Look up a class, method, property or event

CTimestampBehavior

Package zii.behaviors
Inheritance class CTimestampBehavior » CActiveRecordBehavior » CModelBehavior » CBehavior » CComponent
Implements IBehavior
Since 1.1
Source Code framework/zii/behaviors/CTimestampBehavior.php
CTimestampBehavior will automatically fill date and time related attributes.

CTimestampBehavior will automatically fill date and time related attributes when the active record is created and/or updated. You may specify an active record model to use this behavior like so:
public function behaviors(){
	return array(
		'CTimestampBehavior' => array(
			'class' => 'zii.behaviors.CTimestampBehavior',
			'createAttribute' => 'create_time_attribute',
			'updateAttribute' => 'update_time_attribute',
		)
	);
}
The createAttribute and updateAttribute options actually default to 'create_time' and 'update_time' respectively, so it is not required that you configure them. If you do not wish CTimestampBehavior to set a timestamp for record update or creation, set the corresponding attribute option to null.

By default, the update attribute is only set on record update. If you also wish it to be set on record creation, set the setUpdateOnCreate option to true.

Although CTimestampBehavior attempts to figure out on it's own what value to inject into the timestamp attribute, you may specify a custom value to use instead via timestampExpression

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
createAttribute mixed The name of the attribute to store the creation time. CTimestampBehavior
enabled boolean whether this behavior is enabled CBehavior
owner CComponent the owner component that this behavior is attached to. CBehavior
setUpdateOnCreate bool Whether to set the update attribute to the creation timestamp upon creation. CTimestampBehavior
timestampExpression mixed The expression that will be used for generating the timestamp. CTimestampBehavior
updateAttribute mixed The name of the attribute to store the modification time. CTimestampBehavior

Protected Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
map array Maps column types to database method CTimestampBehavior

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attach() Attaches the behavior object to the component. CBehavior
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
beforeSave() Responds to CModel::onBeforeSave event. CTimestampBehavior
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
detach() Detaches the behavior object from the component. CBehavior
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
events() Declares events and the corresponding event handler methods. CActiveRecordBehavior
getEnabled() Returns whether this behavior is enabled CBehavior
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getOwner() Returns the owner component that this behavior is attached to. CBehavior
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
raiseEvent() Raises an event. CComponent
setEnabled() Sets whether this behavior is enabled CBehavior

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
afterConstruct() Responds to CModel::onAfterConstruct event. CModelBehavior
afterDelete() Responds to CActiveRecord::onAfterDelete event. CActiveRecordBehavior
afterFind() Responds to CActiveRecord::onAfterFind event. CActiveRecordBehavior
afterSave() Responds to CActiveRecord::onAfterSave event. CActiveRecordBehavior
afterValidate() Responds to CModel::onAfterValidate event. CModelBehavior
beforeCount() Responds to CActiveRecord::onBeforeCount event. CActiveRecordBehavior
beforeDelete() Responds to CActiveRecord::onBeforeDelete event. CActiveRecordBehavior
beforeFind() Responds to CActiveRecord::onBeforeFind event. CActiveRecordBehavior
beforeValidate() Responds to CModel::onBeforeValidate event. CModelBehavior
getTimestampByAttribute() Gets the appropriate timestamp depending on the column type $attribute is CTimestampBehavior
getTimestampByColumnType() Returns the appropriate timestamp depending on $columnType CTimestampBehavior

Property Details

createAttribute property
public mixed $createAttribute;

The name of the attribute to store the creation time. Set to null to not use a timestamp for the creation attribute. Defaults to 'create_time'

map property
protected static array $map;

Maps column types to database method

setUpdateOnCreate property
public bool $setUpdateOnCreate;

Whether to set the update attribute to the creation timestamp upon creation. Otherwise it will be left alone. Defaults to false.

timestampExpression property
public mixed $timestampExpression;

The expression that will be used for generating the timestamp. This can be either a string representing a PHP expression (e.g. 'time()'), or a CDbExpression object representing a DB expression (e.g. new CDbExpression('NOW()')). Defaults to null, meaning that we will attempt to figure out the appropriate timestamp automatically. If we fail at finding the appropriate timestamp, then it will fall back to using the current UNIX timestamp.

A PHP expression can be any PHP code that has a value. To learn more about what an expression is, please refer to the php manual.

updateAttribute property
public mixed $updateAttribute;

The name of the attribute to store the modification time. Set to null to not use a timestamp for the update attribute. Defaults to 'update_time'

Method Details

beforeSave() method
public void beforeSave(CModelEvent $event)
$event CModelEvent event parameter
Source Code: framework/zii/behaviors/CTimestampBehavior.php#89 (show)
public function beforeSave($event) {
    if (
$this->getOwner()->getIsNewRecord() && ($this->createAttribute !== null)) {
        
$this->getOwner()->{$this->createAttribute} = $this->getTimestampByAttribute($this->createAttribute);
    }
    if ((!
$this->getOwner()->getIsNewRecord() || $this->setUpdateOnCreate) && ($this->updateAttribute !== null)) {
        
$this->getOwner()->{$this->updateAttribute} = $this->getTimestampByAttribute($this->updateAttribute);
    }
}

Responds to CModel::onBeforeSave event. Sets the values of the creation or modified attributes as configured

getTimestampByAttribute() method
protected mixed getTimestampByAttribute(string $attribute)
$attribute string $attribute
{return} mixed timestamp (eg unix timestamp or a mysql function)
Source Code: framework/zii/behaviors/CTimestampBehavior.php#104 (show)
protected function getTimestampByAttribute($attribute) {
    if (
$this->timestampExpression instanceof CDbExpression)
        return 
$this->timestampExpression;
    elseif (
$this->timestampExpression !== null)
        return @eval(
'return '.$this->timestampExpression.';');

    
$columnType $this->getOwner()->getTableSchema()->getColumn($attribute)->dbType;
    return 
$this->getTimestampByColumnType($columnType);
}

Gets the appropriate timestamp depending on the column type $attribute is

getTimestampByColumnType() method
protected mixed getTimestampByColumnType(string $columnType)
$columnType string $columnType
{return} mixed timestamp (eg unix timestamp or a mysql function)
Source Code: framework/zii/behaviors/CTimestampBehavior.php#120 (show)
protected function getTimestampByColumnType($columnType) {
    return isset(
self::$map[$columnType]) ? new CDbExpression(self::$map[$columnType]) : time();
}

Returns the appropriate timestamp depending on $columnType

Total 2 comments

#17893 report it
Leffe at 2014/08/07 08:49am
TimeZones

Note that this behaviour may give the local time zone of your server. If you wish to get UTC, you better tell it to use 'time()' or new CDbExpression('UTC_TIMESTAMP()') to ensure it doesn't pick the local time on the server.

'CTimestampBehavior' => array(
    'class' => 'zii.behaviors.CTimestampBehavior',
    'timestampExpression' => new CDbExpression('UTC_TIMESTAMP()'), // Ensure we get UTC time
),

Edit: Reworded as I see now that the docs actually do not make any claims on what expression is used as default. However, my experience is that I got local server times that you get by using NOW() instead of UTC time.

#11381 report it
Milan Zivkovic at 2013/01/10 06:46am
Maybe this will help someone

Since onBeforeSave event will be fired only if active model will pass validation, its important that you not add 'create_time'/'update_time' attributes to required list in your model rules. If You will add it to required list, since you not fill this attributes, because this behavior need to do that for you, model will fail validation and onBeforeSave will not be fired, so attributes will not be set. You can add any other rules for this field, just not add it to required list, it will be anyway filled for sure.

Leave a comment

Please to leave your comment.