3 namespace Wikimedia\ParamValidator\TypeDef
;
5 use Wikimedia\ParamValidator\Callbacks
;
6 use Wikimedia\ParamValidator\TypeDef
;
7 use Wikimedia\ParamValidator\ValidationException
;
8 use Wikimedia\Timestamp\ConvertibleTimestamp
;
9 use Wikimedia\Timestamp\TimestampException
;
12 * Type definition for timestamp types
14 * This uses the wikimedia/timestamp library for parsing and formatting the
17 * The result from validate() is a ConvertibleTimestamp by default, but this
18 * may be changed by both a constructor option and a PARAM constant.
20 * ValidationException codes:
21 * - 'badtimestamp': The timestamp is not valid. No data, but the
22 * TimestampException is available via Exception::getPrevious().
23 * - 'unclearnowtimestamp': Non-fatal. The value is the empty string or "0".
24 * Use 'now' instead if you really want the current timestamp. No data.
28 class TimestampDef
extends TypeDef
{
31 * (string|int) Timestamp format to return from validate()
34 * - 'ConvertibleTimestamp': A ConvertibleTimestamp object.
35 * - 'DateTime': A PHP DateTime object
36 * - One of ConvertibleTimestamp's TS_* constants.
38 * This does not affect the format returned by stringifyValue().
40 const PARAM_TIMESTAMP_FORMAT
= 'param-timestamp-format';
42 /** @var string|int */
43 protected $defaultFormat;
46 protected $stringifyFormat;
49 * @param Callbacks $callbacks
50 * @param array $options Options:
51 * - defaultFormat: (string|int) Default for PARAM_TIMESTAMP_FORMAT.
52 * Default if not specified is 'ConvertibleTimestamp'.
53 * - stringifyFormat: (int) Format to use for stringifyValue().
54 * Default is TS_ISO_8601.
56 public function __construct( Callbacks
$callbacks, array $options = [] ) {
57 parent
::__construct( $callbacks );
59 $this->defaultFormat
= $options['defaultFormat'] ??
'ConvertibleTimestamp';
60 $this->stringifyFormat
= $options['stringifyFormat'] ?? TS_ISO_8601
;
63 public function validate( $name, $value, array $settings, array $options ) {
64 // Confusing synonyms for the current time accepted by ConvertibleTimestamp
66 $this->callbacks
->recordCondition(
67 new ValidationException( $name, $value, $settings, 'unclearnowtimestamp', [] ),
74 $timestamp = new ConvertibleTimestamp( $value === 'now' ?
false : $value );
75 } catch ( TimestampException
$ex ) {
76 throw new ValidationException( $name, $value, $settings, 'badtimestamp', [], $ex );
79 $format = $settings[self
::PARAM_TIMESTAMP_FORMAT
] ??
$this->defaultFormat
;
81 case 'ConvertibleTimestamp':
86 return $timestamp->timestamp
;
89 return $timestamp->getTimestamp( $format );
93 public function stringifyValue( $name, $value, array $settings, array $options ) {
94 if ( !$value instanceof ConvertibleTimestamp
) {
95 $value = new ConvertibleTimestamp( $value );
97 return $value->getTimestamp( $this->stringifyFormat
);