Manual:RequestContext.php

From mediawiki.org
(Redirected from Manual:RequestContext)
MediaWiki version:
1.18

As of MediaWiki 1.18 the context of a request is encapsulated inside of a RequestContext instance which implements the IContextSource interface. Extensions should call getContext() and then getSomeObject() rather than rely on global state variables.

Accessors[edit]

A RequestContext or IContextSource provides the following accessor methods:

  • $context->getRequest() - the WebRequest instance to fetch request variables from.
  • $context->getTitle() - the Title instance for the page being outputted.
  • $context->getOutput() - a OutputPage instance tied to the RequestContext for sending page output to.
  • $context->getSkin() - the Skin class instance being used to render the page.
  • $context->getUser() - the instance of User for the user the page is rendered for.
  • $context->getLanguage() - (added in 1.19 to replace the now deprecated $context->getLang()) the Language instance of the user language the page is rendered in.
  • $context->getWikiPage() (introduced in 1.19) - the WikiPage instance being outputted (but see below).
  • $context->canUseWikiPage() (introduced in 1.19) - checks whether getWikiPage() can be called, or it will throw an exception.
  • $context->msg() - returns a Message object with context set to the context being called. It has the same parameters as wfMessage() .
  • $context->getConfig() (introduced in 1.23) - the main Config object

The output and language are read-only, the rest of the RequestContext may be set using methods such as $context->setTitle( Title::newMainPage() )).

Working with Request Contexts[edit]

You can access the main request context using RequestContext::getMain(); however this should be a last resort. Most places where you need to do something with request context data should provide access to an IContextData source and you should use that, not the main RequestContext instance or $wg globals.

When writing a SpecialPage[edit]

  • You have access to the context through $this->getContext();
  • SpecialPage also implements a number of helpers:
    • $this->getRequest()
    • $this->getOutput()
    • $this->getUser()
    • $this->getAuthority()
    • $this->getSkin()
    • $this->getLanguage()
    • $this->getConfig()
    • $this->getFullTitle() You can use $this->getPageTitle(); for the title of the SpecialPage and $this->getFullTitle(); for the title of the special page and any $par data.
  • SpecialPages are meant to be executable in alternate contexts so extensions should start moving away from the use of $wg's. We may drop support for includable special pages using $wg request context related variables around MW 1.20.

When writing skin code[edit]

  • You have access to the context through $this->getContext();
  • Skin also implements a number of helpers:
    • $this->getUser()
    • $this->getTitle()
  • The skin context is entered by Skin::outputPage( $out ); which is called by OutputPage::output(); external access to context sensitive method calls should be avoided.

When using hooks[edit]

  • If your hook provides an OutputPage as an argument make use of the context provided by it.
  • If your hook is executed within the Skin::outputPage( $out ); page outputting context, and is provided a Skin instance, make use of the context provided by it.
  • If your hook provides a Title instance, use it as a preference to other context.
  • Same goes for any WebRequest instances provided as arguments to hooks.
  • Make sure you are using the right hook, if proper context is not provided then you may be using a hook for the wrong purpose and may run into unrelated bugs.
  • However some hooks may be out of date and need to be provided with a proper context inside of their arguments.

When writing parser functions and hooks[edit]

  • Parser functions and hooks should not be accessing request context data. Other contextual information can be accessed from the local parser object.
    For example: $parser->getOutput()->addModules( 'ext.my.module' );
  • Make use of the ParserOptions for anything you do need like the user lang.
  • Use the Linker:: class statically instead of accessing the Skin.
  • If you need to add something to the page output outside of the content area the ParserOutput should have methods that allow you to do what you want.
    • If the methods in ParserOutput aren't flexible enough for what you need to do it's possible to register a callback with the ParserOutput that will be called later in a place you can freely make use of the request context.

Creating new Request Contexts[edit]

There is still code using the global $wgOut , $wgTitle , $wgUser variables. Until those are eliminated we cannot expect custom contexts to work perfectly and will need to keep the same workarounds, however if we fix code to stop using those globals then something like this should be possible:

$context = new RequestContext();
$context->setRequest( new FauxRequest( [...] ) );
$context->setTitle( Title::newFromText( [...] ) );
$context->setUser( User::newFromName( 'Dantman' ) );
$context->setSkin( new OfflineDummySkin() );

// [...]
$html = $context->getOutput()->capture();

Using a DerivativeContext[edit]

MediaWiki version:
1.19

MediaWiki 1.19 added a DerivativeContext class. DerivativeContext is useful if you want to give a context to something which is based on the context you're in but slightly different. For example a context which has all the current context, but a different Title.

$newContext = new DerivativeContext( $currentContext );
$newContext->setTitle( Title::newFromText( 'Asdf' ) );

When designing a class api it is preferable to just use a context source and not require a separate title (or by extension WikiPage) as an argument. As the calling api would be better off making use of a DerivativeContext if it needs to pass a different context to your class api.

Using IContextSource and ContextSource[edit]

The base of a RequestContext is the IContextSource interface. It defines the API of something from which you can get pieces of request context. If you are writing an API which uses type hinting in the arguments or makes instanceof checks you should check for IContextSoure, NOT for RequestContext.

if ( $arg instanceof IContextSource ) {
  // Treat $arg as a context object
}
function foo( IContextSource $context ) {
  // Use $context as the request context
}

Additionally we provide a ContextSource helper class. By making your class extend ContextSource your class will be provided with the various getOutput, getSkin, getLanguage, etc... helpers directly and will implements IContextSource. However unfortunately because we cannot use traits[1] yet if you need to make your class extend from another class you will have to implements IContextSource and implement the helper boilerplate directly in the class.

From a ContextSource class you can use setContext to set the context your class is in. For example a constructor that requires a context can be written like so:

class SomeClass extends ContextSource {
  public function __constructor( IContextSource $context ) {
    $this->setContext( $context );
  }
}

Again if you can't extend ContextSource you'll have to write the helper boilerplate into your class directly. As we unfortunately can't use traits[1] to allow something like this:

class SomeClass extends SomeOtherClass implements IContextSource {
  use TContextSource;
  public function __constructor( IContextSource $context ) {
    $this->setContext( $context );
  }
}

Backwards compatibility in extensions[edit]

Using the linker alone[edit]

If your extension needs 1.18 compat and you want to use linker methods this trick can get you a linker instance you can use:

$linker = class_exists( 'DummyLinker' ) ? new DummyLinker() : new Linker();

Now instead of using a skin instance to access the linker just use $linker->, and you'll be able to update to Linker:: when you drop pre-1.18 compatibility.

References[edit]

  1. 1.0 1.1 Traits have appeared with PHP 5.4 and allow to reduce limitations of PHP single inheritance by allowing you to declare methods (abstract too) with their access modifier (public, private, protected) you can use in several classes.