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 $noEmpty Don't return an empty session
  71          * @param WebRequest|null $request Corresponding request. Any existing
  72          *  session associated with this WebRequest object will be overwritten.
  73          * @return Session|null
  74          */
  75         public function getSessionById( $id, $noEmpty = false, WebRequest $request = null );
  76
  77         /**
  78          * Fetch a new, empty session
  79          *
  80          * The first provider configured that is able to provide an empty session
  81          * will be used.
  82          *
  83          * @param WebRequest|null $request Corresponding request. Any existing
  84          *  session associated with this WebRequest object will be overwritten.
  85          * @return Session
  86          */
  87         public function getEmptySession( WebRequest $request = null );
  88
  89         /**
  90          * Return the HTTP headers that need varying on.
  91          *
  92          * The return value is such that someone could theoretically do this:
  93          * @code
  94          *  foreach ( $provider->getVaryHeaders() as $header => $options ) {
  95          *      $outputPage->addVaryHeader( $header, $options );
  96          *  }
  97          * @endcode
  98          *
  99          * @return array
 100          */
 101         public function getVaryHeaders();
 102
 103         /**
 104          * Return the list of cookies that need varying on.
 105          * @return string[]
 106          */
 107         public function getVaryCookies();
 108
 109 }