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  * @since 1.18
  19  *
  20  * @author Happy-melon
  21  * @file
  22  */
  23
  24 use Liuggio\StatsdClient\Factory\StatsdDataFactory;
  25
  26 /**
  27  * Interface for objects which can provide a MediaWiki context on request
  28  *
  29  * Context objects contain request-dependent objects that manage the core
  30  * web request/response logic for essentially all requests to MediaWiki.
  31  * The contained objects include:
  32  *   a) Key objects that depend (for construction/loading) on the HTTP request
  33  *   b) Key objects used for response building and PHP session state control
  34  *   c) Performance metric deltas accumulated from request execution
  35  *   d) The site configuration object
  36  * All of the objects are useful for the vast majority of MediaWiki requests.
  37  * The site configuration object is included on grounds of extreme
  38  * utility, even though it should not actually depend on the web request.
  39  *
  40  * More specifically, the scope of the context includes:
  41  *   a) Objects that represent the HTTP request/response and PHP session state
  42  *   b) Object representing the MediaWiki user (as determined by the HTTP request)
  43  *   c) Primary MediaWiki output builder objects (OutputPage, user skin object)
  44  *   d) The language object for the user/request
  45  *   e) The title and wiki page objects requested via URL (if any)
  46  *   f) Performance metric deltas accumulated from request execution
  47  *   g) The site configuration object
  48  *
  49  * This class is not intended as a service-locator nor a service singleton.
  50  * Objects that only depend on site configuration do not belong here (aside
  51  * from Config itself). Objects that represent persistent data stores do not
  52  * belong here either. Session state changes should only be propagated on
  53  * shutdown by separate persistence handler objects, for example.
  54  */
  55 interface IContextSource {
  56         /**
  57          * Get the WebRequest object
  58          *
  59          * @return WebRequest
  60          */
  61         public function getRequest();
  62
  63         /**
  64          * Get the Title object
  65          *
  66          * @return Title|null
  67          */
  68         public function getTitle();
  69
  70         /**
  71          * Check whether a WikiPage object can be get with getWikiPage().
  72          * Callers should expect that an exception is thrown from getWikiPage()
  73          * if this method returns false.
  74          *
  75          * @since 1.19
  76          * @return bool
  77          */
  78         public function canUseWikiPage();
  79
  80         /**
  81          * Get the WikiPage object.
  82          * May throw an exception if there's no Title object set or the Title object
  83          * belongs to a special namespace that doesn't have WikiPage, so use first
  84          * canUseWikiPage() to check whether this method can be called safely.
  85          *
  86          * @since 1.19
  87          * @return WikiPage
  88          */
  89         public function getWikiPage();
  90
  91         /**
  92          * Get the OutputPage object
  93          *
  94          * @return OutputPage
  95          */
  96         public function getOutput();
  97
  98         /**
  99          * Get the User object
 100          *
 101          * @return User
 102          */
 103         public function getUser();
 104
 105         /**
 106          * Get the Language object
 107          *
 108          * @return Language
 109          * @since 1.19
 110          */
 111         public function getLanguage();
 112
 113         /**
 114          * Get the Skin object
 115          *
 116          * @return Skin
 117          */
 118         public function getSkin();
 119
 120         /**
 121          * Get the site configuration
 122          *
 123          * @since 1.23
 124          * @return Config
 125          */
 126         public function getConfig();
 127
 128         /**
 129          * Get the stats object
 130          *
 131          * @deprecated since 1.27 use a StatsdDataFactory from MediaWikiServices (preferably injected)
 132          *
 133          * @since 1.25
 134          * @return StatsdDataFactory
 135          */
 136         public function getStats();
 137
 138         /**
 139          * Get the timing object
 140          *
 141          * @since 1.27
 142          * @return Timing
 143          */
 144         public function getTiming();
 145
 146         /**
 147          * Get a Message object with context set.  See wfMessage for parameters.
 148          *
 149          * @param mixed ...
 150          * @return Message
 151          */
 152         public function msg();
 153
 154         /**
 155          * Export the resolved user IP, HTTP headers, user ID, and session ID.
 156          * The result will be reasonably sized to allow for serialization.
 157          *
 158          * @return array
 159          * @since 1.21
 160          */
 161         public function exportSession();
 162 }