MediaWiki  master
ApiManageTags.php
Go to the documentation of this file.
1 <?php
2 
23 
28 class ApiManageTags extends ApiBase {
29 
30  public function execute() {
31  $params = $this->extractRequestParams();
32  $authority = $this->getAuthority();
33 
34  // make sure the user is allowed
35  if ( $params['operation'] !== 'delete'
36  && !$authority->isAllowed( 'managechangetags' )
37  ) {
38  $this->dieWithError( 'tags-manage-no-permission', 'permissiondenied' );
39  } elseif ( !$authority->isAllowed( 'deletechangetags' ) ) {
40  $this->dieWithError( 'tags-delete-no-permission', 'permissiondenied' );
41  }
42 
43  // Check if user can add the log entry tags which were requested
44  if ( $params['tags'] ) {
45  $ableToTag = ChangeTags::canAddTagsAccompanyingChange( $params['tags'], $authority );
46  if ( !$ableToTag->isOK() ) {
47  $this->dieStatus( $ableToTag );
48  }
49  }
50 
51  $result = $this->getResult();
52  $tag = $params['tag'];
53  $reason = $params['reason'];
54  $ignoreWarnings = $params['ignorewarnings'];
55  $tags = $params['tags'] ?: [];
56  switch ( $params['operation'] ) {
57  case 'create':
58  $status = ChangeTags::createTagWithChecks( $tag, $reason, $authority, $ignoreWarnings, $tags );
59  break;
60  case 'delete':
61  $status = ChangeTags::deleteTagWithChecks( $tag, $reason, $authority, $ignoreWarnings, $tags );
62  break;
63  case 'activate':
64  $status = ChangeTags::activateTagWithChecks( $tag, $reason, $authority, $ignoreWarnings, $tags );
65  break;
66  case 'deactivate':
67  $status = ChangeTags::deactivateTagWithChecks( $tag, $reason, $authority, $ignoreWarnings, $tags );
68  break;
69  default:
70  // unreachable
71  throw new UnexpectedValueException( 'invalid operation' );
72  }
73  if ( !$status->isOK() ) {
74  $this->dieStatus( $status );
75  }
76 
77  $ret = [
78  'operation' => $params['operation'],
79  'tag' => $params['tag'],
80  ];
81  if ( !$status->isGood() ) {
82  $ret['warnings'] = $this->getErrorFormatter()->arrayFromStatus( $status, 'warning' );
83  }
84  $ret['success'] = $status->value !== null;
85  if ( $ret['success'] ) {
86  $ret['logid'] = $status->value;
87  }
88 
89  $result->addValue( null, $this->getModuleName(), $ret );
90  }
91 
92  public function mustBePosted() {
93  return true;
94  }
95 
96  public function isWriteMode() {
97  return true;
98  }
99 
100  public function getAllowedParams() {
101  return [
102  'operation' => [
103  ParamValidator::PARAM_TYPE => [ 'create', 'delete', 'activate', 'deactivate' ],
104  ParamValidator::PARAM_REQUIRED => true,
105  ],
106  'tag' => [
107  ParamValidator::PARAM_TYPE => 'string',
108  ParamValidator::PARAM_REQUIRED => true,
109  ],
110  'reason' => [
111  ParamValidator::PARAM_TYPE => 'string',
112  ParamValidator::PARAM_DEFAULT => '',
113  ],
114  'ignorewarnings' => [
115  ParamValidator::PARAM_TYPE => 'boolean',
116  ParamValidator::PARAM_DEFAULT => false,
117  ],
118  'tags' => [
119  ParamValidator::PARAM_TYPE => 'tags',
120  ParamValidator::PARAM_ISMULTI => true,
121  ],
122  ];
123  }
124 
125  public function needsToken() {
126  return 'csrf';
127  }
128 
129  protected function getExamplesMessages() {
130  return [
131  'action=managetags&operation=create&tag=spam&reason=For+use+in+edit+patrolling&token=123ABC'
132  => 'apihelp-managetags-example-create',
133  'action=managetags&operation=delete&tag=vandlaism&reason=Misspelt&token=123ABC'
134  => 'apihelp-managetags-example-delete',
135  'action=managetags&operation=activate&tag=spam&reason=For+use+in+edit+patrolling&token=123ABC'
136  => 'apihelp-managetags-example-activate',
137  'action=managetags&operation=deactivate&tag=spam&reason=No+longer+required&token=123ABC'
138  => 'apihelp-managetags-example-deactivate',
139  ];
140  }
141 
142  public function getHelpUrls() {
143  return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Tag_management';
144  }
145 }
This abstract class implements many basic API functions, and is the base of all API classes.
Definition: ApiBase.php:56
dieWithError( $msg, $code=null, $data=null, $httpCode=0)
Abort execution with an error.
Definition: ApiBase.php:1453
getErrorFormatter()
Definition: ApiBase.php:640
getResult()
Get the result object.
Definition: ApiBase.php:629
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition: ApiBase.php:765
getModuleName()
Get the name of the module being executed by this instance.
Definition: ApiBase.php:498
dieStatus(StatusValue $status)
Throw an ApiUsageException based on the Status object.
Definition: ApiBase.php:1516
needsToken()
Returns the token type this module requires in order to execute.
isWriteMode()
Indicates whether this module requires write mode.
getExamplesMessages()
Returns usage examples for this module.
mustBePosted()
Indicates whether this module must be called with a POST request.
getAllowedParams()
Returns an array of allowed parameters (parameter name) => (default value) or (parameter name) => (ar...
execute()
Evaluates the parameters, performs the requested query, and sets up the result.
getHelpUrls()
Return links to more detailed help pages about the module.
static deactivateTagWithChecks(string $tag, string $reason, Authority $performer, bool $ignoreWarnings=false, array $logEntryTags=[])
Deactivates a tag, checking whether it is allowed first, and adding a log entry afterwards.
static deleteTagWithChecks(string $tag, string $reason, Authority $performer, bool $ignoreWarnings=false, array $logEntryTags=[])
Deletes a tag, checking whether it is allowed first, and adding a log entry afterwards.
static createTagWithChecks(string $tag, string $reason, Authority $performer, bool $ignoreWarnings=false, array $logEntryTags=[])
Creates a tag by adding it to change_tag_def table.
static canAddTagsAccompanyingChange(array $tags, Authority $performer=null, $checkBlock=true)
Is it OK to allow the user to apply all the specified tags at the same time as they edit/make the cha...
Definition: ChangeTags.php:635
static activateTagWithChecks(string $tag, string $reason, Authority $performer, bool $ignoreWarnings=false, array $logEntryTags=[])
Activates a tag, checking whether it is allowed first, and adding a log entry afterwards.
Service for formatting and validating API parameters.