includes/context/IContextSource.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 namespace MediaWiki\Context;
  22
  23 use MediaWiki\Config\Config;
  24 use MediaWiki\Language\Language;
  25 use MediaWiki\Language\LocalizationContext;
  26 use MediaWiki\Output\OutputPage;
  27 use MediaWiki\Permissions\Authority;
  28 use MediaWiki\Request\WebRequest;
  29 use MediaWiki\Session\CsrfTokenSetProvider;
  30 use MediaWiki\Title\Title;
  31 use MediaWiki\User\User;
  32 use Skin;
  33 use Timing;
  34 use WikiPage;
  35
  36 /**
  37  * Interface for objects which can provide a MediaWiki context on request
  38  *
  39  * Context objects contain request-dependent objects that manage the core
  40  * web request/response logic for essentially all requests to MediaWiki.
  41  * The contained objects include:
  42  *   a) Key objects that depend (for construction/loading) on the HTTP request
  43  *   b) Key objects used for response building and PHP session state control
  44  *   c) Performance metric deltas accumulated from request execution
  45  *   d) The site configuration object
  46  * All these objects are useful for the vast majority of MediaWiki requests.
  47  * The site configuration object is included on grounds of extreme
  48  * utility, even though it should not depend on the web request.
  49  *
  50  * More specifically, the scope of the context includes:
  51  *   a) Objects that represent the HTTP request/response and PHP session state
  52  *   b) Object representing the MediaWiki user (as determined by the HTTP request)
  53  *   c) Primary MediaWiki output builder objects (OutputPage, user skin object)
  54  *   d) The language object for the user/request
  55  *   e) The title and wiki page objects requested via URL (if any)
  56  *   f) Performance metric deltas accumulated from request execution
  57  *   g) The site configuration object
  58  *
  59  * This class is not intended as a service-locator nor a service singleton.
  60  * Objects that only depend on site configuration do not belong here (aside
  61  * from Config itself). Objects that represent persistent data stores do not
  62  * belong here either. Session state changes should only be propagated on
  63  * shutdown by separate persistence handler objects, for example.
  64  *
  65  * Must not be implemented directly by extensions, extend ContextSource instead.
  66  *
  67  * @since 1.18
  68  * @stable to type
  69  * @author Happy-melon
  70  */
  71 interface IContextSource extends LocalizationContext, CsrfTokenSetProvider {
  72
  73         /**
  74          * @return WebRequest
  75          */
  76         public function getRequest();
  77
  78         /**
  79          * @return Title|null
  80          */
  81         public function getTitle();
  82
  83         /**
  84          * Check whether a WikiPage object can be obtained with getWikiPage().
  85          *
  86          * Callers should expect that an exception is thrown from getWikiPage()
  87          * if this method returns false.
  88          *
  89          * @since 1.19
  90          * @return bool
  91          */
  92         public function canUseWikiPage();
  93
  94         /**
  95          * Get the WikiPage object.
  96          *
  97          * May throw an exception if there's no Title object set or the Title object
  98          * belongs to a special namespace that doesn't have WikiPage, so use first
  99          * canUseWikiPage() to check whether this method can be called safely.
 100          *
 101          * @since 1.19
 102          * @return WikiPage
 103          */
 104         public function getWikiPage();
 105
 106         /**
 107          * Get the action name for the current web request.
 108          *
 109          * @since 1.38
 110          * @return string
 111          */
 112         public function getActionName(): string;
 113
 114         /**
 115          * @return OutputPage
 116          */
 117         public function getOutput();
 118
 119         /**
 120          * @return User
 121          */
 122         public function getUser();
 123
 124         /**
 125          * @since 1.36
 126          * @return Authority
 127          */
 128         public function getAuthority(): Authority;
 129
 130         /**
 131          * @since 1.19
 132          * @return Language
 133          */
 134         public function getLanguage();
 135
 136         /**
 137          * @return Skin
 138          */
 139         public function getSkin();
 140
 141         /**
 142          * Get the site configuration
 143          *
 144          * @since 1.23
 145          * @return Config
 146          */
 147         public function getConfig();
 148
 149         /**
 150          * @since 1.27
 151          * @return Timing
 152          */
 153         public function getTiming();
 154
 155         /**
 156          * Export the resolved user IP, HTTP headers, user ID, and session ID.
 157          *
 158          * The result will be reasonably sized to allow for serialization.
 159          *
 160          * @return array
 161          * @since 1.21
 162          */
 163         public function exportSession();
 164 }
 165
 166 /** @deprecated class alias since 1.42 */
 167 class_alias( IContextSource::class, 'IContextSource' );