Manuel:RequestContext.php
| Fichier MediaWiki : RequestContext.php | |
|---|---|
| Emplacement : | includes/context/ |
| Code source : | master • 1.42.1 • 1.41.2 • 1.39.8 |
| Classes : | RequestContext |
| Version de 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.
Les extensions doivent appeler getContext() puis getSomeObject() plutôt que de s'appuyer sur les variables globales d'état.
Access a RequestContext
La plupart des endroits où vous devez faire quelque chose avec les données du contexte de requête doivent fournir un accès à une source IContextData et vous devez utiliser celle-ci et non pas l'instance principale RequestContext ni les variables globales $wg.
Vous pouvez accéder au contexte principal de la requête en utilisant RequestContext::getMain(); néanmoins ceci doit être fait en dernier recours.
Lorsque vous écrivez une SpecialPage
Vous pouvez accéder au contexte avec $this->getContext();
SpecialPage also implements a number of helper methods that are the equivalent of methods provided by RequestContext, for which see below.
Les SpecialPage sont faites pour être exécutées dans les contextes alternatifs ; les extensions devraient donc commencer à arrêter d’utiliser les $wg . Il est probable qu’à partir de MediaWiki 1.20 environ, nous arrêtions la prise en charge des pages spéciales transclusibles qui utilisent des variables $wg relatives au contexte de la requête.
Lorsque vous écrivez du code d'habillage
Vous accédez au contexte par $this->getContext();
Skin similarly provides a few helper methods, for which see below.
Lorsque vous utilisez des accroches
- Si votre accroche fournit un OutputPage en tant qu'argument, alors utilisez le contexte qu'il fournit.
- Si votre accroche s’exécute dans le contexte de sortie de la page
Skin::outputPage( $out );, et qu’une instance de Skin est fournie, utilisez le contexte fournit par le Skin. - Si votre accroche fournit une instance de Title, préférez utiliser celle-ci par rapport aux autres contextes.
- Le même principe est valable pour toutes les instances de WebRequest passées comme argument aux accroches.
- Assurez-vous d'utiliser la bonne accroche; si vous founissez un contexte qui n'est pas le bon, alors vous utilisez probablement une accroche à tord et vous pouvez créer des bogues incohérents.
- Néanmoins certaines accroches peuvent être obsolètes et doivent être appelées avec un nouveau contexte dans leur arguments.
Lorsque vous écrivez des fonctions d'analyseur syntaxique et des accroches
- Les fonctions de l'analyseur syntaxique ainsi que les accroches ne doivent pas accéder aux données des contextes de requête. Les autres informations contextuelles peuvent être accédées à partir de l'objet analyseur syntaxique local.
Par exemple :$parser->getOutput()->addModules( 'ext.my.module' ); - Utilisez ParserOptions pour tout ce dont vous avez besoin comme par exemple la langue de l'utilisateur.
- Utilisez la classe Linker:: en statique au lieu d'accéder à l'habillage.
- Si vous devez ajouter quelquechose à la page fournie, en dehors de la zone de contenu, la classe ParserOutput doit avoir les méthodes pour faire ce que vous voulez.
- Si les méthodes de ParserOutput ne sont pas assez flexibles pour ce que vous devez faire, il est possible d'enregistrer avec ParserOutput, une procédure de rappel (callback) qui sera appelée ultérieurement à un endroit où vous pourrez utiliser librement les contexte de la requête.
Create a new RequestContext
Il existe encore du code qui utilise les variables globales $wgOut, $wgTitle, $wgUser.
Tant que ceux-ci n'auront pas été supprimés, il ne faut pas s'attendre à ce que les contextes personnalisés fonctionnent parfaitement et nous aurons encore besoin des solutions de contournement, néanmoins si nous corrigeons le code pour ne plus utiliser ces variables globales, alors quelque chose de similaire à ce qui suit devrait être 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
RequestContext: les accesseurs
Un RequestContext ou IContextSource fournit les accesseurs suivants :
$context->getRequest()- instance WebRequest de laquelle récupérer les variables demandées.$context->getTitle()- instance Title pour la page devant être produite.$context->getOutput()- instance OutputPage liée à RequestContext, et vers laquelle sera envoyée la page produite.$context->getSkin()- instance de la classe Skin à utiliser pour générer la page.$context->getUser()- instance de User de l'utilisateur pour lequel la page est générée.$context->getLanguage()- (ajouté en 1.19 pour remplacer$context->getLang()dorénavant obsolète) instance Language de la langue de l'utilisateur dans laquelle la page est générée.$context->getWikiPage()(introduit dans 1.19) - instance WikiPage à produire (mais voir ci-dessous).$context->canUseWikiPage()(introduit dans 1.19) - vérifie sigetWikiPage()peut être appelé, sinon lève une exception.$context->msg()- renvoie un objet Message dont le contexte est initialisé comme le contexte appelé. possède les mêmes paramètres que wfMessage().$context->getConfig()(introduit dans 1.23) - objet Config principal
La sortie (output) et la langue (language) sont en lecture seule, le reste de RequestContext peut être initialisé en utilisant les méthodes telles que $context->setTitle( Title::newMainPage() )).
When writing SpecialPage
SpecialPage fournit aussi plusieurs raccourcis :
$this->getRequest()$this->getOutput()$this->getUser()$this->getAuthority()$this->getSkin()$this->getLanguage()$this->getConfig()$this->getFullTitle()Vous pouvez utiliser$this->getPageTitle();pour le titre de la SpecialPage et$this->getFullTitle();pour le titre de la page spéciale ainsi que pour toute donnée $par .
When writing skin code
Skin fournit aussi plusieurs raccourcis :
$this->getUser()$this->getTitle()
Le contexte de l’habillage est passé par Skin::outputPage( $out ); qui est appelé par OutputPage::output(); ; l’accès externe aux appels de méthodes sensibles au contexte doit être évité.
Alternative classes to consider
La base de RequestContext est l'interface IContextSource.
Il définit l'API d'un service à partir duquel vous pouvez obtenir des éléments du contexte de requête.
Si vous écrivez une API qui utilise des type hinting
dans les arguments, ou qui fait des contrôles instanceof vous devez utiliser IContextSoure, et non pas RequestContext.
ContextSource is an abstract helper class which like RequestContext, implements IContextSource.
En faisant en sorte que votre classe soit une extension de la classe ContextSource, elle contiendra directement déja, les différents assistants getOutput, getSkin, getLanguage, etc... et sera 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.