-
Notifications
You must be signed in to change notification settings - Fork 3.4k
/
TimestampBehavior.php
227 lines (206 loc) · 7.24 KB
/
TimestampBehavior.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
<?php
declare(strict_types=1);
/**
* CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
* Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
*
* Licensed under The MIT License
* For full copyright and license information, please see the LICENSE.txt
* Redistributions of files must retain the above copyright notice.
*
* @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
* @link https://cakephp.org CakePHP(tm) Project
* @since 3.0.0
* @license https://opensource.org/licenses/mit-license.php MIT License
*/
namespace Cake\ORM\Behavior;
use Cake\Database\Type\DateTimeType;
use Cake\Database\TypeFactory;
use Cake\Datasource\EntityInterface;
use Cake\Event\EventInterface;
use Cake\I18n\DateTime;
use Cake\ORM\Behavior;
use DateTimeInterface;
use UnexpectedValueException;
/**
* Class TimestampBehavior
*/
class TimestampBehavior extends Behavior
{
/**
* Default config
*
* These are merged with user-provided config when the behavior is used.
*
* events - an event-name keyed array of which fields to update, and when, for a given event
* possible values for when a field will be updated are "always", "new" or "existing", to set
* the field value always, only when a new record or only when an existing record.
*
* refreshTimestamp - if true (the default) the timestamp used will be the current time when
* the code is executed, to set to an explicit date time value - set refreshTimetamp to false
* and call setTimestamp() on the behavior class before use.
*
* @var array<string, mixed>
*/
protected array $_defaultConfig = [
'implementedFinders' => [],
'implementedMethods' => [
'timestamp' => 'timestamp',
'touch' => 'touch',
],
'events' => [
'Model.beforeSave' => [
'created' => 'new',
'modified' => 'always',
],
],
'refreshTimestamp' => true,
];
/**
* Current timestamp
*
* @var \Cake\I18n\DateTime|null
*/
protected ?DateTime $_ts = null;
/**
* Initialize hook
*
* If events are specified - do *not* merge them with existing events,
* overwrite the events to listen on
*
* @param array<string, mixed> $config The config for this behavior.
* @return void
*/
public function initialize(array $config): void
{
if (isset($config['events'])) {
$this->setConfig('events', $config['events'], false);
}
}
/**
* There is only one event handler, it can be configured to be called for any event
*
* @param \Cake\Event\EventInterface<\Cake\ORM\Table> $event Event instance.
* @param \Cake\Datasource\EntityInterface $entity Entity instance.
* @throws \UnexpectedValueException if a field's when value is misdefined
* @return void
* @throws \UnexpectedValueException When the value for an event is not 'always', 'new' or 'existing'
*/
public function handleEvent(EventInterface $event, EntityInterface $entity): void
{
$eventName = $event->getName();
$events = $this->_config['events'];
$new = $entity->isNew() !== false;
$refresh = $this->_config['refreshTimestamp'];
foreach ($events[$eventName] as $field => $when) {
if (!in_array($when, ['always', 'new', 'existing'], true)) {
throw new UnexpectedValueException(sprintf(
'When should be one of "always", "new" or "existing". The passed value `%s` is invalid.',
$when
));
}
if (
$when === 'always' ||
(
$when === 'new' &&
$new
) ||
(
$when === 'existing' &&
!$new
)
) {
$this->_updateField($entity, $field, $refresh);
}
}
}
/**
* implementedEvents
*
* The implemented events of this behavior depend on configuration
*
* @return array<string, mixed>
*/
public function implementedEvents(): array
{
/** @var array<string, mixed> */
return array_fill_keys(array_keys($this->_config['events']), 'handleEvent');
}
/**
* Get or set the timestamp to be used
*
* Set the timestamp to the given DateTime object, or if not passed a new DateTime object
* If an explicit date time is passed, the config option `refreshTimestamp` is
* automatically set to false.
*
* @param \DateTimeInterface|null $ts Timestamp
* @param bool $refreshTimestamp If true timestamp is refreshed.
* @return \Cake\I18n\DateTime
*/
public function timestamp(?DateTimeInterface $ts = null, bool $refreshTimestamp = false): DateTime
{
if ($ts) {
if ($this->_config['refreshTimestamp']) {
$this->_config['refreshTimestamp'] = false;
}
$this->_ts = new DateTime($ts);
} elseif ($this->_ts === null || $refreshTimestamp) {
$this->_ts = new DateTime();
}
return $this->_ts;
}
/**
* Touch an entity
*
* Bumps timestamp fields for an entity. For any fields configured to be updated
* "always" or "existing", update the timestamp value. This method will overwrite
* any pre-existing value.
*
* @param \Cake\Datasource\EntityInterface $entity Entity instance.
* @param string $eventName Event name.
* @return bool true if a field is updated, false if no action performed
*/
public function touch(EntityInterface $entity, string $eventName = 'Model.beforeSave'): bool
{
$events = $this->_config['events'];
if (empty($events[$eventName])) {
return false;
}
$return = false;
$refresh = $this->_config['refreshTimestamp'];
foreach ($events[$eventName] as $field => $when) {
if (in_array($when, ['always', 'existing'], true)) {
$return = true;
$entity->setDirty($field, false);
$this->_updateField($entity, $field, $refresh);
}
}
return $return;
}
/**
* Update a field, if it hasn't been updated already
*
* @param \Cake\Datasource\EntityInterface $entity Entity instance.
* @param string $field Field name
* @param bool $refreshTimestamp Whether to refresh timestamp.
* @return void
*/
protected function _updateField(EntityInterface $entity, string $field, bool $refreshTimestamp): void
{
if ($entity->isDirty($field)) {
return;
}
$ts = $this->timestamp(null, $refreshTimestamp);
$columnType = $this->table()->getSchema()->getColumnType($field);
if (!$columnType) {
return;
}
$type = TypeFactory::build($columnType);
assert(
$type instanceof DateTimeType,
sprintf('TimestampBehavior only supports columns of type `%s`.', DateTimeType::class)
);
$class = $type->getDateTimeClassName();
$entity->set($field, new $class($ts));
}
}