includes/session/SessionManagerInterface.php

   1 <?php
   2 /**
   3  * MediaWiki\Session entry point interface
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Session
  22  */
  23
  24 namespace MediaWiki\Session;
  25
  26 use Psr\Log\LoggerAwareInterface;
  27 use WebRequest;
  28
  29 /**
  30  * This exists to make IDEs happy, so they don't see the
  31  * internal-but-required-to-be-public methods on SessionManager.
  32  *
  33  * @ingroup Session
  34  * @since 1.27
  35  */
  36 interface SessionManagerInterface extends LoggerAwareInterface {
  37         /**
  38          * Fetch the session for a request
  39          *
  40          * @note You probably want to use $request->getSession() instead. It's more
  41          *  efficient and doesn't break FauxRequests or sessions that were changed
  42          *  by $this->getSessionById() or $this->getEmptySession().
  43          * @param WebRequest $request Any existing associated session will be reset
  44          *  to the session corresponding to the data in the request itself.
  45          * @return Session
  46          * @throws \\OverflowException if there are multiple sessions tied for top
  47          *  priority in the request. Exception has a property "sessionInfos"
  48          *  holding the SessionInfo objects for the sessions involved.
  49          */
  50         public function getSessionForRequest( WebRequest $request );
  51
  52         /**
  53          * Fetch a session by ID
  54          * @param string $id
  55          * @param bool $create If no session exists for $id, try to create a new one.
  56          *  May still return null if a session for $id exists but cannot be loaded.
  57          * @param WebRequest|null $request Corresponding request. Any existing
  58          *  session associated with this WebRequest object will be overwritten.
  59          * @return Session|null
  60          */
  61         public function getSessionById( $id, $create = false, WebRequest $request = null );
  62
  63         /**
  64          * Fetch a new, empty session
  65          *
  66          * The first provider configured that is able to provide an empty session
  67          * will be used.
  68          *
  69          * @param WebRequest|null $request Corresponding request. Any existing
  70          *  session associated with this WebRequest object will be overwritten.
  71          * @return Session
  72          */
  73         public function getEmptySession( WebRequest $request = null );
  74
  75         /**
  76          * Return the HTTP headers that need varying on.
  77          *
  78          * The return value is such that someone could theoretically do this:
  79          * @code
  80          *  foreach ( $provider->getVaryHeaders() as $header => $options ) {
  81          *      $outputPage->addVaryHeader( $header, $options );
  82          *  }
  83          * @endcode
  84          *
  85          * @return array
  86          */
  87         public function getVaryHeaders();
  88
  89         /**
  90          * Return the list of cookies that need varying on.
  91          * @return string[]
  92          */
  93         public function getVaryCookies();
  94
  95 }