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 persisted session ID in a request.
  39          *
  40          * Note this is not the same thing as whether the session associated with
  41          * the request is currently persistent, as the session might have been
  42          * first made persistent during this request.
  43          *
  44          * @param WebRequest $request
  45          * @return string|null
  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 getPersistedSessionId( WebRequest $request );
  51
  52         /**
  53          * Fetch the session for a request
  54          *
  55          * @note You probably want to use $request->getSession() instead. It's more
  56          *  efficient and doesn't break FauxRequests or sessions that were changed
  57          *  by $this->getSessionById() or $this->getEmptySession().
  58          * @param WebRequest $request Any existing associated session will be reset
  59          *  to the session corresponding to the data in the request itself.
  60          * @return Session
  61          * @throws \\OverflowException if there are multiple sessions tied for top
  62          *  priority in the request. Exception has a property "sessionInfos"
  63          *  holding the SessionInfo objects for the sessions involved.
  64          */
  65         public function getSessionForRequest( WebRequest $request );
  66
  67         /**
  68          * Fetch a session by ID
  69          * @param string $id
  70          * @param bool $create If no session exists for $id, try to create a new one.
  71          *  May still return null if a session for $id exists but cannot be loaded.
  72          * @param WebRequest|null $request Corresponding request. Any existing
  73          *  session associated with this WebRequest object will be overwritten.
  74          * @return Session|null
  75          */
  76         public function getSessionById( $id, $create = false, WebRequest $request = null );
  77
  78         /**
  79          * Fetch a new, empty session
  80          *
  81          * The first provider configured that is able to provide an empty session
  82          * will be used.
  83          *
  84          * @param WebRequest|null $request Corresponding request. Any existing
  85          *  session associated with this WebRequest object will be overwritten.
  86          * @return Session
  87          */
  88         public function getEmptySession( WebRequest $request = null );
  89
  90         /**
  91          * Return the HTTP headers that need varying on.
  92          *
  93          * The return value is such that someone could theoretically do this:
  94          * @code
  95          *  foreach ( $provider->getVaryHeaders() as $header => $options ) {
  96          *      $outputPage->addVaryHeader( $header, $options );
  97          *  }
  98          * @endcode
  99          *
 100          * @return array
 101          */
 102         public function getVaryHeaders();
 103
 104         /**
 105          * Return the list of cookies that need varying on.
 106          * @return string[]
 107          */
 108         public function getVaryCookies();
 109
 110 }