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 MediaWiki\Request\WebRequest;
27	use MediaWiki\User\User;
28	use Psr\Log\LoggerAwareInterface;
29
30	/**
31	* This exists to make IDEs happy, so they don't see the
32	* internal-but-required-to-be-public methods on SessionManager.
33	*
34	* @ingroup Session
35	* @since 1.27
36	*/
37	interface SessionManagerInterface extends LoggerAwareInterface {
38	/**
39	* Fetch the session for a request (or a new empty session if none is
40	* attached to it)
41	*
42	* @note You probably want to use $request->getSession() instead. It's more
43	*  efficient and doesn't break FauxRequests or sessions that were changed
44	*  by $this->getSessionById() or $this->getEmptySession().
45	* @param WebRequest $request Any existing associated session will be reset
46	*  to the session corresponding to the data in the request itself.
47	* @return Session
48	* @throws \OverflowException if there are multiple sessions tied for top
49	*  priority in the request. Exception has a property "sessionInfos"
50	*  holding the SessionInfo objects for the sessions involved.
51	*/
52	public function getSessionForRequest( WebRequest $request );
53
54	/**
55	* Fetch a session by ID
56	*
57	* @param string $id
58	* @param bool $create If no session exists for $id, try to create a new one.
59	*  May still return null if a session for $id exists but cannot be loaded.
60	* @param WebRequest|null $request Corresponding request. Any existing
61	*  session associated with this WebRequest object will be overwritten.
62	* @return Session|null
63	*/
64	public function getSessionById( $id, $create = false, ?WebRequest $request = null );
65
66	/**
67	* Create a new, empty session
68	*
69	* The first provider configured that is able to provide an empty session
70	* will be used.
71	*
72	* @param WebRequest|null $request Corresponding request. Any existing
73	*  session associated with this WebRequest object will be overwritten.
74	* @return Session
75	*/
76	public function getEmptySession( ?WebRequest $request = null );
77
78	/**
79	* Invalidate sessions for a user
80	*
81	* After calling this, existing sessions should be invalid. For mutable
82	* session providers, this generally means the user has to log in again;
83	* for immutable providers, it generally means the loss of session data.
84	*
85	* @param User $user
86	*/
87	public function invalidateSessionsForUser( User $user );
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 => $_ ) {
95	*   $outputPage->addVaryHeader( $header );
96	* }
97	* @endcode
98	*
99	* @return array<string,null>
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	}