MediaWiki  master
TitleDef.php
Go to the documentation of this file.
1 <?php
2 
4 
11 
22 class TitleDef extends TypeDef {
23 
29  public const PARAM_MUST_EXIST = 'param-must-exist';
30 
41  public const PARAM_RETURN_OBJECT = 'param-return-object';
42 
44  private $titleFactory;
45 
50  public function __construct( Callbacks $callbacks, TitleFactory $titleFactory ) {
51  parent::__construct( $callbacks );
52  $this->titleFactory = $titleFactory;
53  }
54 
59  public function validate( $name, $value, array $settings, array $options ) {
60  $mustExist = !empty( $settings[self::PARAM_MUST_EXIST] );
61  $returnObject = !empty( $settings[self::PARAM_RETURN_OBJECT] );
62 
63  $title = $this->titleFactory->newFromText( $value );
64 
65  if ( !$title ) {
66  // Message used: paramvalidator-badtitle
67  $this->failure( 'badtitle', $name, $value, $settings, $options );
68  } elseif ( $mustExist && !$title->exists() ) {
69  // Message used: paramvalidator-missingtitle
70  $this->failure( 'missingtitle', $name, $value, $settings, $options );
71  }
72 
73  if ( $returnObject ) {
74  return $title->getTitleValue();
75  } else {
76  return $title->getPrefixedText();
77  }
78  }
79 
81  public function stringifyValue( $name, $value, array $settings, array $options ) {
82  if ( $value instanceof LinkTarget ) {
83  return $this->titleFactory->newFromLinkTarget( $value )->getPrefixedText();
84  }
85  return parent::stringifyValue( $name, $value, $settings, $options );
86  }
87 
89  public function checkSettings( string $name, $settings, array $options, array $ret ): array {
90  $ret = parent::checkSettings( $name, $settings, $options, $ret );
91 
92  $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [
93  self::PARAM_MUST_EXIST, self::PARAM_RETURN_OBJECT,
94  ] );
95 
96  if ( !is_bool( $settings[self::PARAM_MUST_EXIST] ?? false ) ) {
97  $ret['issues'][self::PARAM_MUST_EXIST] = 'PARAM_MUST_EXIST must be boolean, got '
98  . gettype( $settings[self::PARAM_MUST_EXIST] );
99  }
100 
101  if ( !is_bool( $settings[self::PARAM_RETURN_OBJECT] ?? false ) ) {
102  $ret['issues'][self::PARAM_RETURN_OBJECT] = 'PARAM_RETURN_OBJECT must be boolean, got '
103  . gettype( $settings[self::PARAM_RETURN_OBJECT] );
104  }
105 
106  if ( !empty( $settings[ParamValidator::PARAM_ISMULTI] ) &&
107  !empty( $settings[self::PARAM_RETURN_OBJECT] ) &&
108  (
109  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT1] ?? 100 ) > 10 ||
110  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT2] ?? 100 ) > 10
111  )
112  ) {
113  $ret['issues'][] = 'Multi-valued title-type parameters with PARAM_RETURN_OBJECT '
114  . 'should set low values (<= 10) for PARAM_ISMULTI_LIMIT1 and PARAM_ISMULTI_LIMIT2.'
115  . ' (Note that "<= 10" is arbitrary. If something hits this, we can investigate a real limit '
116  . 'once we have a real use case to look at.)';
117  }
118 
119  return $ret;
120  }
121 
123  public function getParamInfo( $name, array $settings, array $options ) {
124  $info = parent::getParamInfo( $name, $settings, $options );
125 
126  $info['mustExist'] = !empty( $settings[self::PARAM_MUST_EXIST] );
127 
128  return $info;
129  }
130 
132  public function getHelpInfo( $name, array $settings, array $options ) {
133  $info = parent::getParamInfo( $name, $settings, $options );
134 
135  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-title' );
136 
137  $mustExist = !empty( $settings[self::PARAM_MUST_EXIST] );
138  $info[self::PARAM_MUST_EXIST] = $mustExist
139  ? MessageValue::new( 'paramvalidator-help-type-title-must-exist' )
140  : MessageValue::new( 'paramvalidator-help-type-title-no-must-exist' );
141 
142  return $info;
143  }
144 
145 }
getParamInfo( $name, array $settings, array $options)
Describe parameter settings in a machine-readable format.Keys should be short strings using lowercase...
Definition: TitleDef.php:123
stringifyValue( $name, $value, array $settings, array $options)
Convert a value to a string representation.This is intended as the inverse of getValue() and validate...
Definition: TitleDef.php:81
checkSettings(string $name, $settings, array $options, array $ret)
Validate a parameter settings array.This is intended for validation of parameter settings during unit...
Definition: TitleDef.php:89
validate( $name, $value, array $settings, array $options)
Validate the value.When ParamValidator is processing a multi-valued parameter, this will be called on...
Definition: TitleDef.php:59
const PARAM_RETURN_OBJECT
(bool) Whether to return a LinkTarget.
Definition: TitleDef.php:41
getHelpInfo( $name, array $settings, array $options)
Describe parameter settings in human-readable format.Keys in the returned array should generally corr...
Definition: TitleDef.php:132
const PARAM_MUST_EXIST
(bool) Whether the page with the given title needs to exist.
Definition: TitleDef.php:29
__construct(Callbacks $callbacks, TitleFactory $titleFactory)
Definition: TitleDef.php:50
Creates Title objects.
Value object representing a message for i18n.
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
Service for formatting and validating API parameters.
const PARAM_ISMULTI
(bool) Indicate that the parameter is multi-valued.
const PARAM_ISMULTI_LIMIT2
(int) Maximum number of multi-valued parameter values allowed for users allowed high limits.
const PARAM_ISMULTI_LIMIT1
(int) Maximum number of multi-valued parameter values allowed
const PARAM_TYPE
(string|array) Type of the parameter.
Base definition for ParamValidator types.
Definition: TypeDef.php:19
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