MediaWiki  master
ApiMain.php
Go to the documentation of this file.
1 <?php
27 
41 class ApiMain extends ApiBase {
45  const API_DEFAULT_FORMAT = 'jsonfm';
46 
50  const API_DEFAULT_USELANG = 'user';
51 
55  private static $Modules = [
56  'login' => ApiLogin::class,
57  'clientlogin' => ApiClientLogin::class,
58  'logout' => ApiLogout::class,
59  'createaccount' => ApiAMCreateAccount::class,
60  'linkaccount' => ApiLinkAccount::class,
61  'unlinkaccount' => ApiRemoveAuthenticationData::class,
62  'changeauthenticationdata' => ApiChangeAuthenticationData::class,
63  'removeauthenticationdata' => ApiRemoveAuthenticationData::class,
64  'resetpassword' => ApiResetPassword::class,
65  'query' => ApiQuery::class,
66  'expandtemplates' => ApiExpandTemplates::class,
67  'parse' => ApiParse::class,
68  'stashedit' => ApiStashEdit::class,
69  'opensearch' => ApiOpenSearch::class,
70  'feedcontributions' => ApiFeedContributions::class,
71  'feedrecentchanges' => ApiFeedRecentChanges::class,
72  'feedwatchlist' => ApiFeedWatchlist::class,
73  'help' => ApiHelp::class,
74  'paraminfo' => ApiParamInfo::class,
75  'rsd' => ApiRsd::class,
76  'compare' => ApiComparePages::class,
77  'tokens' => ApiTokens::class,
78  'checktoken' => ApiCheckToken::class,
79  'cspreport' => ApiCSPReport::class,
80  'validatepassword' => ApiValidatePassword::class,
81 
82  // Write modules
83  'purge' => ApiPurge::class,
84  'setnotificationtimestamp' => ApiSetNotificationTimestamp::class,
85  'rollback' => ApiRollback::class,
86  'delete' => ApiDelete::class,
87  'undelete' => ApiUndelete::class,
88  'protect' => ApiProtect::class,
89  'block' => ApiBlock::class,
90  'unblock' => ApiUnblock::class,
91  'move' => ApiMove::class,
92  'edit' => ApiEditPage::class,
93  'upload' => ApiUpload::class,
94  'filerevert' => ApiFileRevert::class,
95  'emailuser' => ApiEmailUser::class,
96  'watch' => ApiWatch::class,
97  'patrol' => ApiPatrol::class,
98  'import' => ApiImport::class,
99  'clearhasmsg' => ApiClearHasMsg::class,
100  'userrights' => ApiUserrights::class,
101  'options' => ApiOptions::class,
102  'imagerotate' => ApiImageRotate::class,
103  'revisiondelete' => ApiRevisionDelete::class,
104  'managetags' => ApiManageTags::class,
105  'tag' => ApiTag::class,
106  'mergehistory' => ApiMergeHistory::class,
107  'setpagelanguage' => ApiSetPageLanguage::class,
108  ];
109 
113  private static $Formats = [
114  'json' => ApiFormatJson::class,
115  'jsonfm' => ApiFormatJson::class,
116  'php' => ApiFormatPhp::class,
117  'phpfm' => ApiFormatPhp::class,
118  'xml' => ApiFormatXml::class,
119  'xmlfm' => ApiFormatXml::class,
120  'rawfm' => ApiFormatJson::class,
121  'none' => ApiFormatNone::class,
122  ];
123 
130  private static $mRights = [
131  'writeapi' => [
132  'msg' => 'right-writeapi',
133  'params' => []
134  ],
135  'apihighlimits' => [
136  'msg' => 'api-help-right-apihighlimits',
138  ]
139  ];
140 
144  private $mPrinter;
145 
149  private $mAction;
150  private $mEnableWrite;
153  private $mModule;
154 
155  private $mCacheMode = 'private';
156  private $mCacheControl = [];
157  private $mParamsUsed = [];
158  private $mParamsSensitive = [];
159 
162 
170  public function __construct( $context = null, $enableWrite = false ) {
171  if ( $context === null ) {
173  } elseif ( $context instanceof WebRequest ) {
174  // BC for pre-1.19
175  $request = $context;
177  }
178  // We set a derivative context so we can change stuff later
179  $this->setContext( new DerivativeContext( $context ) );
180 
181  if ( isset( $request ) ) {
182  $this->getContext()->setRequest( $request );
183  } else {
184  $request = $this->getRequest();
185  }
186 
187  $this->mInternalMode = ( $request instanceof FauxRequest );
188 
189  // Special handling for the main module: $parent === $this
190  parent::__construct( $this, $this->mInternalMode ? 'main_int' : 'main' );
191 
192  $config = $this->getConfig();
193 
194  if ( !$this->mInternalMode ) {
195  // Log if a request with a non-whitelisted Origin header is seen
196  // with session cookies.
197  $originHeader = $request->getHeader( 'Origin' );
198  if ( $originHeader === false ) {
199  $origins = [];
200  } else {
201  $originHeader = trim( $originHeader );
202  $origins = preg_split( '/\s+/', $originHeader );
203  }
204  $sessionCookies = array_intersect(
205  array_keys( $_COOKIE ),
206  MediaWiki\Session\SessionManager::singleton()->getVaryCookies()
207  );
208  if ( $origins && $sessionCookies && (
209  count( $origins ) !== 1 || !self::matchOrigin(
210  $origins[0],
211  $config->get( 'CrossSiteAJAXdomains' ),
212  $config->get( 'CrossSiteAJAXdomainExceptions' )
213  )
214  ) ) {
215  LoggerFactory::getInstance( 'cors' )->warning(
216  'Non-whitelisted CORS request with session cookies', [
217  'origin' => $originHeader,
218  'cookies' => $sessionCookies,
219  'ip' => $request->getIP(),
220  'userAgent' => $this->getUserAgent(),
221  'wiki' => wfWikiID(),
222  ]
223  );
224  }
225 
226  // If we're in a mode that breaks the same-origin policy, strip
227  // user credentials for security.
228  if ( $this->lacksSameOriginSecurity() ) {
229  global $wgUser;
230  wfDebug( "API: stripping user credentials when the same-origin policy is not applied\n" );
231  $wgUser = new User();
232  $this->getContext()->setUser( $wgUser );
233  $request->response()->header( 'MediaWiki-Login-Suppressed: true' );
234  }
235  }
236 
237  $this->mResult = new ApiResult( $this->getConfig()->get( 'APIMaxResultSize' ) );
238 
239  // Setup uselang. This doesn't use $this->getParameter()
240  // because we're not ready to handle errors yet.
241  $uselang = $request->getVal( 'uselang', self::API_DEFAULT_USELANG );
242  if ( $uselang === 'user' ) {
243  // Assume the parent context is going to return the user language
244  // for uselang=user (see T85635).
245  } else {
246  if ( $uselang === 'content' ) {
247  $uselang = MediaWikiServices::getInstance()->getContentLanguage()->getCode();
248  }
250  $this->getContext()->setLanguage( $code );
251  if ( !$this->mInternalMode ) {
252  global $wgLang;
253  $wgLang = $this->getContext()->getLanguage();
254  RequestContext::getMain()->setLanguage( $wgLang );
255  }
256  }
257 
258  // Set up the error formatter. This doesn't use $this->getParameter()
259  // because we're not ready to handle errors yet.
260  $errorFormat = $request->getVal( 'errorformat', 'bc' );
261  $errorLangCode = $request->getVal( 'errorlang', 'uselang' );
262  $errorsUseDB = $request->getCheck( 'errorsuselocal' );
263  if ( in_array( $errorFormat, [ 'plaintext', 'wikitext', 'html', 'raw', 'none' ], true ) ) {
264  if ( $errorLangCode === 'uselang' ) {
265  $errorLang = $this->getLanguage();
266  } elseif ( $errorLangCode === 'content' ) {
267  $errorLang = MediaWikiServices::getInstance()->getContentLanguage();
268  } else {
269  $errorLangCode = RequestContext::sanitizeLangCode( $errorLangCode );
270  $errorLang = Language::factory( $errorLangCode );
271  }
272  $this->mErrorFormatter = new ApiErrorFormatter(
273  $this->mResult, $errorLang, $errorFormat, $errorsUseDB
274  );
275  } else {
276  $this->mErrorFormatter = new ApiErrorFormatter_BackCompat( $this->mResult );
277  }
278  $this->mResult->setErrorFormatter( $this->getErrorFormatter() );
279 
280  $this->mModuleMgr = new ApiModuleManager( $this );
281  $this->mModuleMgr->addModules( self::$Modules, 'action' );
282  $this->mModuleMgr->addModules( $config->get( 'APIModules' ), 'action' );
283  $this->mModuleMgr->addModules( self::$Formats, 'format' );
284  $this->mModuleMgr->addModules( $config->get( 'APIFormatModules' ), 'format' );
285 
286  Hooks::run( 'ApiMain::moduleManager', [ $this->mModuleMgr ] );
287 
288  $this->mContinuationManager = null;
289  $this->mEnableWrite = $enableWrite;
290 
291  $this->mSquidMaxage = -1; // flag for executeActionWithErrorHandling()
292  $this->mCommit = false;
293  }
294 
299  public function isInternalMode() {
300  return $this->mInternalMode;
301  }
302 
308  public function getResult() {
309  return $this->mResult;
310  }
311 
316  public function lacksSameOriginSecurity() {
317  if ( $this->lacksSameOriginSecurity !== null ) {
319  }
320 
321  $request = $this->getRequest();
322 
323  // JSONP mode
324  if ( $request->getVal( 'callback' ) !== null ) {
325  $this->lacksSameOriginSecurity = true;
326  return true;
327  }
328 
329  // Anonymous CORS
330  if ( $request->getVal( 'origin' ) === '*' ) {
331  $this->lacksSameOriginSecurity = true;
332  return true;
333  }
334 
335  // Header to be used from XMLHTTPRequest when the request might
336  // otherwise be used for XSS.
337  if ( $request->getHeader( 'Treat-as-Untrusted' ) !== false ) {
338  $this->lacksSameOriginSecurity = true;
339  return true;
340  }
341 
342  // Allow extensions to override.
343  $this->lacksSameOriginSecurity = !Hooks::run( 'RequestHasSameOriginSecurity', [ $request ] );
345  }
346 
351  public function getErrorFormatter() {
352  return $this->mErrorFormatter;
353  }
354 
359  public function getContinuationManager() {
361  }
362 
367  public function setContinuationManager( ApiContinuationManager $manager = null ) {
368  if ( $manager !== null && $this->mContinuationManager !== null ) {
369  throw new UnexpectedValueException(
370  __METHOD__ . ': tried to set manager from ' . $manager->getSource() .
371  ' when a manager is already set from ' . $this->mContinuationManager->getSource()
372  );
373  }
374  $this->mContinuationManager = $manager;
375  }
376 
382  public function getModule() {
383  return $this->mModule;
384  }
385 
391  public function getPrinter() {
392  return $this->mPrinter;
393  }
394 
400  public function setCacheMaxAge( $maxage ) {
401  $this->setCacheControl( [
402  'max-age' => $maxage,
403  's-maxage' => $maxage
404  ] );
405  }
406 
432  public function setCacheMode( $mode ) {
433  if ( !in_array( $mode, [ 'private', 'public', 'anon-public-user-private' ] ) ) {
434  wfDebug( __METHOD__ . ": unrecognised cache mode \"$mode\"\n" );
435 
436  // Ignore for forwards-compatibility
437  return;
438  }
439 
440  if ( !User::isEveryoneAllowed( 'read' ) ) {
441  // Private wiki, only private headers
442  if ( $mode !== 'private' ) {
443  wfDebug( __METHOD__ . ": ignoring request for $mode cache mode, private wiki\n" );
444 
445  return;
446  }
447  }
448 
449  if ( $mode === 'public' && $this->getParameter( 'uselang' ) === 'user' ) {
450  // User language is used for i18n, so we don't want to publicly
451  // cache. Anons are ok, because if they have non-default language
452  // then there's an appropriate Vary header set by whatever set
453  // their non-default language.
454  wfDebug( __METHOD__ . ": downgrading cache mode 'public' to " .
455  "'anon-public-user-private' due to uselang=user\n" );
456  $mode = 'anon-public-user-private';
457  }
458 
459  wfDebug( __METHOD__ . ": setting cache mode $mode\n" );
460  $this->mCacheMode = $mode;
461  }
462 
473  public function setCacheControl( $directives ) {
474  $this->mCacheControl = $directives + $this->mCacheControl;
475  }
476 
484  public function createPrinterByName( $format ) {
485  $printer = $this->mModuleMgr->getModule( $format, 'format', /* $ignoreCache */ true );
486  if ( $printer === null ) {
487  $this->dieWithError(
488  [ 'apierror-unknownformat', wfEscapeWikiText( $format ) ], 'unknown_format'
489  );
490  }
491 
492  return $printer;
493  }
494 
498  public function execute() {
499  if ( $this->mInternalMode ) {
500  $this->executeAction();
501  } else {
503  }
504  }
505 
510  protected function executeActionWithErrorHandling() {
511  // Verify the CORS header before executing the action
512  if ( !$this->handleCORS() ) {
513  // handleCORS() has sent a 403, abort
514  return;
515  }
516 
517  // Exit here if the request method was OPTIONS
518  // (assume there will be a followup GET or POST)
519  if ( $this->getRequest()->getMethod() === 'OPTIONS' ) {
520  return;
521  }
522 
523  // In case an error occurs during data output,
524  // clear the output buffer and print just the error information
525  $obLevel = ob_get_level();
526  ob_start();
527 
528  $t = microtime( true );
529  $isError = false;
530  try {
531  $this->executeAction();
532  $runTime = microtime( true ) - $t;
533  $this->logRequest( $runTime );
534  MediaWikiServices::getInstance()->getStatsdDataFactory()->timing(
535  'api.' . $this->mModule->getModuleName() . '.executeTiming', 1000 * $runTime
536  );
537  } catch ( Exception $e ) { // @todo Remove this block when HHVM is no longer supported
538  $this->handleException( $e );
539  $this->logRequest( microtime( true ) - $t, $e );
540  $isError = true;
541  } catch ( Throwable $e ) {
542  $this->handleException( $e );
543  $this->logRequest( microtime( true ) - $t, $e );
544  $isError = true;
545  }
546 
547  // Commit DBs and send any related cookies and headers
549 
550  // Send cache headers after any code which might generate an error, to
551  // avoid sending public cache headers for errors.
552  $this->sendCacheHeaders( $isError );
553 
554  // Executing the action might have already messed with the output
555  // buffers.
556  while ( ob_get_level() > $obLevel ) {
557  ob_end_flush();
558  }
559  }
560 
567  protected function handleException( $e ) {
568  // T65145: Rollback any open database transactions
569  if ( !$e instanceof ApiUsageException ) {
570  // ApiUsageExceptions are intentional, so don't rollback if that's the case
572  }
573 
574  // Allow extra cleanup and logging
575  Hooks::run( 'ApiMain::onException', [ $this, $e ] );
576 
577  // Handle any kind of exception by outputting properly formatted error message.
578  // If this fails, an unhandled exception should be thrown so that global error
579  // handler will process and log it.
580 
581  $errCodes = $this->substituteResultWithError( $e );
582 
583  // Error results should not be cached
584  $this->setCacheMode( 'private' );
585 
586  $response = $this->getRequest()->response();
587  $headerStr = 'MediaWiki-API-Error: ' . implode( ', ', $errCodes );
588  $response->header( $headerStr );
589 
590  // Reset and print just the error message
591  ob_clean();
592 
593  // Printer may not be initialized if the extractRequestParams() fails for the main module
594  $this->createErrorPrinter();
595 
596  $failed = false;
597  try {
598  $this->printResult( $e->getCode() );
599  } catch ( ApiUsageException $ex ) {
600  // The error printer itself is failing. Try suppressing its request
601  // parameters and redo.
602  $failed = true;
603  $this->addWarning( 'apiwarn-errorprinterfailed' );
604  foreach ( $ex->getStatusValue()->getErrors() as $error ) {
605  try {
606  $this->mPrinter->addWarning( $error );
607  } catch ( Exception $ex2 ) { // @todo Remove this block when HHVM is no longer supported
608  // WTF?
609  $this->addWarning( $error );
610  } catch ( Throwable $ex2 ) {
611  // WTF?
612  $this->addWarning( $error );
613  }
614  }
615  }
616  if ( $failed ) {
617  $this->mPrinter = null;
618  $this->createErrorPrinter();
619  $this->mPrinter->forceDefaultParams();
620  if ( $e->getCode() ) {
621  $response->statusHeader( 200 ); // Reset in case the fallback doesn't want a non-200
622  }
623  $this->printResult( $e->getCode() );
624  }
625  }
626 
637  public static function handleApiBeforeMainException( $e ) {
638  ob_start();
639 
640  try {
641  $main = new self( RequestContext::getMain(), false );
642  $main->handleException( $e );
643  $main->logRequest( 0, $e );
644  } catch ( Exception $e2 ) { // @todo Remove this block when HHVM is no longer supported
645  // Nope, even that didn't work. Punt.
646  throw $e;
647  } catch ( Throwable $e2 ) {
648  // Nope, even that didn't work. Punt.
649  throw $e;
650  }
651 
652  // Reset cache headers
653  $main->sendCacheHeaders( true );
654 
655  ob_end_flush();
656  }
657 
672  protected function handleCORS() {
673  $originParam = $this->getParameter( 'origin' ); // defaults to null
674  if ( $originParam === null ) {
675  // No origin parameter, nothing to do
676  return true;
677  }
678 
679  $request = $this->getRequest();
680  $response = $request->response();
681 
682  $matchedOrigin = false;
683  $allowTiming = false;
684  $varyOrigin = true;
685 
686  if ( $originParam === '*' ) {
687  // Request for anonymous CORS
688  // Technically we should check for the presence of an Origin header
689  // and not process it as CORS if it's not set, but that would
690  // require us to vary on Origin for all 'origin=*' requests which
691  // we don't want to do.
692  $matchedOrigin = true;
693  $allowOrigin = '*';
694  $allowCredentials = 'false';
695  $varyOrigin = false; // No need to vary
696  } else {
697  // Non-anonymous CORS, check we allow the domain
698 
699  // Origin: header is a space-separated list of origins, check all of them
700  $originHeader = $request->getHeader( 'Origin' );
701  if ( $originHeader === false ) {
702  $origins = [];
703  } else {
704  $originHeader = trim( $originHeader );
705  $origins = preg_split( '/\s+/', $originHeader );
706  }
707 
708  if ( !in_array( $originParam, $origins ) ) {
709  // origin parameter set but incorrect
710  // Send a 403 response
711  $response->statusHeader( 403 );
712  $response->header( 'Cache-Control: no-cache' );
713  echo "'origin' parameter does not match Origin header\n";
714 
715  return false;
716  }
717 
718  $config = $this->getConfig();
719  $matchedOrigin = count( $origins ) === 1 && self::matchOrigin(
720  $originParam,
721  $config->get( 'CrossSiteAJAXdomains' ),
722  $config->get( 'CrossSiteAJAXdomainExceptions' )
723  );
724 
725  $allowOrigin = $originHeader;
726  $allowCredentials = 'true';
727  $allowTiming = $originHeader;
728  }
729 
730  if ( $matchedOrigin ) {
731  $requestedMethod = $request->getHeader( 'Access-Control-Request-Method' );
732  $preflight = $request->getMethod() === 'OPTIONS' && $requestedMethod !== false;
733  if ( $preflight ) {
734  // This is a CORS preflight request
735  if ( $requestedMethod !== 'POST' && $requestedMethod !== 'GET' ) {
736  // If method is not a case-sensitive match, do not set any additional headers and terminate.
737  $response->header( 'MediaWiki-CORS-Rejection: Unsupported method requested in preflight' );
738  return true;
739  }
740  // We allow the actual request to send the following headers
741  $requestedHeaders = $request->getHeader( 'Access-Control-Request-Headers' );
742  if ( $requestedHeaders !== false ) {
743  if ( !self::matchRequestedHeaders( $requestedHeaders ) ) {
744  $response->header( 'MediaWiki-CORS-Rejection: Unsupported header requested in preflight' );
745  return true;
746  }
747  $response->header( 'Access-Control-Allow-Headers: ' . $requestedHeaders );
748  }
749 
750  // We only allow the actual request to be GET or POST
751  $response->header( 'Access-Control-Allow-Methods: POST, GET' );
752  } elseif ( $request->getMethod() !== 'POST' && $request->getMethod() !== 'GET' ) {
753  // Unsupported non-preflight method, don't handle it as CORS
754  $response->header(
755  'MediaWiki-CORS-Rejection: Unsupported method for simple request or actual request'
756  );
757  return true;
758  }
759 
760  $response->header( "Access-Control-Allow-Origin: $allowOrigin" );
761  $response->header( "Access-Control-Allow-Credentials: $allowCredentials" );
762  // https://www.w3.org/TR/resource-timing/#timing-allow-origin
763  if ( $allowTiming !== false ) {
764  $response->header( "Timing-Allow-Origin: $allowTiming" );
765  }
766 
767  if ( !$preflight ) {
768  $response->header(
769  'Access-Control-Expose-Headers: MediaWiki-API-Error, Retry-After, X-Database-Lag, '
770  . 'MediaWiki-Login-Suppressed'
771  );
772  }
773  } else {
774  $response->header( 'MediaWiki-CORS-Rejection: Origin mismatch' );
775  }
776 
777  if ( $varyOrigin ) {
778  $this->getOutput()->addVaryHeader( 'Origin' );
779  }
780 
781  return true;
782  }
783 
792  protected static function matchOrigin( $value, $rules, $exceptions ) {
793  foreach ( $rules as $rule ) {
794  if ( preg_match( self::wildcardToRegex( $rule ), $value ) ) {
795  // Rule matches, check exceptions
796  foreach ( $exceptions as $exc ) {
797  if ( preg_match( self::wildcardToRegex( $exc ), $value ) ) {
798  return false;
799  }
800  }
801 
802  return true;
803  }
804  }
805 
806  return false;
807  }
808 
816  protected static function matchRequestedHeaders( $requestedHeaders ) {
817  if ( trim( $requestedHeaders ) === '' ) {
818  return true;
819  }
820  $requestedHeaders = explode( ',', $requestedHeaders );
821  $allowedAuthorHeaders = array_flip( [
822  /* simple headers (see spec) */
823  'accept',
824  'accept-language',
825  'content-language',
826  'content-type',
827  /* non-authorable headers in XHR, which are however requested by some UAs */
828  'accept-encoding',
829  'dnt',
830  'origin',
831  /* MediaWiki whitelist */
832  'user-agent',
833  'api-user-agent',
834  ] );
835  foreach ( $requestedHeaders as $rHeader ) {
836  $rHeader = strtolower( trim( $rHeader ) );
837  if ( !isset( $allowedAuthorHeaders[$rHeader] ) ) {
838  LoggerFactory::getInstance( 'api-warning' )->warning(
839  'CORS preflight failed on requested header: {header}', [
840  'header' => $rHeader
841  ]
842  );
843  return false;
844  }
845  }
846  return true;
847  }
848 
857  protected static function wildcardToRegex( $wildcard ) {
858  $wildcard = preg_quote( $wildcard, '/' );
859  $wildcard = str_replace(
860  [ '\*', '\?' ],
861  [ '.*?', '.' ],
862  $wildcard
863  );
864 
865  return "/^https?:\/\/$wildcard$/";
866  }
867 
873  protected function sendCacheHeaders( $isError ) {
874  $response = $this->getRequest()->response();
875  $out = $this->getOutput();
876 
877  $out->addVaryHeader( 'Treat-as-Untrusted' );
878 
879  $config = $this->getConfig();
880 
881  if ( $config->get( 'VaryOnXFP' ) ) {
882  $out->addVaryHeader( 'X-Forwarded-Proto' );
883  }
884 
885  if ( !$isError && $this->mModule &&
886  ( $this->getRequest()->getMethod() === 'GET' || $this->getRequest()->getMethod() === 'HEAD' )
887  ) {
888  $etag = $this->mModule->getConditionalRequestData( 'etag' );
889  if ( $etag !== null ) {
890  $response->header( "ETag: $etag" );
891  }
892  $lastMod = $this->mModule->getConditionalRequestData( 'last-modified' );
893  if ( $lastMod !== null ) {
894  $response->header( 'Last-Modified: ' . wfTimestamp( TS_RFC2822, $lastMod ) );
895  }
896  }
897 
898  // The logic should be:
899  // $this->mCacheControl['max-age'] is set?
900  // Use it, the module knows better than our guess.
901  // !$this->mModule || $this->mModule->isWriteMode(), and mCacheMode is private?
902  // Use 0 because we can guess caching is probably the wrong thing to do.
903  // Use $this->getParameter( 'maxage' ), which already defaults to 0.
904  $maxage = 0;
905  if ( isset( $this->mCacheControl['max-age'] ) ) {
906  $maxage = $this->mCacheControl['max-age'];
907  } elseif ( ( $this->mModule && !$this->mModule->isWriteMode() ) ||
908  $this->mCacheMode !== 'private'
909  ) {
910  $maxage = $this->getParameter( 'maxage' );
911  }
912  $privateCache = 'private, must-revalidate, max-age=' . $maxage;
913 
914  if ( $this->mCacheMode == 'private' ) {
915  $response->header( "Cache-Control: $privateCache" );
916  return;
917  }
918 
919  $useKeyHeader = $config->get( 'UseKeyHeader' );
920  if ( $this->mCacheMode == 'anon-public-user-private' ) {
921  $out->addVaryHeader( 'Cookie' );
922  $response->header( $out->getVaryHeader() );
923  if ( $useKeyHeader ) {
924  $response->header( $out->getKeyHeader() );
925  if ( $out->haveCacheVaryCookies() ) {
926  // Logged in, mark this request private
927  $response->header( "Cache-Control: $privateCache" );
928  return;
929  }
930  // Logged out, send normal public headers below
931  } elseif ( MediaWiki\Session\SessionManager::getGlobalSession()->isPersistent() ) {
932  // Logged in or otherwise has session (e.g. anonymous users who have edited)
933  // Mark request private
934  $response->header( "Cache-Control: $privateCache" );
935 
936  return;
937  } // else no Key and anonymous, send public headers below
938  }
939 
940  // Send public headers
941  $response->header( $out->getVaryHeader() );
942  if ( $useKeyHeader ) {
943  $response->header( $out->getKeyHeader() );
944  }
945 
946  // If nobody called setCacheMaxAge(), use the (s)maxage parameters
947  if ( !isset( $this->mCacheControl['s-maxage'] ) ) {
948  $this->mCacheControl['s-maxage'] = $this->getParameter( 'smaxage' );
949  }
950  if ( !isset( $this->mCacheControl['max-age'] ) ) {
951  $this->mCacheControl['max-age'] = $this->getParameter( 'maxage' );
952  }
953 
954  if ( !$this->mCacheControl['s-maxage'] && !$this->mCacheControl['max-age'] ) {
955  // Public cache not requested
956  // Sending a Vary header in this case is harmless, and protects us
957  // against conditional calls of setCacheMaxAge().
958  $response->header( "Cache-Control: $privateCache" );
959 
960  return;
961  }
962 
963  $this->mCacheControl['public'] = true;
964 
965  // Send an Expires header
966  $maxAge = min( $this->mCacheControl['s-maxage'], $this->mCacheControl['max-age'] );
967  $expiryUnixTime = ( $maxAge == 0 ? 1 : time() + $maxAge );
968  $response->header( 'Expires: ' . wfTimestamp( TS_RFC2822, $expiryUnixTime ) );
969 
970  // Construct the Cache-Control header
971  $ccHeader = '';
972  $separator = '';
973  foreach ( $this->mCacheControl as $name => $value ) {
974  if ( is_bool( $value ) ) {
975  if ( $value ) {
976  $ccHeader .= $separator . $name;
977  $separator = ', ';
978  }
979  } else {
980  $ccHeader .= $separator . "$name=$value";
981  $separator = ', ';
982  }
983  }
984 
985  $response->header( "Cache-Control: $ccHeader" );
986  }
987 
991  private function createErrorPrinter() {
992  if ( !isset( $this->mPrinter ) ) {
993  $value = $this->getRequest()->getVal( 'format', self::API_DEFAULT_FORMAT );
994  if ( !$this->mModuleMgr->isDefined( $value, 'format' ) ) {
995  $value = self::API_DEFAULT_FORMAT;
996  }
997  $this->mPrinter = $this->createPrinterByName( $value );
998  }
999 
1000  // Printer may not be able to handle errors. This is particularly
1001  // likely if the module returns something for getCustomPrinter().
1002  if ( !$this->mPrinter->canPrintErrors() ) {
1003  $this->mPrinter = $this->createPrinterByName( self::API_DEFAULT_FORMAT );
1004  }
1005  }
1006 
1022  protected function errorMessagesFromException( $e, $type = 'error' ) {
1023  $messages = [];
1024  if ( $e instanceof ApiUsageException ) {
1025  foreach ( $e->getStatusValue()->getErrorsByType( $type ) as $error ) {
1026  $messages[] = ApiMessage::create( $error );
1027  }
1028  } elseif ( $type !== 'error' ) {
1029  // None of the rest have any messages for non-error types
1030  } else {
1031  // Something is seriously wrong
1032  $config = $this->getConfig();
1033  // TODO: Avoid embedding arbitrary class names in the error code.
1034  $class = preg_replace( '#^Wikimedia\\\Rdbms\\\#', '', get_class( $e ) );
1035  $code = 'internal_api_error_' . $class;
1036  $data = [ 'errorclass' => get_class( $e ) ];
1037  if ( $config->get( 'ShowExceptionDetails' ) ) {
1038  if ( $e instanceof ILocalizedException ) {
1039  $msg = $e->getMessageObject();
1040  } elseif ( $e instanceof MessageSpecifier ) {
1041  $msg = Message::newFromSpecifier( $e );
1042  } else {
1043  $msg = wfEscapeWikiText( $e->getMessage() );
1044  }
1045  $params = [ 'apierror-exceptioncaught', WebRequest::getRequestId(), $msg ];
1046  } else {
1047  $params = [ 'apierror-exceptioncaughttype', WebRequest::getRequestId(), get_class( $e ) ];
1048  }
1049 
1050  $messages[] = ApiMessage::create( $params, $code, $data );
1051  }
1052  return $messages;
1053  }
1054 
1060  protected function substituteResultWithError( $e ) {
1061  $result = $this->getResult();
1062  $formatter = $this->getErrorFormatter();
1063  $config = $this->getConfig();
1064  $errorCodes = [];
1065 
1066  // Remember existing warnings and errors across the reset
1067  $errors = $result->getResultData( [ 'errors' ] );
1068  $warnings = $result->getResultData( [ 'warnings' ] );
1069  $result->reset();
1070  if ( $warnings !== null ) {
1071  $result->addValue( null, 'warnings', $warnings, ApiResult::NO_SIZE_CHECK );
1072  }
1073  if ( $errors !== null ) {
1074  $result->addValue( null, 'errors', $errors, ApiResult::NO_SIZE_CHECK );
1075 
1076  // Collect the copied error codes for the return value
1077  foreach ( $errors as $error ) {
1078  if ( isset( $error['code'] ) ) {
1079  $errorCodes[$error['code']] = true;
1080  }
1081  }
1082  }
1083 
1084  // Add errors from the exception
1085  $modulePath = $e instanceof ApiUsageException ? $e->getModulePath() : null;
1086  foreach ( $this->errorMessagesFromException( $e, 'error' ) as $msg ) {
1087  if ( ApiErrorFormatter::isValidApiCode( $msg->getApiCode() ) ) {
1088  $errorCodes[$msg->getApiCode()] = true;
1089  } else {
1090  LoggerFactory::getInstance( 'api-warning' )->error( 'Invalid API error code "{code}"', [
1091  'code' => $msg->getApiCode(),
1092  'exception' => $e,
1093  ] );
1094  $errorCodes['<invalid-code>'] = true;
1095  }
1096  $formatter->addError( $modulePath, $msg );
1097  }
1098  foreach ( $this->errorMessagesFromException( $e, 'warning' ) as $msg ) {
1099  $formatter->addWarning( $modulePath, $msg );
1100  }
1101 
1102  // Add additional data. Path depends on whether we're in BC mode or not.
1103  // Data depends on the type of exception.
1104  if ( $formatter instanceof ApiErrorFormatter_BackCompat ) {
1105  $path = [ 'error' ];
1106  } else {
1107  $path = null;
1108  }
1109  if ( $e instanceof ApiUsageException ) {
1110  $link = wfExpandUrl( wfScript( 'api' ) );
1111  $result->addContentValue(
1112  $path,
1113  'docref',
1114  trim(
1115  $this->msg( 'api-usage-docref', $link )->inLanguage( $formatter->getLanguage() )->text()
1116  . ' '
1117  . $this->msg( 'api-usage-mailinglist-ref' )->inLanguage( $formatter->getLanguage() )->text()
1118  )
1119  );
1120  } else {
1121  if ( $config->get( 'ShowExceptionDetails' ) ) {
1122  $result->addContentValue(
1123  $path,
1124  'trace',
1125  $this->msg( 'api-exception-trace',
1126  get_class( $e ),
1127  $e->getFile(),
1128  $e->getLine(),
1130  )->inLanguage( $formatter->getLanguage() )->text()
1131  );
1132  }
1133  }
1134 
1135  // Add the id and such
1136  $this->addRequestedFields( [ 'servedby' ] );
1137 
1138  return array_keys( $errorCodes );
1139  }
1140 
1146  protected function addRequestedFields( $force = [] ) {
1147  $result = $this->getResult();
1148 
1149  $requestid = $this->getParameter( 'requestid' );
1150  if ( $requestid !== null ) {
1151  $result->addValue( null, 'requestid', $requestid, ApiResult::NO_SIZE_CHECK );
1152  }
1153 
1154  if ( $this->getConfig()->get( 'ShowHostnames' ) && (
1155  in_array( 'servedby', $force, true ) || $this->getParameter( 'servedby' )
1156  ) ) {
1157  $result->addValue( null, 'servedby', wfHostname(), ApiResult::NO_SIZE_CHECK );
1158  }
1159 
1160  if ( $this->getParameter( 'curtimestamp' ) ) {
1161  $result->addValue( null, 'curtimestamp', wfTimestamp( TS_ISO_8601, time() ),
1163  }
1164 
1165  if ( $this->getParameter( 'responselanginfo' ) ) {
1166  $result->addValue( null, 'uselang', $this->getLanguage()->getCode(),
1168  $result->addValue( null, 'errorlang', $this->getErrorFormatter()->getLanguage()->getCode(),
1170  }
1171  }
1172 
1177  protected function setupExecuteAction() {
1178  $this->addRequestedFields();
1179 
1180  $params = $this->extractRequestParams();
1181  $this->mAction = $params['action'];
1182 
1183  return $params;
1184  }
1185 
1192  protected function setupModule() {
1193  // Instantiate the module requested by the user
1194  $module = $this->mModuleMgr->getModule( $this->mAction, 'action' );
1195  if ( $module === null ) {
1196  // Probably can't happen
1197  // @codeCoverageIgnoreStart
1198  $this->dieWithError(
1199  [ 'apierror-unknownaction', wfEscapeWikiText( $this->mAction ) ], 'unknown_action'
1200  );
1201  // @codeCoverageIgnoreEnd
1202  }
1203  $moduleParams = $module->extractRequestParams();
1204 
1205  // Check token, if necessary
1206  if ( $module->needsToken() === true ) {
1207  throw new MWException(
1208  "Module '{$module->getModuleName()}' must be updated for the new token handling. " .
1209  'See documentation for ApiBase::needsToken for details.'
1210  );
1211  }
1212  if ( $module->needsToken() ) {
1213  if ( !$module->mustBePosted() ) {
1214  throw new MWException(
1215  "Module '{$module->getModuleName()}' must require POST to use tokens."
1216  );
1217  }
1218 
1219  if ( !isset( $moduleParams['token'] ) ) {
1220  // Probably can't happen
1221  // @codeCoverageIgnoreStart
1222  $module->dieWithError( [ 'apierror-missingparam', 'token' ] );
1223  // @codeCoverageIgnoreEnd
1224  }
1225 
1226  $module->requirePostedParameters( [ 'token' ] );
1227 
1228  if ( !$module->validateToken( $moduleParams['token'], $moduleParams ) ) {
1229  $module->dieWithError( 'apierror-badtoken' );
1230  }
1231  }
1232 
1233  return $module;
1234  }
1235 
1239  private function getMaxLag() {
1240  $dbLag = MediaWikiServices::getInstance()->getDBLoadBalancer()->getMaxLag();
1241  $lagInfo = [
1242  'host' => $dbLag[0],
1243  'lag' => $dbLag[1],
1244  'type' => 'db'
1245  ];
1246 
1247  $jobQueueLagFactor = $this->getConfig()->get( 'JobQueueIncludeInMaxLagFactor' );
1248  if ( $jobQueueLagFactor ) {
1249  // Turn total number of jobs into seconds by using the configured value
1250  $totalJobs = array_sum( JobQueueGroup::singleton()->getQueueSizes() );
1251  $jobQueueLag = $totalJobs / (float)$jobQueueLagFactor;
1252  if ( $jobQueueLag > $lagInfo['lag'] ) {
1253  $lagInfo = [
1254  'host' => wfHostname(), // XXX: Is there a better value that could be used?
1255  'lag' => $jobQueueLag,
1256  'type' => 'jobqueue',
1257  'jobs' => $totalJobs,
1258  ];
1259  }
1260  }
1261 
1262  Hooks::runWithoutAbort( 'ApiMaxLagInfo', [ &$lagInfo ] );
1263 
1264  return $lagInfo;
1265  }
1266 
1273  protected function checkMaxLag( $module, $params ) {
1274  if ( $module->shouldCheckMaxlag() && isset( $params['maxlag'] ) ) {
1275  $maxLag = $params['maxlag'];
1276  $lagInfo = $this->getMaxLag();
1277  if ( $lagInfo['lag'] > $maxLag ) {
1278  $response = $this->getRequest()->response();
1279 
1280  $response->header( 'Retry-After: ' . max( intval( $maxLag ), 5 ) );
1281  $response->header( 'X-Database-Lag: ' . intval( $lagInfo['lag'] ) );
1282 
1283  if ( $this->getConfig()->get( 'ShowHostnames' ) ) {
1284  $this->dieWithError(
1285  [ 'apierror-maxlag', $lagInfo['lag'], $lagInfo['host'] ],
1286  'maxlag',
1287  $lagInfo
1288  );
1289  }
1290 
1291  $this->dieWithError( [ 'apierror-maxlag-generic', $lagInfo['lag'] ], 'maxlag', $lagInfo );
1292  }
1293  }
1294 
1295  return true;
1296  }
1297 
1319  protected function checkConditionalRequestHeaders( $module ) {
1320  if ( $this->mInternalMode ) {
1321  // No headers to check in internal mode
1322  return true;
1323  }
1324 
1325  if ( $this->getRequest()->getMethod() !== 'GET' && $this->getRequest()->getMethod() !== 'HEAD' ) {
1326  // Don't check POSTs
1327  return true;
1328  }
1329 
1330  $return304 = false;
1331 
1332  $ifNoneMatch = array_diff(
1333  $this->getRequest()->getHeader( 'If-None-Match', WebRequest::GETHEADER_LIST ) ?: [],
1334  [ '' ]
1335  );
1336  if ( $ifNoneMatch ) {
1337  if ( $ifNoneMatch === [ '*' ] ) {
1338  // API responses always "exist"
1339  $etag = '*';
1340  } else {
1341  $etag = $module->getConditionalRequestData( 'etag' );
1342  }
1343  }
1344  if ( $ifNoneMatch && $etag !== null ) {
1345  $test = substr( $etag, 0, 2 ) === 'W/' ? substr( $etag, 2 ) : $etag;
1346  $match = array_map( function ( $s ) {
1347  return substr( $s, 0, 2 ) === 'W/' ? substr( $s, 2 ) : $s;
1348  }, $ifNoneMatch );
1349  $return304 = in_array( $test, $match, true );
1350  } else {
1351  $value = trim( $this->getRequest()->getHeader( 'If-Modified-Since' ) );
1352 
1353  // Some old browsers sends sizes after the date, like this:
1354  // Wed, 20 Aug 2003 06:51:19 GMT; length=5202
1355  // Ignore that.
1356  $i = strpos( $value, ';' );
1357  if ( $i !== false ) {
1358  $value = trim( substr( $value, 0, $i ) );
1359  }
1360 
1361  if ( $value !== '' ) {
1362  try {
1363  $ts = new MWTimestamp( $value );
1364  if (
1365  // RFC 7231 IMF-fixdate
1366  $ts->getTimestamp( TS_RFC2822 ) === $value ||
1367  // RFC 850
1368  $ts->format( 'l, d-M-y H:i:s' ) . ' GMT' === $value ||
1369  // asctime (with and without space-padded day)
1370  $ts->format( 'D M j H:i:s Y' ) === $value ||
1371  $ts->format( 'D M j H:i:s Y' ) === $value
1372  ) {
1373  $lastMod = $module->getConditionalRequestData( 'last-modified' );
1374  if ( $lastMod !== null ) {
1375  // Mix in some MediaWiki modification times
1376  $modifiedTimes = [
1377  'page' => $lastMod,
1378  'user' => $this->getUser()->getTouched(),
1379  'epoch' => $this->getConfig()->get( 'CacheEpoch' ),
1380  ];
1381  if ( $this->getConfig()->get( 'UseSquid' ) ) {
1382  // T46570: the core page itself may not change, but resources might
1383  $modifiedTimes['sepoch'] = wfTimestamp(
1384  TS_MW, time() - $this->getConfig()->get( 'SquidMaxage' )
1385  );
1386  }
1387  Hooks::run( 'OutputPageCheckLastModified', [ &$modifiedTimes, $this->getOutput() ] );
1388  $lastMod = max( $modifiedTimes );
1389  $return304 = wfTimestamp( TS_MW, $lastMod ) <= $ts->getTimestamp( TS_MW );
1390  }
1391  }
1392  } catch ( TimestampException $e ) {
1393  // Invalid timestamp, ignore it
1394  }
1395  }
1396  }
1397 
1398  if ( $return304 ) {
1399  $this->getRequest()->response()->statusHeader( 304 );
1400 
1401  // Avoid outputting the compressed representation of a zero-length body
1402  Wikimedia\suppressWarnings();
1403  ini_set( 'zlib.output_compression', 0 );
1404  Wikimedia\restoreWarnings();
1406 
1407  return false;
1408  }
1409 
1410  return true;
1411  }
1412 
1417  protected function checkExecutePermissions( $module ) {
1418  $user = $this->getUser();
1419  if ( $module->isReadMode() && !User::isEveryoneAllowed( 'read' ) &&
1420  !$user->isAllowed( 'read' )
1421  ) {
1422  $this->dieWithError( 'apierror-readapidenied' );
1423  }
1424 
1425  if ( $module->isWriteMode() ) {
1426  if ( !$this->mEnableWrite ) {
1427  $this->dieWithError( 'apierror-noapiwrite' );
1428  } elseif ( !$user->isAllowed( 'writeapi' ) ) {
1429  $this->dieWithError( 'apierror-writeapidenied' );
1430  } elseif ( $this->getRequest()->getHeader( 'Promise-Non-Write-API-Action' ) ) {
1431  $this->dieWithError( 'apierror-promised-nonwrite-api' );
1432  }
1433 
1434  $this->checkReadOnly( $module );
1435  }
1436 
1437  // Allow extensions to stop execution for arbitrary reasons.
1438  $message = 'hookaborted';
1439  if ( !Hooks::run( 'ApiCheckCanExecute', [ $module, $user, &$message ] ) ) {
1440  $this->dieWithError( $message );
1441  }
1442  }
1443 
1448  protected function checkReadOnly( $module ) {
1449  if ( wfReadOnly() ) {
1450  $this->dieReadOnly();
1451  }
1452 
1453  if ( $module->isWriteMode()
1454  && $this->getUser()->isBot()
1455  && MediaWikiServices::getInstance()->getDBLoadBalancer()->getServerCount() > 1
1456  ) {
1457  $this->checkBotReadOnly();
1458  }
1459  }
1460 
1464  private function checkBotReadOnly() {
1465  // Figure out how many servers have passed the lag threshold
1466  $numLagged = 0;
1467  $lagLimit = $this->getConfig()->get( 'APIMaxLagThreshold' );
1468  $laggedServers = [];
1469  $loadBalancer = MediaWikiServices::getInstance()->getDBLoadBalancer();
1470  foreach ( $loadBalancer->getLagTimes() as $serverIndex => $lag ) {
1471  if ( $lag > $lagLimit ) {
1472  ++$numLagged;
1473  $laggedServers[] = $loadBalancer->getServerName( $serverIndex ) . " ({$lag}s)";
1474  }
1475  }
1476 
1477  // If a majority of replica DBs are too lagged then disallow writes
1478  $replicaCount = $loadBalancer->getServerCount() - 1;
1479  if ( $numLagged >= ceil( $replicaCount / 2 ) ) {
1480  $laggedServers = implode( ', ', $laggedServers );
1481  wfDebugLog(
1482  'api-readonly', // Deprecate this channel in favor of api-warning?
1483  "Api request failed as read only because the following DBs are lagged: $laggedServers"
1484  );
1485  LoggerFactory::getInstance( 'api-warning' )->warning(
1486  "Api request failed as read only because the following DBs are lagged: {laggeddbs}", [
1487  'laggeddbs' => $laggedServers,
1488  ]
1489  );
1490 
1491  $this->dieWithError(
1492  'readonly_lag',
1493  'readonly',
1494  [ 'readonlyreason' => "Waiting for $numLagged lagged database(s)" ]
1495  );
1496  }
1497  }
1498 
1503  protected function checkAsserts( $params ) {
1504  if ( isset( $params['assert'] ) ) {
1505  $user = $this->getUser();
1506  switch ( $params['assert'] ) {
1507  case 'user':
1508  if ( $user->isAnon() ) {
1509  $this->dieWithError( 'apierror-assertuserfailed' );
1510  }
1511  break;
1512  case 'bot':
1513  if ( !$user->isAllowed( 'bot' ) ) {
1514  $this->dieWithError( 'apierror-assertbotfailed' );
1515  }
1516  break;
1517  }
1518  }
1519  if ( isset( $params['assertuser'] ) ) {
1520  $assertUser = User::newFromName( $params['assertuser'], false );
1521  if ( !$assertUser || !$this->getUser()->equals( $assertUser ) ) {
1522  $this->dieWithError(
1523  [ 'apierror-assertnameduserfailed', wfEscapeWikiText( $params['assertuser'] ) ]
1524  );
1525  }
1526  }
1527  }
1528 
1534  protected function setupExternalResponse( $module, $params ) {
1535  $validMethods = [ 'GET', 'HEAD', 'POST', 'OPTIONS' ];
1536  $request = $this->getRequest();
1537 
1538  if ( !in_array( $request->getMethod(), $validMethods ) ) {
1539  $this->dieWithError( 'apierror-invalidmethod', null, null, 405 );
1540  }
1541 
1542  if ( !$request->wasPosted() && $module->mustBePosted() ) {
1543  // Module requires POST. GET request might still be allowed
1544  // if $wgDebugApi is true, otherwise fail.
1545  $this->dieWithErrorOrDebug( [ 'apierror-mustbeposted', $this->mAction ] );
1546  }
1547 
1548  // See if custom printer is used
1549  $this->mPrinter = $module->getCustomPrinter();
1550  if ( is_null( $this->mPrinter ) ) {
1551  // Create an appropriate printer
1552  $this->mPrinter = $this->createPrinterByName( $params['format'] );
1553  }
1554 
1555  if ( $request->getProtocol() === 'http' && (
1556  $request->getSession()->shouldForceHTTPS() ||
1557  ( $this->getUser()->isLoggedIn() &&
1558  $this->getUser()->requiresHTTPS() )
1559  ) ) {
1560  $this->addDeprecation( 'apiwarn-deprecation-httpsexpected', 'https-expected' );
1561  }
1562  }
1563 
1567  protected function executeAction() {
1568  $params = $this->setupExecuteAction();
1569 
1570  // Check asserts early so e.g. errors in parsing a module's parameters due to being
1571  // logged out don't override the client's intended "am I logged in?" check.
1572  $this->checkAsserts( $params );
1573 
1574  $module = $this->setupModule();
1575  $this->mModule = $module;
1576 
1577  if ( !$this->mInternalMode ) {
1578  $this->setRequestExpectations( $module );
1579  }
1580 
1581  $this->checkExecutePermissions( $module );
1582 
1583  if ( !$this->checkMaxLag( $module, $params ) ) {
1584  return;
1585  }
1586 
1587  if ( !$this->checkConditionalRequestHeaders( $module ) ) {
1588  return;
1589  }
1590 
1591  if ( !$this->mInternalMode ) {
1592  $this->setupExternalResponse( $module, $params );
1593  }
1594 
1595  // Execute
1596  $module->execute();
1597  Hooks::run( 'APIAfterExecute', [ &$module ] );
1598 
1599  $this->reportUnusedParams();
1600 
1601  if ( !$this->mInternalMode ) {
1602  // append Debug information
1604 
1605  // Print result data
1606  $this->printResult();
1607  }
1608  }
1609 
1614  protected function setRequestExpectations( ApiBase $module ) {
1615  $limits = $this->getConfig()->get( 'TrxProfilerLimits' );
1616  $trxProfiler = Profiler::instance()->getTransactionProfiler();
1617  $trxProfiler->setLogger( LoggerFactory::getInstance( 'DBPerformance' ) );
1618  if ( $this->getRequest()->hasSafeMethod() ) {
1619  $trxProfiler->setExpectations( $limits['GET'], __METHOD__ );
1620  } elseif ( $this->getRequest()->wasPosted() && !$module->isWriteMode() ) {
1621  $trxProfiler->setExpectations( $limits['POST-nonwrite'], __METHOD__ );
1622  $this->getRequest()->markAsSafeRequest();
1623  } else {
1624  $trxProfiler->setExpectations( $limits['POST'], __METHOD__ );
1625  }
1626  }
1627 
1633  protected function logRequest( $time, $e = null ) {
1634  $request = $this->getRequest();
1635  $logCtx = [
1636  'ts' => time(),
1637  'ip' => $request->getIP(),
1638  'userAgent' => $this->getUserAgent(),
1639  'wiki' => wfWikiID(),
1640  'timeSpentBackend' => (int)round( $time * 1000 ),
1641  'hadError' => $e !== null,
1642  'errorCodes' => [],
1643  'params' => [],
1644  ];
1645 
1646  if ( $e ) {
1647  foreach ( $this->errorMessagesFromException( $e ) as $msg ) {
1648  $logCtx['errorCodes'][] = $msg->getApiCode();
1649  }
1650  }
1651 
1652  // Construct space separated message for 'api' log channel
1653  $msg = "API {$request->getMethod()} " .
1654  wfUrlencode( str_replace( ' ', '_', $this->getUser()->getName() ) ) .
1655  " {$logCtx['ip']} " .
1656  "T={$logCtx['timeSpentBackend']}ms";
1657 
1658  $sensitive = array_flip( $this->getSensitiveParams() );
1659  foreach ( $this->getParamsUsed() as $name ) {
1660  $value = $request->getVal( $name );
1661  if ( $value === null ) {
1662  continue;
1663  }
1664 
1665  if ( isset( $sensitive[$name] ) ) {
1666  $value = '[redacted]';
1667  $encValue = '[redacted]';
1668  } elseif ( strlen( $value ) > 256 ) {
1669  $value = substr( $value, 0, 256 );
1670  $encValue = $this->encodeRequestLogValue( $value ) . '[...]';
1671  } else {
1672  $encValue = $this->encodeRequestLogValue( $value );
1673  }
1674 
1675  $logCtx['params'][$name] = $value;
1676  $msg .= " {$name}={$encValue}";
1677  }
1678 
1679  wfDebugLog( 'api', $msg, 'private' );
1680  // ApiAction channel is for structured data consumers
1681  wfDebugLog( 'ApiAction', '', 'private', $logCtx );
1682  }
1683 
1689  protected function encodeRequestLogValue( $s ) {
1690  static $table;
1691  if ( !$table ) {
1692  $chars = ';@$!*(),/:';
1693  $numChars = strlen( $chars );
1694  for ( $i = 0; $i < $numChars; $i++ ) {
1695  $table[rawurlencode( $chars[$i] )] = $chars[$i];
1696  }
1697  }
1698 
1699  return strtr( rawurlencode( $s ), $table );
1700  }
1701 
1706  protected function getParamsUsed() {
1707  return array_keys( $this->mParamsUsed );
1708  }
1709 
1714  public function markParamsUsed( $params ) {
1715  $this->mParamsUsed += array_fill_keys( (array)$params, true );
1716  }
1717 
1723  protected function getSensitiveParams() {
1724  return array_keys( $this->mParamsSensitive );
1725  }
1726 
1732  public function markParamsSensitive( $params ) {
1733  $this->mParamsSensitive += array_fill_keys( (array)$params, true );
1734  }
1735 
1742  public function getVal( $name, $default = null ) {
1743  $this->mParamsUsed[$name] = true;
1744 
1745  $ret = $this->getRequest()->getVal( $name );
1746  if ( $ret === null ) {
1747  if ( $this->getRequest()->getArray( $name ) !== null ) {
1748  // See T12262 for why we don't just implode( '|', ... ) the
1749  // array.
1750  $this->addWarning( [ 'apiwarn-unsupportedarray', $name ] );
1751  }
1752  $ret = $default;
1753  }
1754  return $ret;
1755  }
1756 
1763  public function getCheck( $name ) {
1764  return $this->getVal( $name, null ) !== null;
1765  }
1766 
1774  public function getUpload( $name ) {
1775  $this->mParamsUsed[$name] = true;
1776 
1777  return $this->getRequest()->getUpload( $name );
1778  }
1779 
1784  protected function reportUnusedParams() {
1785  $paramsUsed = $this->getParamsUsed();
1786  $allParams = $this->getRequest()->getValueNames();
1787 
1788  if ( !$this->mInternalMode ) {
1789  // Printer has not yet executed; don't warn that its parameters are unused
1790  $printerParams = $this->mPrinter->encodeParamName(
1791  array_keys( $this->mPrinter->getFinalParams() ?: [] )
1792  );
1793  $unusedParams = array_diff( $allParams, $paramsUsed, $printerParams );
1794  } else {
1795  $unusedParams = array_diff( $allParams, $paramsUsed );
1796  }
1797 
1798  if ( count( $unusedParams ) ) {
1799  $this->addWarning( [
1800  'apierror-unrecognizedparams',
1801  Message::listParam( array_map( 'wfEscapeWikiText', $unusedParams ), 'comma' ),
1802  count( $unusedParams )
1803  ] );
1804  }
1805  }
1806 
1812  protected function printResult( $httpCode = 0 ) {
1813  if ( $this->getConfig()->get( 'DebugAPI' ) !== false ) {
1814  $this->addWarning( 'apiwarn-wgDebugAPI' );
1815  }
1816 
1817  $printer = $this->mPrinter;
1818  $printer->initPrinter( false );
1819  if ( $httpCode ) {
1820  $printer->setHttpStatus( $httpCode );
1821  }
1822  $printer->execute();
1823  $printer->closePrinter();
1824  }
1825 
1829  public function isReadMode() {
1830  return false;
1831  }
1832 
1838  public function getAllowedParams() {
1839  return [
1840  'action' => [
1841  ApiBase::PARAM_DFLT => 'help',
1842  ApiBase::PARAM_TYPE => 'submodule',
1843  ],
1844  'format' => [
1845  ApiBase::PARAM_DFLT => self::API_DEFAULT_FORMAT,
1846  ApiBase::PARAM_TYPE => 'submodule',
1847  ],
1848  'maxlag' => [
1849  ApiBase::PARAM_TYPE => 'integer'
1850  ],
1851  'smaxage' => [
1852  ApiBase::PARAM_TYPE => 'integer',
1853  ApiBase::PARAM_DFLT => 0
1854  ],
1855  'maxage' => [
1856  ApiBase::PARAM_TYPE => 'integer',
1857  ApiBase::PARAM_DFLT => 0
1858  ],
1859  'assert' => [
1860  ApiBase::PARAM_TYPE => [ 'user', 'bot' ]
1861  ],
1862  'assertuser' => [
1863  ApiBase::PARAM_TYPE => 'user',
1864  ],
1865  'requestid' => null,
1866  'servedby' => false,
1867  'curtimestamp' => false,
1868  'responselanginfo' => false,
1869  'origin' => null,
1870  'uselang' => [
1871  ApiBase::PARAM_DFLT => self::API_DEFAULT_USELANG,
1872  ],
1873  'errorformat' => [
1874  ApiBase::PARAM_TYPE => [ 'plaintext', 'wikitext', 'html', 'raw', 'none', 'bc' ],
1875  ApiBase::PARAM_DFLT => 'bc',
1876  ],
1877  'errorlang' => [
1878  ApiBase::PARAM_DFLT => 'uselang',
1879  ],
1880  'errorsuselocal' => [
1881  ApiBase::PARAM_DFLT => false,
1882  ],
1883  ];
1884  }
1885 
1887  protected function getExamplesMessages() {
1888  return [
1889  'action=help'
1890  => 'apihelp-help-example-main',
1891  'action=help&recursivesubmodules=1'
1892  => 'apihelp-help-example-recursive',
1893  ];
1894  }
1895 
1896  public function modifyHelp( array &$help, array $options, array &$tocData ) {
1897  // Wish PHP had an "array_insert_before". Instead, we have to manually
1898  // reindex the array to get 'permissions' in the right place.
1899  $oldHelp = $help;
1900  $help = [];
1901  foreach ( $oldHelp as $k => $v ) {
1902  if ( $k === 'submodules' ) {
1903  $help['permissions'] = '';
1904  }
1905  $help[$k] = $v;
1906  }
1907  $help['datatypes'] = '';
1908  $help['templatedparams'] = '';
1909  $help['credits'] = '';
1910 
1911  // Fill 'permissions'
1912  $help['permissions'] .= Html::openElement( 'div',
1913  [ 'class' => 'apihelp-block apihelp-permissions' ] );
1914  $m = $this->msg( 'api-help-permissions' );
1915  if ( !$m->isDisabled() ) {
1916  $help['permissions'] .= Html::rawElement( 'div', [ 'class' => 'apihelp-block-head' ],
1917  $m->numParams( count( self::$mRights ) )->parse()
1918  );
1919  }
1920  $help['permissions'] .= Html::openElement( 'dl' );
1921  foreach ( self::$mRights as $right => $rightMsg ) {
1922  $help['permissions'] .= Html::element( 'dt', null, $right );
1923 
1924  $rightMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )->parse();
1925  $help['permissions'] .= Html::rawElement( 'dd', null, $rightMsg );
1926 
1927  $groups = array_map( function ( $group ) {
1928  return $group == '*' ? 'all' : $group;
1929  }, User::getGroupsWithPermission( $right ) );
1930 
1931  $help['permissions'] .= Html::rawElement( 'dd', null,
1932  $this->msg( 'api-help-permissions-granted-to' )
1933  ->numParams( count( $groups ) )
1934  ->params( Message::listParam( $groups ) )
1935  ->parse()
1936  );
1937  }
1938  $help['permissions'] .= Html::closeElement( 'dl' );
1939  $help['permissions'] .= Html::closeElement( 'div' );
1940 
1941  // Fill 'datatypes', 'templatedparams', and 'credits', if applicable
1942  if ( empty( $options['nolead'] ) ) {
1943  $level = $options['headerlevel'];
1944  $tocnumber = &$options['tocnumber'];
1945 
1946  $header = $this->msg( 'api-help-datatypes-header' )->parse();
1947 
1948  $id = Sanitizer::escapeIdForAttribute( 'main/datatypes', Sanitizer::ID_PRIMARY );
1949  $idFallback = Sanitizer::escapeIdForAttribute( 'main/datatypes', Sanitizer::ID_FALLBACK );
1950  $headline = Linker::makeHeadline( min( 6, $level ),
1951  ' class="apihelp-header">',
1952  $id,
1953  $header,
1954  '',
1955  $idFallback
1956  );
1957  // Ensure we have a sane anchor
1958  if ( $id !== 'main/datatypes' && $idFallback !== 'main/datatypes' ) {
1959  $headline = '<div id="main/datatypes"></div>' . $headline;
1960  }
1961  $help['datatypes'] .= $headline;
1962  $help['datatypes'] .= $this->msg( 'api-help-datatypes' )->parseAsBlock();
1963  if ( !isset( $tocData['main/datatypes'] ) ) {
1964  $tocnumber[$level]++;
1965  $tocData['main/datatypes'] = [
1966  'toclevel' => count( $tocnumber ),
1967  'level' => $level,
1968  'anchor' => 'main/datatypes',
1969  'line' => $header,
1970  'number' => implode( '.', $tocnumber ),
1971  'index' => false,
1972  ];
1973  }
1974 
1975  $header = $this->msg( 'api-help-templatedparams-header' )->parse();
1976 
1977  $id = Sanitizer::escapeIdForAttribute( 'main/templatedparams', Sanitizer::ID_PRIMARY );
1978  $idFallback = Sanitizer::escapeIdForAttribute( 'main/templatedparams', Sanitizer::ID_FALLBACK );
1979  $headline = Linker::makeHeadline( min( 6, $level ),
1980  ' class="apihelp-header">',
1981  $id,
1982  $header,
1983  '',
1984  $idFallback
1985  );
1986  // Ensure we have a sane anchor
1987  if ( $id !== 'main/templatedparams' && $idFallback !== 'main/templatedparams' ) {
1988  $headline = '<div id="main/templatedparams"></div>' . $headline;
1989  }
1990  $help['templatedparams'] .= $headline;
1991  $help['templatedparams'] .= $this->msg( 'api-help-templatedparams' )->parseAsBlock();
1992  if ( !isset( $tocData['main/templatedparams'] ) ) {
1993  $tocnumber[$level]++;
1994  $tocData['main/templatedparams'] = [
1995  'toclevel' => count( $tocnumber ),
1996  'level' => $level,
1997  'anchor' => 'main/templatedparams',
1998  'line' => $header,
1999  'number' => implode( '.', $tocnumber ),
2000  'index' => false,
2001  ];
2002  }
2003 
2004  $header = $this->msg( 'api-credits-header' )->parse();
2005  $id = Sanitizer::escapeIdForAttribute( 'main/credits', Sanitizer::ID_PRIMARY );
2006  $idFallback = Sanitizer::escapeIdForAttribute( 'main/credits', Sanitizer::ID_FALLBACK );
2007  $headline = Linker::makeHeadline( min( 6, $level ),
2008  ' class="apihelp-header">',
2009  $id,
2010  $header,
2011  '',
2012  $idFallback
2013  );
2014  // Ensure we have a sane anchor
2015  if ( $id !== 'main/credits' && $idFallback !== 'main/credits' ) {
2016  $headline = '<div id="main/credits"></div>' . $headline;
2017  }
2018  $help['credits'] .= $headline;
2019  $help['credits'] .= $this->msg( 'api-credits' )->useDatabase( false )->parseAsBlock();
2020  if ( !isset( $tocData['main/credits'] ) ) {
2021  $tocnumber[$level]++;
2022  $tocData['main/credits'] = [
2023  'toclevel' => count( $tocnumber ),
2024  'level' => $level,
2025  'anchor' => 'main/credits',
2026  'line' => $header,
2027  'number' => implode( '.', $tocnumber ),
2028  'index' => false,
2029  ];
2030  }
2031  }
2032  }
2033 
2035 
2040  public function canApiHighLimits() {
2041  if ( !isset( $this->mCanApiHighLimits ) ) {
2042  $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
2043  }
2044 
2045  return $this->mCanApiHighLimits;
2046  }
2047 
2052  public function getModuleManager() {
2053  return $this->mModuleMgr;
2054  }
2055 
2064  public function getUserAgent() {
2065  return trim(
2066  $this->getRequest()->getHeader( 'Api-user-agent' ) . ' ' .
2067  $this->getRequest()->getHeader( 'User-agent' )
2068  );
2069  }
2070 }
2071 
The wiki should then use memcached to cache various data To use multiple just add more items to the array To increase the weight of a make its entry a array("192.168.0.1:11211", 2))
setContext(IContextSource $context)
getAllowedParams()
See ApiBase for description.
Definition: ApiMain.php:1838
getModuleManager()
Overrides to return this instance&#39;s module manager.
Definition: ApiMain.php:2052
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below...
Definition: ApiBase.php:88
static matchRequestedHeaders( $requestedHeaders)
Attempt to validate the value of Access-Control-Request-Headers against a list of headers that we all...
Definition: ApiMain.php:816
getUserAgent()
Fetches the user agent used for this request.
Definition: ApiMain.php:2064
const LIMIT_BIG2
Fast query, apihighlimits limit.
Definition: ApiBase.php:255
wfEscapeWikiText( $text)
Escapes the given text so that it may be output using addWikiText() without any linking, formatting, etc.
setCacheMaxAge( $maxage)
Set how long the response should be cached.
Definition: ApiMain.php:400
getContinuationManager()
Get the continuation manager.
Definition: ApiMain.php:359
static $Modules
List of available modules: action name => module class.
Definition: ApiMain.php:55
$mEnableWrite
Definition: ApiMain.php:150
static element( $element, $attribs=[], $contents='')
Identical to rawElement(), but HTML-escapes $contents (like Xml::element()).
Definition: Html.php:232
Formats errors and warnings for the API, and add them to the associated ApiResult.
addRequestedFields( $force=[])
Add requested fields to the result.
Definition: ApiMain.php:1146
static getRequestId()
Get the unique request ID.
Definition: WebRequest.php:275
executeActionWithErrorHandling()
Execute an action, and in case of an error, erase whatever partial results have been accumulated...
Definition: ApiMain.php:510
modifyHelp(array &$help, array $options, array &$tocData)
Definition: ApiMain.php:1896
processing should stop and the error should be shown to the user * false
Definition: hooks.txt:187
const ID_PRIMARY
Tells escapeUrlForHtml() to encode the ID using the wiki&#39;s primary encoding.
Definition: Sanitizer.php:66
This class holds a list of modules and handles instantiation.
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses & $ret
Definition: hooks.txt:1995
bool null $lacksSameOriginSecurity
Cached return value from self::lacksSameOriginSecurity()
Definition: ApiMain.php:161
static isEveryoneAllowed( $right)
Check if all users may be assumed to have the given permission.
Definition: User.php:5084
Apache License January AND DISTRIBUTION Definitions License shall mean the terms and conditions for use
addDeprecation( $msg, $feature, $data=[])
Add a deprecation warning for this module.
Definition: ApiBase.php:1920
initPrinter( $unused=false)
Initialize the printer function and prepare the output headers.
div flags Integer display flags(NO_ACTION_LINK, NO_EXTRA_USER_LINKS) 'LogException' returning false will NOT prevent logging $e
Definition: hooks.txt:2172
checkExecutePermissions( $module)
Check for sufficient permissions to execute.
Definition: ApiMain.php:1417
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition: ApiBase.php:49
static instance()
Singleton.
Definition: Profiler.php:62
wfExpandUrl( $url, $defaultProto=PROTO_CURRENT)
Expand a potentially local URL to a fully-qualified URL.
getMaxLag()
Definition: ApiMain.php:1239
wfHostname()
Fetch server name for use in error reporting etc.
Exception used to abort API execution with an error.
$mCacheControl
Definition: ApiMain.php:156
static openElement( $element, $attribs=[])
Identical to rawElement(), but has no third parameter and omits the end tag (and the self-closing &#39;/&#39;...
Definition: Html.php:252
static rawElement( $element, $attribs=[], $contents='')
Returns an HTML element in a string.
Definition: Html.php:210
An IContextSource implementation which will inherit context from another source but allow individual ...
static static static ApiFormatBase $mPrinter
Definition: ApiMain.php:133
checkReadOnly( $module)
Check if the DB is read-only for this user.
Definition: ApiMain.php:1448
static isValidApiCode( $code)
Test whether a code is a valid API error code.
This manages continuation state.
isInternalMode()
Return true if the API was started by other PHP code using FauxRequest.
Definition: ApiMain.php:299
$value
setCacheControl( $directives)
Set directives (key/value pairs) for the Cache-Control header.
Definition: ApiMain.php:473
dieWithError( $msg, $code=null, $data=null, $httpCode=null)
Abort execution with an error.
Definition: ApiBase.php:1987
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user...
Definition: ApiBase.php:744
static preOutputCommit(IContextSource $context, callable $postCommitWork=null)
This function commits all DB and session changes as needed before the client can receive a response (...
Definition: MediaWiki.php:582
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency MediaWikiServices
Definition: injection.txt:23
const GETHEADER_LIST
Flag to make WebRequest::getHeader return an array of values.
Definition: WebRequest.php:48
msg( $key)
Get a Message object with context set Parameters are the same as wfMessage()
canApiHighLimits()
Check whether the current user is allowed to use high limits.
Definition: ApiMain.php:2040
errorMessagesFromException( $e, $type='error')
Create an error message for the given exception.
Definition: ApiMain.php:1022
static rollbackMasterChangesAndLog( $e)
Roll back any open database transactions and log the stack trace of the exception.
A helper class for throttling authentication attempts.
this hook is for auditing only $response
Definition: hooks.txt:780
const API_DEFAULT_FORMAT
When no format parameter is given, this format will be used.
Definition: ApiMain.php:45
see documentation in includes Linker php for Linker::makeImageLink & $time
Definition: hooks.txt:1812
IContextSource $context
This list may contain false positives That usually means there is additional text with links below the first Each row contains links to the first and second as well as the first line of the second redirect text
ApiBase $mModule
Definition: ApiMain.php:153
static static static $mRights
List of user roles that are specifically relevant to the API.
Definition: ApiMain.php:130
getParameter( $paramName, $parseLimit=true)
Get a value for the given parameter.
Definition: ApiBase.php:858
The index of the header message $result[1]=The index of the body text message $result[2 through n]=Parameters passed to body text message. Please note the header message cannot receive/use parameters. 'ImportHandleLogItemXMLTag':When parsing a XML tag in a log item. Return false to stop further processing of the tag $reader:XMLReader object $logInfo:Array of information 'ImportHandlePageXMLTag':When parsing a XML tag in a page. Return false to stop further processing of the tag $reader:XMLReader object & $pageInfo:Array of information 'ImportHandleRevisionXMLTag':When parsing a XML tag in a page revision. Return false to stop further processing of the tag $reader:XMLReader object $pageInfo:Array of page information $revisionInfo:Array of revision information 'ImportHandleToplevelXMLTag':When parsing a top level XML tag. Return false to stop further processing of the tag $reader:XMLReader object 'ImportHandleUnknownUser':When a user doesn 't exist locally, this hook is called to give extensions an opportunity to auto-create it. If the auto-creation is successful, return false. $name:User name 'ImportHandleUploadXMLTag':When parsing a XML tag in a file upload. Return false to stop further processing of the tag $reader:XMLReader object $revisionInfo:Array of information 'ImportLogInterwikiLink':Hook to change the interwiki link used in log entries and edit summaries for transwiki imports. & $fullInterwikiPrefix:Interwiki prefix, may contain colons. & $pageTitle:String that contains page title. 'ImportSources':Called when reading from the $wgImportSources configuration variable. Can be used to lazy-load the import sources list. & $importSources:The value of $wgImportSources. Modify as necessary. See the comment in DefaultSettings.php for the detail of how to structure this array. 'InfoAction':When building information to display on the action=info page. $context:IContextSource object & $pageInfo:Array of information 'InitializeArticleMaybeRedirect':MediaWiki check to see if title is a redirect. & $title:Title object for the current page & $request:WebRequest & $ignoreRedirect:boolean to skip redirect check & $target:Title/string of redirect target & $article:Article object 'InternalParseBeforeLinks':during Parser 's internalParse method before links but after nowiki/noinclude/includeonly/onlyinclude and other processings. & $parser:Parser object & $text:string containing partially parsed text & $stripState:Parser 's internal StripState object 'InternalParseBeforeSanitize':during Parser 's internalParse method just before the parser removes unwanted/dangerous HTML tags and after nowiki/noinclude/includeonly/onlyinclude and other processings. Ideal for syntax-extensions after template/parser function execution which respect nowiki and HTML-comments. & $parser:Parser object & $text:string containing partially parsed text & $stripState:Parser 's internal StripState object 'InterwikiLoadPrefix':When resolving if a given prefix is an interwiki or not. Return true without providing an interwiki to continue interwiki search. $prefix:interwiki prefix we are looking for. & $iwData:output array describing the interwiki with keys iw_url, iw_local, iw_trans and optionally iw_api and iw_wikiid. 'InvalidateEmailComplete':Called after a user 's email has been invalidated successfully. $user:user(object) whose email is being invalidated 'IRCLineURL':When constructing the URL to use in an IRC notification. Callee may modify $url and $query, URL will be constructed as $url . $query & $url:URL to index.php & $query:Query string $rc:RecentChange object that triggered url generation 'IsFileCacheable':Override the result of Article::isFileCacheable()(if true) & $article:article(object) being checked 'IsTrustedProxy':Override the result of IP::isTrustedProxy() & $ip:IP being check & $result:Change this value to override the result of IP::isTrustedProxy() 'IsUploadAllowedFromUrl':Override the result of UploadFromUrl::isAllowedUrl() $url:URL used to upload from & $allowed:Boolean indicating if uploading is allowed for given URL 'isValidEmailAddr':Override the result of Sanitizer::validateEmail(), for instance to return false if the domain name doesn 't match your organization. $addr:The e-mail address entered by the user & $result:Set this and return false to override the internal checks 'isValidPassword':Override the result of User::isValidPassword() $password:The password entered by the user & $result:Set this and return false to override the internal checks $user:User the password is being validated for 'Language::getMessagesFileName':$code:The language code or the language we 're looking for a messages file for & $file:The messages file path, you can override this to change the location. 'LanguageGetNamespaces':Provide custom ordering for namespaces or remove namespaces. Do not use this hook to add namespaces. Use CanonicalNamespaces for that. & $namespaces:Array of namespaces indexed by their numbers 'LanguageGetTranslatedLanguageNames':Provide translated language names. & $names:array of language code=> language name $code:language of the preferred translations 'LanguageLinks':Manipulate a page 's language links. This is called in various places to allow extensions to define the effective language links for a page. $title:The page 's Title. & $links:Array with elements of the form "language:title" in the order that they will be output. & $linkFlags:Associative array mapping prefixed links to arrays of flags. Currently unused, but planned to provide support for marking individual language links in the UI, e.g. for featured articles. 'LanguageSelector':Hook to change the language selector available on a page. $out:The output page. $cssClassName:CSS class name of the language selector. 'LinkBegin':DEPRECATED since 1.28! Use HtmlPageLinkRendererBegin instead. Used when generating internal and interwiki links in Linker::link(), before processing starts. Return false to skip default processing and return $ret. See documentation for Linker::link() for details on the expected meanings of parameters. $skin:the Skin object $target:the Title that the link is pointing to & $html:the contents that the< a > tag should have(raw HTML) $result
Definition: hooks.txt:1993
setupModule()
Set up the module for response.
Definition: ApiMain.php:1192
__construct( $context=null, $enableWrite=false)
Constructs an instance of ApiMain that utilizes the module and format specified by $request...
Definition: ApiMain.php:170
const ID_FALLBACK
Tells escapeUrlForHtml() to encode the ID using the fallback encoding, or return false if no fallback...
Definition: Sanitizer.php:74
usually copyright or history_copyright This message must be in HTML not wikitext & $link
Definition: hooks.txt:3042
wfScript( $script='index')
Get the path to a specified script file, respecting file extensions; this is a wrapper around $wgScri...
const API_DEFAULT_USELANG
When no uselang parameter is given, this language will be used.
Definition: ApiMain.php:50
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses just before the function returns a value If you return true
Definition: hooks.txt:1995
checkMaxLag( $module, $params)
Check the max lag if necessary.
Definition: ApiMain.php:1273
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
createPrinterByName( $format)
Create an instance of an output formatter by its name.
Definition: ApiMain.php:484
setRequestExpectations(ApiBase $module)
Set database connection, query, and write expectations given this module request. ...
Definition: ApiMain.php:1614
setupExternalResponse( $module, $params)
Check POST for external response and setup result printer.
Definition: ApiMain.php:1534
wfReadOnly()
Check whether the wiki is in read-only mode.
wfUrlencode( $s)
We want some things to be included as literal characters in our title URLs for prettiness, which urlencode encodes by default.
$wgLang
Definition: Setup.php:891
printResult( $httpCode=0)
Print results using the current printer.
Definition: ApiMain.php:1812
static getMain()
Get the RequestContext object associated with the main request.
static getRedactedTraceAsString( $e)
Generate a string representation of an exception&#39;s stack trace.
static getGroupsWithPermission( $role)
Get all the groups who have a given permission.
Definition: User.php:5041
setCacheMode( $mode)
Set the type of caching headers which will be sent.
Definition: ApiMain.php:432
static escapeIdForAttribute( $id, $mode=self::ID_PRIMARY)
Given a section name or other user-generated or otherwise unsafe string, escapes it to be a valid HTM...
Definition: Sanitizer.php:1289
checkAsserts( $params)
Check asserts of the user&#39;s rights.
Definition: ApiMain.php:1503
wfDebug( $text, $dest='all', array $context=[])
Sends a line to the debug log if enabled or, optionally, to a comment in output.
handleException( $e)
Handle an exception as an API response.
Definition: ApiMain.php:567
const LIMIT_SML2
Slow query, apihighlimits limit.
Definition: ApiBase.php:259
getContext()
Get the base IContextSource object.
$params
This is the main API class, used for both external and internal processing.
Definition: ApiMain.php:41
executeAction()
Execute the actual module, without any error handling.
Definition: ApiMain.php:1567
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped & $options
Definition: hooks.txt:1995
isReadMode()
Definition: ApiMain.php:1829
static closeElement( $element)
Returns "</$element>".
Definition: Html.php:316
handleCORS()
Check the &origin= query parameter against the Origin: HTTP header and respond appropriately.
Definition: ApiMain.php:672
setupExecuteAction()
Set up for the execution.
Definition: ApiMain.php:1177
getSensitiveParams()
Get the request parameters that should be considered sensitive.
Definition: ApiMain.php:1723
$mCacheMode
Definition: ApiMain.php:155
Format errors and warnings in the old style, for backwards compatibility.
$mErrorFormatter
Definition: ApiMain.php:146
this hook is for auditing only or null if authentication failed before getting that far or null if we can t even determine that When $user is not null
Definition: hooks.txt:780
lacksSameOriginSecurity()
Get the security flag for the current request.
Definition: ApiMain.php:316
static runWithoutAbort( $event, array $args=[], $deprecatedVersion=null)
Call hook functions defined in Hooks::register and $wgHooks.
Definition: Hooks.php:231
static wildcardToRegex( $wildcard)
Helper function to convert wildcard string into a regex &#39;*&#39; => &#39;.
Definition: ApiMain.php:857
const NO_SIZE_CHECK
For addValue() and similar functions, do not check size while adding a value Don&#39;t use this unless yo...
Definition: ApiResult.php:58
static factory( $code)
Get a cached or new language object for a given language code.
Definition: Language.php:214
This class represents the result of the API operations.
Definition: ApiResult.php:35
markParamsSensitive( $params)
Mark parameters as sensitive.
Definition: ApiMain.php:1732
$help
Definition: mcc.php:32
wfWikiID()
Get an ASCII string identifying this wiki This is used as a prefix in memcached keys.
$mParamsSensitive
Definition: ApiMain.php:158
$header
$mCanApiHighLimits
Definition: ApiMain.php:2034
this hook is for auditing only or null if authentication failed before getting that far or null if we can t even determine that When $user is not it can be in the form of< username >< more info > e g for bot passwords intended to be added to log contexts Fields it might only if the login was with a bot password probably a stub it is not rendered in wiki pages or galleries in category pages allow injecting custom HTML after the section Any uses of the hook need to handle escaping see BaseTemplate::getToolbox and BaseTemplate::makeListItem for details on the format of individual items inside of this array or by returning and letting standard HTTP rendering take place modifiable or by returning false and taking over the output modifiable & $code
Definition: hooks.txt:780
This document is intended to provide useful advice for parties seeking to redistribute MediaWiki to end users It s targeted particularly at maintainers for Linux since it s been observed that distribution packages of MediaWiki often break We ve consistently had to recommend that users seeking support use official tarballs instead of their distribution s and this often solves whatever problem the user is having It would be nice if this could such as
Definition: distributors.txt:9
static static $Formats
List of available formats: format name => format class.
Definition: ApiMain.php:113
getParamsUsed()
Get the request parameters used in the course of the preceding execute() request. ...
Definition: ApiMain.php:1706
getExamplesMessages()
Definition: ApiMain.php:1887
getErrorFormatter()
Get the ApiErrorFormatter object associated with current request.
Definition: ApiMain.php:351
getCheck( $name)
Get a boolean request value, and register the fact that the parameter was used, for logging...
Definition: ApiMain.php:1763
logRequest( $time, $e=null)
Log the preceding request.
Definition: ApiMain.php:1633
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency which acts as the top level factory for services in MediaWiki which can be used to gain access to default instances of various services MediaWikiServices however also allows new services to be defined and default services to be redefined Services are defined or redefined by providing a callback the instantiator that will return a new instance of the service When it will create an instance of MediaWikiServices and populate it with the services defined in the files listed by thereby bootstrapping the DI framework Per $wgServiceWiringFiles lists includes ServiceWiring php
Definition: injection.txt:35
sendCacheHeaders( $isError)
Send caching headers.
Definition: ApiMain.php:873
checkBotReadOnly()
Check whether we are readonly for bots.
Definition: ApiMain.php:1464
getModule()
Get the API module object.
Definition: ApiMain.php:382
this hook is for auditing only or null if authentication failed before getting that far or null if we can t even determine that When $user is not it can be in the form of< username >< more info > e g for bot passwords intended to be added to log contexts Fields it might only if the login was with a bot password probably a stub it is not rendered in wiki pages or galleries in category pages allow injecting custom HTML after the section Any uses of the hook need to handle escaping see BaseTemplate::getToolbox and BaseTemplate::makeListItem for details on the format of individual items inside of this array or by returning and letting standard HTTP rendering take place modifiable or by returning false and taking over the output $out
Definition: hooks.txt:780
checkConditionalRequestHeaders( $module)
Check selected RFC 7232 precondition headers.
Definition: ApiMain.php:1319
static makeHeadline( $level, $attribs, $anchor, $html, $link, $fallbackAnchor=false)
Create a headline for content.
Definition: Linker.php:1683
dieWithErrorOrDebug( $msg, $code=null, $data=null, $httpCode=null)
Will only set a warning instead of failing if the global $wgDebugAPI is set to true.
Definition: ApiBase.php:2185
static appendDebugInfoToApiResult(IContextSource $context, ApiResult $result)
Append the debug info to given ApiResult.
Definition: MWDebug.php:481
dieReadOnly()
Helper function for readonly errors.
Definition: ApiBase.php:2086
static newFromSpecifier( $value)
Transform a MessageSpecifier or a primitive value used interchangeably with specifiers (a message key...
Definition: Message.php:427
you have access to all of the normal MediaWiki so you can get a DB use the etc For full docs on the Maintenance class
Definition: maintenance.txt:52
wfDebugLog( $logGroup, $text, $dest='all', array $context=[])
Send a line to a supplementary debug log file, if configured, or main debug log if not...
$mSquidMaxage
Definition: ApiMain.php:151
$mParamsUsed
Definition: ApiMain.php:157
addWarning( $msg, $code=null, $data=null)
Add a warning for this module.
Definition: ApiBase.php:1906
static sanitizeLangCode( $code)
Accepts a language code and ensures it&#39;s sane.
static handleApiBeforeMainException( $e)
Handle an exception from the ApiBeforeMain hook.
Definition: ApiMain.php:637
reportUnusedParams()
Report unused parameters, so the client gets a hint in case it gave us parameters we don&#39;t know...
Definition: ApiMain.php:1784
wfClearOutputBuffers()
More legible than passing a &#39;false&#39; parameter to wfResetOutputBuffers():
MediaWiki Logger LoggerFactory implements a PSR [0] compatible message logging system Named Psr Log LoggerInterface instances can be obtained from the MediaWiki Logger LoggerFactory::getInstance() static method. MediaWiki\Logger\LoggerFactory expects a class implementing the MediaWiki\Logger\Spi interface to act as a factory for new Psr\Log\LoggerInterface instances. The "Spi" in MediaWiki\Logger\Spi stands for "service provider interface". An SPI is an API intended to be implemented or extended by a third party. This software design pattern is intended to enable framework extension and replaceable components. It is specifically used in the MediaWiki\Logger\LoggerFactory service to allow alternate PSR-3 logging implementations to be easily integrated with MediaWiki. The service provider interface allows the backend logging library to be implemented in multiple ways. The $wgMWLoggerDefaultSpi global provides the classname of the default MediaWiki\Logger\Spi implementation to be loaded at runtime. This can either be the name of a class implementing the MediaWiki\Logger\Spi with a zero argument const ructor or a callable that will return an MediaWiki\Logger\Spi instance. Alternately the MediaWiki\Logger\LoggerFactory MediaWiki Logger LoggerFactory
Definition: logger.txt:5
This abstract class implements many basic API functions, and is the base of all API classes...
Definition: ApiBase.php:38
static singleton( $domain=false)
substituteResultWithError( $e)
Replace the result data with the information about an exception.
Definition: ApiMain.php:1060
Allows to change the fields on the form that will be generated $name
Definition: hooks.txt:271
getPrinter()
Get the result formatter object.
Definition: ApiMain.php:391
$messages
getStatusValue()
Fetch the error status.
static newFromName( $name, $validate='valid')
Static factory method for creation from username.
Definition: User.php:584
markParamsUsed( $params)
Mark parameters as used.
Definition: ApiMain.php:1714
getUpload( $name)
Get a request upload, and register the fact that it was used, for logging.
Definition: ApiMain.php:1774
setContinuationManager(ApiContinuationManager $manager=null)
Set the continuation manager.
Definition: ApiMain.php:367
do that in ParserLimitReportFormat instead use this to modify the parameters of the image all existing parser cache entries will be invalid To avoid you ll need to handle that somehow(e.g. with the RejectParserCacheValue hook) because MediaWiki won 't do it for you. & $defaults also a ContextSource after deleting those rows but within the same transaction you ll probably need to make sure the header is varied on $request
Definition: hooks.txt:2625
$mInternalMode
Definition: ApiMain.php:151
Interface for MediaWiki-localized exceptions.
$mModuleMgr
Definition: ApiMain.php:146
encodeRequestLogValue( $s)
Encode a value in a format suitable for a space-separated log line.
Definition: ApiMain.php:1689
execute()
Execute api request.
Definition: ApiMain.php:498
return true to allow those checks to and false if checking is done & $user
Definition: hooks.txt:1486
static listParam(array $list, $type='text')
Definition: Message.php:1126
static run( $event, array $args=[], $deprecatedVersion=null)
Call hook functions defined in Hooks::register and $wgHooks.
Definition: Hooks.php:200
static matchOrigin( $value, $rules, $exceptions)
Attempt to match an Origin header against a set of rules and a set of exceptions. ...
Definition: ApiMain.php:792
static create( $msg, $code=null, array $data=null)
Create an IApiMessage for the message.
Definition: ApiMessage.php:40
getResult()
Get the ApiResult object associated with current request.
Definition: ApiMain.php:308
createErrorPrinter()
Create the printer for error output.
Definition: ApiMain.php:991
isWriteMode()
Indicates whether this module requires write mode.
Definition: ApiBase.php:420
ApiContinuationManager null $mContinuationManager
Definition: ApiMain.php:148
getVal( $name, $default=null)
Get a request value, and register the fact that it was used, for logging.
Definition: ApiMain.php:1742