MediaWiki  master
TimestampDef.php
Go to the documentation of this file.
1 <?php
2 
4 
5 use InvalidArgumentException;
11 use Wikimedia\Timestamp\ConvertibleTimestamp;
12 use Wikimedia\Timestamp\TimestampException;
13 
32 class TimestampDef extends TypeDef {
33 
44  public const PARAM_TIMESTAMP_FORMAT = 'param-timestamp-format';
45 
47  protected $defaultFormat;
48 
50  protected $stringifyFormat;
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 
84  $format = $settings[self::PARAM_TIMESTAMP_FORMAT] ?? $this->defaultFormat;
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 }
Wikimedia\ParamValidator\TypeDef\TimestampDef\PARAM_TIMESTAMP_FORMAT
const PARAM_TIMESTAMP_FORMAT
(string|int) Timestamp format to return from validate()
Definition: TimestampDef.php:44
Wikimedia\ParamValidator\TypeDef\TimestampDef\$defaultFormat
string int $defaultFormat
Definition: TimestampDef.php:47
Wikimedia\ParamValidator\ValidationException
Error reporting for ParamValidator.
Definition: ValidationException.php:16
Wikimedia\ParamValidator\TypeDef\failureMessage
failureMessage( $code, array $data=null, $suffix=null)
Create a DataMessageValue representing a failure.
Definition: TypeDef.php:84
Wikimedia\ParamValidator\Callbacks
Interface defining callbacks needed by ParamValidator.
Definition: Callbacks.php:21
Wikimedia\ParamValidator\TypeDef\failure
failure( $failure, $name, $value, array $settings, array $options, $fatal=true)
Record a failure message.
Definition: TypeDef.php:49
Wikimedia\ParamValidator\TypeDef\TimestampDef\__construct
__construct(Callbacks $callbacks, array $options=[])
Definition: TimestampDef.php:60
Wikimedia\Message\MessageValue
Value object representing a message for i18n.
Definition: MessageValue.php:16
Wikimedia\ParamValidator\TypeDef
Base definition for ParamValidator types.
Definition: TypeDef.php:19
Wikimedia\ParamValidator\TypeDef\TimestampDef\stringifyValue
stringifyValue( $name, $value, array $settings, array $options)
Convert a value to a string representation.
Definition: TimestampDef.php:130
Wikimedia\ParamValidator\TypeDef\TimestampDef\$stringifyFormat
int $stringifyFormat
Definition: TimestampDef.php:50
Wikimedia\ParamValidator\TypeDef\TimestampDef\getHelpInfo
getHelpInfo( $name, array $settings, array $options)
Describe parameter settings in human-readable format.
Definition: TimestampDef.php:137
Wikimedia\ParamValidator\TypeDef\TimestampDef
Type definition for timestamp types.
Definition: TimestampDef.php:32
Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI
const PARAM_ISMULTI
(bool) Indicate that the parameter is multi-valued.
Definition: ParamValidator.php:112
Wikimedia\ParamValidator\TypeDef\TimestampDef\validate
validate( $name, $value, array $settings, array $options)
Validate the value.
Definition: TimestampDef.php:77
Wikimedia\ParamValidator\TypeDef
Definition: BooleanDef.php:3
Wikimedia\Message\MessageValue\new
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
Definition: MessageValue.php:42
Wikimedia\ParamValidator\ParamValidator\PARAM_TYPE
const PARAM_TYPE
(string|array) Type of the parameter.
Definition: ParamValidator.php:76
Wikimedia\ParamValidator\ParamValidator
Service for formatting and validating API parameters.
Definition: ParamValidator.php:42
Wikimedia\ParamValidator\TypeDef\$callbacks
Callbacks $callbacks
Definition: TypeDef.php:22
Wikimedia\ParamValidator\TypeDef\TimestampDef\checkSettings
checkSettings(string $name, $settings, array $options, array $ret)
Validate a parameter settings array.
Definition: TimestampDef.php:113