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 extends MessageLocalizer {
  54
  55         /**
  56          * @return WebRequest
  57          */
  58         public function getRequest();
  59
  60         /**
  61          * @return Title|null
  62          */
  63         public function getTitle();
  64
  65         /**
  66          * Check whether a WikiPage object can be get with getWikiPage().
  67          * Callers should expect that an exception is thrown from getWikiPage()
  68          * if this method returns false.
  69          *
  70          * @since 1.19
  71          * @return bool
  72          */
  73         public function canUseWikiPage();
  74
  75         /**
  76          * Get the WikiPage object.
  77          * May throw an exception if there's no Title object set or the Title object
  78          * belongs to a special namespace that doesn't have WikiPage, so use first
  79          * canUseWikiPage() to check whether this method can be called safely.
  80          *
  81          * @since 1.19
  82          * @return WikiPage
  83          */
  84         public function getWikiPage();
  85
  86         /**
  87          * @return OutputPage
  88          */
  89         public function getOutput();
  90
  91         /**
  92          * @return User
  93          */
  94         public function getUser();
  95
  96         /**
  97          * @return Language
  98          * @since 1.19
  99          */
 100         public function getLanguage();
 101
 102         /**
 103          * @return Skin
 104          */
 105         public function getSkin();
 106
 107         /**
 108          * Get the site configuration
 109          *
 110          * @since 1.23
 111          * @return Config
 112          */
 113         public function getConfig();
 114
 115         /**
 116          * @deprecated since 1.27 use a StatsdDataFactory from MediaWikiServices (preferably injected)
 117          *
 118          * @since 1.25
 119          * @return IBufferingStatsdDataFactory
 120          */
 121         public function getStats();
 122
 123         /**
 124          * @since 1.27
 125          * @return Timing
 126          */
 127         public function getTiming();
 128
 129         /**
 130          * Export the resolved user IP, HTTP headers, user ID, and session ID.
 131          * The result will be reasonably sized to allow for serialization.
 132          *
 133          * @return array
 134          * @since 1.21
 135          */
 136         public function exportSession();
 137 }