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