Manual:RequestContext.php/zh

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

Accessors
A RequestContext or IContextSource provides the following accessor methods:
 * - the instance to fetch request variables from.
 * - the instance for the page being outputted.
 * - a instance tied to the RequestContext for sending page output to.
 * - the class instance being used to render the page.
 * - the instance of for the user the page is rendered for.
 * - (added in 1.19 to replace the now deprecated ) the  instance of the user language the page is rendered in.
 * - the instance being outputted (but see below).
 * - checks whether  can be called, or it will throw an exception.
 * - returns a object with context set to the context being called. 它具有与相同的参数.
 * - 主要的对象

The output and language are read-only, the rest of the RequestContext may be set using methods such as ).

Working with Request Contexts
You can access the main request context using  however this should be a last resort. Most places where you need to do something with request context data should provice access to an IContextData source and you should use that, not the main RequestContext instance or  globals.


 * 编写特殊页面时
 * 您可以通过 访问上下文
 * SpecialPage also implements a number of helpers:
 * You can use  for the title of the SpecialPage and   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.
 * You can use  for the title of the SpecialPage and   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.
 * You can use  for the title of the SpecialPage and   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
 * You have access to the context through
 * Skin also implements a number of helpers:
 * The skin context is entered by  which is called by   external access to context sensitive method calls should be avoided.
 * The skin context is entered by  which is called by   external access to context sensitive method calls should be avoided.
 * The skin context is entered by  which is called by   external access to context sensitive method calls should be avoided.


 * 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  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.
 * 例如：
 * 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
There is still code using the global, , and 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:

Using a DerivativeContext
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.

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
The base of a RequestContext is the  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.

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. However unfortunately because we cannot use traits yet if you need to make your class extend from another class you will have to  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:

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 to allow something like this:

Using the linker alone
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:

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.