MediaWiki  master
ActionModuleBasedHandler.php
Go to the documentation of this file.
1 <?php
2 
4 
5 use ApiBase;
6 use ApiMain;
7 use ApiMessage;
9 use FauxRequest;
10 use IApiMessage;
16 use RequestContext;
17 use WebResponse;
23 
27 abstract class ActionModuleBasedHandler extends Handler {
28 
32  private $session = null;
33 
37  private $apiMain = null;
38 
39  protected function getUser() {
40  return $this->getApiMain()->getUser();
41  }
42 
46  protected function getSession() {
47  if ( !$this->session ) {
48  $this->session = $this->getApiMain()->getRequest()->getSession();
49  }
50 
51  return $this->session;
52  }
53 
59  public function setApiMain( ApiMain $apiMain ) {
60  $this->apiMain = $apiMain;
61  }
62 
66  public function getApiMain() {
67  if ( $this->apiMain ) {
68  return $this->apiMain;
69  }
70 
72  $session = $context->getRequest()->getSession();
73 
74  // NOTE: This being a FauxRequest instance triggers special case behavior
75  // in ApiMain, causing ApiMain::isInternalMode() to return true. Among other things,
76  // this causes ApiMain to throw errors rather than encode them in the result data.
77  $fauxRequest = new FauxRequest( [], true, $session );
78  $fauxRequest->setSessionId( $session->getSessionId() );
79 
80  $fauxContext = new RequestContext();
81  $fauxContext->setRequest( $fauxRequest );
82  $fauxContext->setUser( $context->getUser() );
83  $fauxContext->setLanguage( $context->getLanguage() );
84 
85  $this->apiMain = new ApiMain( $fauxContext, true );
86  return $this->apiMain;
87  }
88 
96  public function overrideActionModule( string $name, string $group, ApiBase $module ) {
97  $this->getApiMain()->getModuleManager()->addModule(
98  $name,
99  $group,
100  [
101  'class' => get_class( $module ),
102  'factory' => function () use ( $module ) {
103  return $module;
104  }
105  ]
106  );
107  }
108 
118  public function execute() {
119  $apiMain = $this->getApiMain();
120 
121  $params = $this->getActionModuleParameters();
123 
124  foreach ( $params as $key => $value ) {
125  $request->setVal( $key, $value );
126  }
127 
128  try {
129  // NOTE: ApiMain detects the this to be an internal call, so it will throw
130  // ApiUsageException rather than putting error messages into the result.
131  $apiMain->execute();
132  } catch ( ApiUsageException $ex ) {
133  // use a fake loop to throw the first error
134  foreach ( $ex->getStatusValue()->getErrorsByType( 'error' ) as $error ) {
135  $msg = ApiMessage::create( $error );
136  $this->throwHttpExceptionForActionModuleError( $msg, $ex->getCode() ?: 400 );
137  }
138 
139  // This should never happen, since ApiUsageExceptions should always
140  // have errors in their Status object.
141  throw new HttpException(
142  'Unmapped action module error: ' . $ex->getMessage(),
143  $ex->getCode()
144  );
145  }
146 
147  $actionModuleResult = $apiMain->getResult()->getResultData( null, [ 'Strip' => 'all' ] );
148 
149  // construct result
150  $resultData = $this->mapActionModuleResult( $actionModuleResult );
151 
152  $response = $this->getResponseFactory()->createFromReturnValue( $resultData );
153 
155  $apiMain->getRequest()->response(),
156  $actionModuleResult,
157  $response
158  );
159 
160  return $response;
161  }
162 
172  abstract protected function getActionModuleParameters();
173 
182  abstract protected function mapActionModuleResult( array $data );
183 
198  protected function mapActionModuleResponse(
199  WebResponse $actionModuleResponse,
200  array $actionModuleResult,
202  ) {
203  // TODO: map status, headers, cookies, etc
204  }
205 
222  protected function throwHttpExceptionForActionModuleError( IApiMessage $msg, $statusCode = 400 ) {
223  // override to supply mappings
224 
225  throw new LocalizedHttpException(
226  $this->makeMessageValue( $msg ),
227  $statusCode,
228  // Include the original error code in the response.
229  // This makes it easier to track down the original cause of the error,
230  // and allows more specific mappings to be added to
231  // implementations of throwHttpExceptionForActionModuleError() provided by
232  // subclasses
233  [ 'actionModuleErrorCode' => $msg->getApiCode() ]
234  );
235  }
236 
244  protected function makeMessageValue( IApiMessage $msg ) {
245  $params = [];
246 
247  // TODO: find a better home for the parameter mapping logic
248  foreach ( $msg->getParams() as $p ) {
249  $params[] = $this->makeMessageParam( $p );
250  }
251 
252  return new MessageValue( $msg->getKey(), $params );
253  }
254 
260  private function makeMessageParam( $param ) {
261  if ( is_array( $param ) ) {
262  foreach ( $param as $type => $value ) {
263  if ( $type === 'list' ) {
264  $paramList = [];
265 
266  foreach ( $value as $v ) {
267  $paramList[] = $this->makeMessageParam( $v );
268  }
269 
270  return new ListParam( ParamType::TEXT, $paramList );
271  } else {
272  return new ScalarParam( $type, $value );
273  }
274  }
275  } else {
276  return new ScalarParam( ParamType::TEXT, $param );
277  }
278  }
279 
280 }
MediaWiki\Rest\Handler\ActionModuleBasedHandler\getApiMain
getApiMain()
Definition: ActionModuleBasedHandler.php:66
ApiUsageException\getStatusValue
getStatusValue()
Fetch the error status.
Definition: ApiUsageException.php:104
MediaWiki\Rest\Handler\ActionModuleBasedHandler\$session
Session null $session
Definition: ActionModuleBasedHandler.php:32
ApiMain
This is the main API class, used for both external and internal processing.
Definition: ApiMain.php:44
MediaWiki\Rest\Handler
Definition: ActionModuleBasedHandler.php:3
FauxRequest
WebRequest clone which takes values from a provided array.
Definition: FauxRequest.php:33
ApiUsageException
Exception used to abort API execution with an error.
Definition: ApiUsageException.php:28
MediaWiki\Rest\Handler\ActionModuleBasedHandler
Base class for REST handlers that are implemented by mapping to an existing ApiModule.
Definition: ActionModuleBasedHandler.php:27
MediaWiki\Rest\Handler\ActionModuleBasedHandler\makeMessageValue
makeMessageValue(IApiMessage $msg)
Constructs a MessageValue from an IApiMessage.
Definition: ActionModuleBasedHandler.php:244
MediaWiki\Rest\Handler\getResponseFactory
getResponseFactory()
Get the ResponseFactory which can be used to generate Response objects.
Definition: Handler.php:104
$response
$response
Definition: opensearch_desc.php:44
MediaWiki\Rest\Handler\$request
RequestInterface $request
Definition: Handler.php:23
MessageSpecifier\getKey
getKey()
Returns the message key.
IApiMessage\getApiCode
getApiCode()
Returns a machine-readable code for use by the API.
ContextSource\getRequest
getRequest()
Definition: ContextSource.php:71
Wikimedia\Message\ScalarParam
Value object representing a message parameter holding a single value.
Definition: ScalarParam.php:10
IApiMessage
Interface for messages with machine-readable data for use by the API.
Definition: IApiMessage.php:39
MediaWiki\Rest\Handler\ActionModuleBasedHandler\getSession
getSession()
Definition: ActionModuleBasedHandler.php:46
Wikimedia\Message\MessageValue
Value object representing a message for i18n.
Definition: MessageValue.php:14
ApiBase
This abstract class implements many basic API functions, and is the base of all API classes.
Definition: ApiBase.php:50
MediaWiki\Rest\Handler
Definition: Handler.php:11
MessageSpecifier\getParams
getParams()
Returns the message parameters.
ApiMessage
Extension of Message implementing IApiMessage.
Definition: ApiMessage.php:26
MediaWiki\Rest\Handler\ActionModuleBasedHandler\setApiMain
setApiMain(ApiMain $apiMain)
Set main action API entry point for testing.
Definition: ActionModuleBasedHandler.php:59
MediaWiki\Rest\Handler\ActionModuleBasedHandler\overrideActionModule
overrideActionModule(string $name, string $group, ApiBase $module)
Overrides an action API module.
Definition: ActionModuleBasedHandler.php:96
MediaWiki\Rest\Handler\ActionModuleBasedHandler\mapActionModuleResponse
mapActionModuleResponse(WebResponse $actionModuleResponse, array $actionModuleResult, Response $response)
Transfers relevant information, such as header values, from the WebResponse constructed by the action...
Definition: ActionModuleBasedHandler.php:198
MediaWiki\Session\Session
Manages data for an an authenticated session.
Definition: Session.php:48
ApiMain\getResult
getResult()
Get the ApiResult object associated with current request.
Definition: ApiMain.php:292
MediaWiki\Rest\Response
Definition: Response.php:8
MediaWiki\Rest\Handler\ActionModuleBasedHandler\throwHttpExceptionForActionModuleError
throwHttpExceptionForActionModuleError(IApiMessage $msg, $statusCode=400)
Throws a HttpException for a given IApiMessage that represents an error.
Definition: ActionModuleBasedHandler.php:222
RequestContext
Group all the pieces relevant to the context of a request into one instance.
Definition: RequestContext.php:34
ApiMessage\create
static create( $msg, $code=null, array $data=null)
Create an IApiMessage for the message.
Definition: ApiMessage.php:40
MediaWiki\Session\Session\getSessionId
getSessionId()
Returns the SessionId object.
Definition: Session.php:89
MediaWiki\Rest\Handler\ActionModuleBasedHandler\getUser
getUser()
Definition: ActionModuleBasedHandler.php:39
MediaWiki\Rest\Handler\ActionModuleBasedHandler\$apiMain
ApiMain null $apiMain
Definition: ActionModuleBasedHandler.php:37
MediaWiki\Rest\HttpException
This is the base exception class for non-fatal exceptions thrown from REST handlers.
Definition: HttpException.php:10
ApiMain\execute
execute()
Execute api request.
Definition: ApiMain.php:491
MediaWiki\Rest\Handler\ActionModuleBasedHandler\execute
execute()
Main execution method, implemented to delegate execution to ApiMain.
Definition: ActionModuleBasedHandler.php:118
IContextSource\getUser
getUser()
RequestContext\getMain
static getMain()
Get the RequestContext object associated with the main request.
Definition: RequestContext.php:451
Wikimedia\Message\ListParam
Value object representing a message parameter that consists of a list of values.
Definition: ListParam.php:10
IContextSource\getRequest
getRequest()
MediaWiki\Rest\Handler\ActionModuleBasedHandler\makeMessageParam
makeMessageParam( $param)
Definition: ActionModuleBasedHandler.php:260
MediaWiki\$context
IContextSource $context
Definition: MediaWiki.php:40
WebResponse
Allow programs to request this object from WebRequest::response() and handle all outputting (or lack ...
Definition: WebResponse.php:28
Wikimedia\Message\MessageParam
Value object representing a message parameter that consists of a list of values.
Definition: MessageParam.php:10
MediaWiki\Rest\Handler\ActionModuleBasedHandler\mapActionModuleResult
mapActionModuleResult(array $data)
Maps an action API result to a REST API result.
MediaWiki\Rest\Handler\ActionModuleBasedHandler\getActionModuleParameters
getActionModuleParameters()
Maps a REST API request to an action API request.
IContextSource\getLanguage
getLanguage()
MediaWiki\Rest\LocalizedHttpException
Definition: LocalizedHttpException.php:7
Wikimedia\Message\ParamType
The constants used to specify parameter types.
Definition: ParamType.php:11
$type
$type
Definition: testCompression.php:52