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