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  try {
85  $timestamp = new ConvertibleTimestamp( $value === 'now' ? false : $value );
86  } catch ( TimestampException $ex ) {
87  // $this->failure() doesn't handle passing a previous exception
88  throw new ValidationException(
89  $this->failureMessage( 'badtimestamp' )->plaintextParams( $name, $value ),
90  $name, $value, $settings, $ex
91  );
92  }
93 
94  $format = $settings[self::PARAM_TIMESTAMP_FORMAT] ?? $this->defaultFormat;
95  switch ( $format ) {
96  case 'ConvertibleTimestamp':
97  return $timestamp;
98 
99  case 'DateTime':
100  // Eew, no getter.
101  return $timestamp->timestamp;
102 
103  default:
104  return $timestamp->getTimestamp( $format );
105  }
106  }
107 
108  public function checkSettings( string $name, $settings, array $options, array $ret ) : array {
109  $ret = parent::checkSettings( $name, $settings, $options, $ret );
110 
111  $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [
112  self::PARAM_TIMESTAMP_FORMAT,
113  ] );
114 
116  if ( $f !== 'ConvertibleTimestamp' && $f !== 'DateTime' &&
117  ConvertibleTimestamp::convert( $f, 0 ) === false
118  ) {
119  $ret['issues'][self::PARAM_TIMESTAMP_FORMAT] = 'Value for PARAM_TIMESTAMP_FORMAT is not valid';
120  }
121 
122  return $ret;
123  }
124 
125  public function stringifyValue( $name, $value, array $settings, array $options ) {
126  if ( !$value instanceof ConvertibleTimestamp ) {
127  $value = new ConvertibleTimestamp( $value );
128  }
129  return $value->getTimestamp( $this->stringifyFormat );
130  }
131 
132  public function getHelpInfo( $name, array $settings, array $options ) {
133  $info = parent::getHelpInfo( $name, $settings, $options );
134 
135  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-timestamp' )
136  ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 );
137 
138  return $info;
139  }
140 
141 }
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:125
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:132
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:108