Manuel:RequestContext.php

Fichier MediaWiki : RequestContext.php
Emplacement :	includes/context/
Code source :	master • 1.43.1 • 1.42.6 • 1.39.12
Classes :	MediaWiki\Context\RequestContext

Version de MediaWiki :

≥ 1.18

La classe RequestContext est utilisée pour encapsuler tous les éléments qui ont rapport au contexte d'une requête. Elle implémente les interfaces IContextSource et MutableContext .

Les extensions doivent appeler getContext() puis getSomeObject() plutôt que de s'appuyer sur les variables globales d'état.

Accès à RequestContext

La plupart des endroits où vous devez faire quelque chose avec les données RequestContext 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

Lorsque vous écrivez une SpecialPage , vous pouvez accéder au contexte via $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 doivent 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 en utilisant les variables relatives $wg RequestContext.

Lorsque vous écrivez du code d'habillage

Vous accédez au contexte par $this->getContext(); . Skin fournit de manière similaire quelques méthodes d'aide vues ci-après.

Lorsque vous utilisez des accroches

• Si votre accroche fournit un objet 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 fournissez 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'analyse syntaxique et des accroches

• Les fonctions d'analyse 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 quelque chose à la sortie de la page, 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 RequestContext.

Créer un nouveau 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();

Méthodes publiques

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 si getWikiPage() 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() )).

Ecriture d'une page spéciale

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 .

Ecrire le code d'un habillage

Comme SpecialPage, Skin implémente également plusieurs aides :

• $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 des méthodes sensibles du contexte doit être évité.

Classes alternatives à considérer

IContextSource

La base d'un 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 le type hinting dans les arguments, ou qui fait des contrôles instanceof vous devez utiliser IContextSource, et non pas RequestContext.

ContextSource

ContextSource est une classe d'aide abstraite qui, comme RequestContext, implémente IContextSource. En faisant en sorte que votre classe étende ContextSource, elle comportera les différentes méthodes d'aide (getOutput(), getSkin(), getLanguage(), etc.) et implémentera IContextSource.

DerivativeContext

Comme ContextSource, DerivativeContext peut être utilisé pour faire hériter le contexte d'une autre source, mais il permet aussi de modifier localement les éléments individuels du contexte, tels qu'une instance Title du titre.