Manual:RequestContext.php
| Arquivo MediaWiki: RequestContext.php | |
|---|---|
| Local: | includes/context/ |
| Código fonte: | master • 1.42.4 • 1.41.5 • 1.39.11 |
| Classes: | MediaWiki\Context\RequestContext |
| Versão MediaWiki: | ≥ 1.18 |
The RequestContext class is used to encapsulate all the pieces that are relevant to the context of a request. It implements the IContextSource and MutableContext interfaces.
Extensions should call getContext() and then getSomeObject() rather than rely on global state variables.
Access a RequestContext
Most places where you need to do something with RequestContext data should provide access to an IContextData source (?) and you should use that, not the main RequestContext instance or $wg globals.
You can also access the main request context using RequestContext::getMain(); however this should be a last resort.
When writing a SpecialPage
When writing a SpecialPage, you have access to the context through $this->getContext();
SpecialPage also implements a number of helper methods that are the equivalent of methods provided by RequestContext, for which see below.
SpecialPages are meant to be executable in alternate contexts, extensions should start moving away from the use of $wg's.
We may drop support for includable special pages using $wg RequestContext related variables around MW 1.20.
When writing skin code
You have access to the context through $this->getContext();.
Skin similarly provides a few helper methods, for which see below.
When using hooks
- 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
- 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
RequestContext.
- 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
Create a new RequestContext
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();
Public methods
Accessors
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()(introduzido na 1.19) - the WikiPage instance being outputted (but see below).$context->canUseWikiPage()(introduzido na 1.19) - checks whethergetWikiPage()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()(introduzido na 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() )).
When writing SpecialPage
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.
When writing skin code
Like SpecialPage, 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.
Alternative classes to consider
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 use IContextSource, not RequestContext.
ContextSource is an abstract helper class which like RequestContext, implements IContextSource.
By making your new class extend ContextSource, your class will be provided with the various helper methods (getOutput(), getSkin(), getLanguage(), etc.) and it will implement IContextSource.
Like ContextSource, DerivativeContext can be used to inherit the context from another source, but it also allows for the individual pieces of the context, such as a Title instance, to be changed locally.