MediaWiki master
TimestampDef.php
Go to the documentation of this file.
1<?php
2
4
5use InvalidArgumentException;
11use Wikimedia\Timestamp\ConvertibleTimestamp;
12use Wikimedia\Timestamp\TimestampException;
13
32class TimestampDef extends TypeDef {
33
44 public const PARAM_TIMESTAMP_FORMAT = 'param-timestamp-format';
45
47 protected $defaultFormat;
48
51
60 public function __construct( Callbacks $callbacks, array $options = [] ) {
61 parent::__construct( $callbacks );
62
63 $this->defaultFormat = $options['defaultFormat'] ?? 'ConvertibleTimestamp';
64 $this->stringifyFormat = $options['stringifyFormat'] ?? TS_ISO_8601;
65
66 // Check values by trying to convert 0
67 if ( $this->defaultFormat !== 'ConvertibleTimestamp' && $this->defaultFormat !== 'DateTime' &&
68 ConvertibleTimestamp::convert( $this->defaultFormat, 0 ) === false
69 ) {
70 throw new InvalidArgumentException( 'Invalid value for $options[\'defaultFormat\']' );
71 }
72 if ( ConvertibleTimestamp::convert( $this->stringifyFormat, 0 ) === false ) {
73 throw new InvalidArgumentException( 'Invalid value for $options[\'stringifyFormat\']' );
74 }
75 }
76
77 public function validate( $name, $value, array $settings, array $options ) {
78 // Confusing synonyms for the current time accepted by ConvertibleTimestamp
79 if ( !$value ) {
80 $this->failure( 'unclearnowtimestamp', $name, $value, $settings, $options, false );
81 $value = 'now';
82 }
83
85
86 try {
87 $timestampObj = new ConvertibleTimestamp( $value === 'now' ? false : $value );
88
89 $timestamp = ( $format !== 'ConvertibleTimestamp' && $format !== 'DateTime' )
90 ? $timestampObj->getTimestamp( $format )
91 : null;
92 } catch ( TimestampException $ex ) {
93 // $this->failure() doesn't handle passing a previous exception
94 throw new ValidationException(
95 $this->failureMessage( 'badtimestamp' )->plaintextParams( $name, $value ),
96 $name, $value, $settings, $ex
97 );
98 }
99
100 switch ( $format ) {
101 case 'ConvertibleTimestamp':
102 return $timestampObj;
103
104 case 'DateTime':
105 // Eew, no getter.
106 return $timestampObj->timestamp;
107
108 default:
109 return $timestamp;
110 }
111 }
112
113 public function checkSettings( string $name, $settings, array $options, array $ret ): array {
114 $ret = parent::checkSettings( $name, $settings, $options, $ret );
115
116 $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [
117 self::PARAM_TIMESTAMP_FORMAT,
118 ] );
119
121 if ( $f !== 'ConvertibleTimestamp' && $f !== 'DateTime' &&
122 ConvertibleTimestamp::convert( $f, 0 ) === false
123 ) {
124 $ret['issues'][self::PARAM_TIMESTAMP_FORMAT] = 'Value for PARAM_TIMESTAMP_FORMAT is not valid';
125 }
126
127 return $ret;
128 }
129
130 public function stringifyValue( $name, $value, array $settings, array $options ) {
131 if ( !$value instanceof ConvertibleTimestamp ) {
132 $value = new ConvertibleTimestamp( $value );
133 }
134 return $value->getTimestamp( $this->stringifyFormat );
135 }
136
137 public function getHelpInfo( $name, array $settings, array $options ) {
138 $info = parent::getHelpInfo( $name, $settings, $options );
139
140 $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-timestamp' )
141 ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 );
142
143 return $info;
144 }
145
146}
Value object representing a message for i18n.
Service for formatting and validating API parameters.
const PARAM_ISMULTI
(bool) Indicate that the parameter is multi-valued.
const PARAM_TYPE
(string|array) Type of the parameter.
Type definition for timestamp types.
getHelpInfo( $name, array $settings, array $options)
Describe parameter settings in human-readable format.
validate( $name, $value, array $settings, array $options)
Validate the value.
__construct(Callbacks $callbacks, array $options=[])
stringifyValue( $name, $value, array $settings, array $options)
Convert a value to a string representation.
checkSettings(string $name, $settings, array $options, array $ret)
Validate a parameter settings array.
const PARAM_TIMESTAMP_FORMAT
(string|int) Timestamp format to return from validate()
Base definition for ParamValidator types.
Definition TypeDef.php:19
failureMessage( $code, array $data=null, $suffix=null)
Create a DataMessageValue representing a failure.
Definition TypeDef.php:84
failure( $failure, $name, $value, array $settings, array $options, $fatal=true)
Record a failure message.
Definition TypeDef.php:49
Interface defining callbacks needed by ParamValidator.
Definition Callbacks.php:21