MediaWiki  master
ExpiryDef.php
Go to the documentation of this file.
1 <?php
2 
4 
9 use Wikimedia\Timestamp\ConvertibleTimestamp;
10 
16 class ExpiryDef extends TypeDef {
17 
19  public const INFINITY_VALS = [ 'infinite', 'indefinite', 'infinity', 'never' ];
20 
27  public const PARAM_USE_MAX = 'param-use-max';
28 
32  public const PARAM_MAX = 'param-max';
33 
34  public function validate( $name, $value, array $settings, array $options ) {
35  $expiry = self::normalizeExpiry( $value );
36 
37  if ( $expiry === false ) {
38  $this->failure( 'badexpiry', $name, $value, $settings, $options );
39  }
40 
41  if ( $expiry < self::timestamp() ) {
42  $this->failure( 'badexpiry-past', $name, $value, $settings, $options );
43  }
44 
45  $max = $settings[self::PARAM_MAX] ?? null;
46 
47  if ( self::expiryExceedsMax( $expiry, $max ) ) {
48  $dontUseMax = empty( $settings[self::PARAM_USE_MAX] );
49  // Show warning that expiry exceeds the max, and that the max is being used instead.
50  $msg = DataMessageValue::new(
51  $dontUseMax
52  ? 'paramvalidator-badexpiry-duration'
53  : 'paramvalidator-badexpiry-duration-max',
54  [ $max ]
55  );
56  $this->failure( $msg, $name, $value, $settings, $options, $dontUseMax );
57 
58  return self::normalizeExpiry( $max );
59  }
60 
61  return $expiry;
62  }
63 
64  public function getHelpInfo( $name, array $settings, array $options ) {
65  $info = parent::getHelpInfo( $name, $settings, $options );
66 
67  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-expiry' )
68  ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 )
69  ->textListParams(
70  // Should be quoted or monospace for presentation purposes,
71  // but textListParams() doesn't do this.
72  array_map( function ( $val ) {
73  return "\"$val\"";
74  }, self::INFINITY_VALS )
75  );
76 
77  return $info;
78  }
79 
86  public static function normalizeExpiry( ?string $expiry ) {
87  if ( $expiry === null ) {
88  return null;
89  }
90  if ( in_array( $expiry, self::INFINITY_VALS, true ) ) {
91  return 'infinity';
92  }
93 
94  // ConvertibleTimestamp::time() used so we can fake the current time in ExpiryDefTest.
95  $unix = strtotime( $expiry, ConvertibleTimestamp::time() );
96  if ( $unix === false ) {
97  // Invalid expiry.
98  return false;
99  }
100 
101  return self::timestamp( $unix );
102  }
103 
109  protected static function timestamp( $unix = false ) {
110  // Don't pass 0, since ConvertibleTimestamp interprets that to mean the current timestamp.
111  // '00' does the right thing. Without this check, calling normalizeExpiry()
112  // with 1970-01-01T00:00:00Z incorrectly returns the current time.
113  return ConvertibleTimestamp::convert( TS_ISO_8601, $unix === 0 ? '00' : $unix );
114  }
115 
123  public static function expiryExceedsMax( ?string $expiry, ?string $max = null ): bool {
124  // Normalize the max and given expiries to TS_ISO_8601 format.
125  $expiry = self::normalizeExpiry( $expiry );
126  $max = self::normalizeExpiry( $max );
127 
128  if ( !$max || !$expiry || $expiry === 'infinity' ) {
129  // Either there is no max or given expiry was invalid.
130  return false;
131  }
132 
133  return $expiry > $max;
134  }
135 
136 }
Wikimedia\ParamValidator\TypeDef\ExpiryDef\getHelpInfo
getHelpInfo( $name, array $settings, array $options)
Describe parameter settings in human-readable format.
Definition: ExpiryDef.php:64
Wikimedia\ParamValidator\TypeDef\failure
failure( $failure, $name, $value, array $settings, array $options, $fatal=true)
Record a failure message.
Definition: TypeDef.php:43
Wikimedia\ParamValidator\TypeDef\ExpiryDef\expiryExceedsMax
static expiryExceedsMax(?string $expiry, ?string $max=null)
Given an expiry, test if the normalized value exceeds the given maximum.
Definition: ExpiryDef.php:123
Wikimedia\Message\MessageValue
Value object representing a message for i18n.
Definition: MessageValue.php:14
Wikimedia\ParamValidator\TypeDef
Base definition for ParamValidator types.
Definition: TypeDef.php:18
Wikimedia\ParamValidator\TypeDef\ExpiryDef
Type definition for expiry timestamps.
Definition: ExpiryDef.php:16
Wikimedia\ParamValidator\TypeDef\ExpiryDef\PARAM_MAX
const PARAM_MAX
(int|float) Maximum non-infinity duration.
Definition: ExpiryDef.php:32
Wikimedia\ParamValidator\TypeDef\ExpiryDef\validate
validate( $name, $value, array $settings, array $options)
Validate the value.
Definition: ExpiryDef.php:34
Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI
const PARAM_ISMULTI
(bool) Indicate that the parameter is multi-valued.
Definition: ParamValidator.php:112
Wikimedia\Message\DataMessageValue
Value object representing a message for i18n with alternative machine-readable data.
Definition: DataMessageValue.php:21
Wikimedia\Message\DataMessageValue\new
static new( $key, $params=[], $code=null, array $data=null)
Static constructor for easier chaining of ->params() methods.
Definition: DataMessageValue.php:51
Wikimedia\ParamValidator\TypeDef\ExpiryDef\PARAM_USE_MAX
const PARAM_USE_MAX
(bool) If truthy, the value given for the PARAM_MAX setting is used if the provided expiry exceeds it...
Definition: ExpiryDef.php:27
Wikimedia\ParamValidator\TypeDef\ExpiryDef\normalizeExpiry
static normalizeExpiry(?string $expiry)
Normalize a user-inputted expiry.
Definition: ExpiryDef.php:86
Wikimedia\ParamValidator\TypeDef
Definition: BooleanDef.php:3
Wikimedia\ParamValidator\TypeDef\ExpiryDef\timestamp
static timestamp( $unix=false)
Convert to or get the current time in TS_ISO_8601.
Definition: ExpiryDef.php:109
Wikimedia\Message\MessageValue\new
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
Definition: MessageValue.php:38
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