3 * MediaWiki session info
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.
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.
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
24 namespace MediaWiki\Session
;
27 * Value object returned by SessionProvider
29 * This holds the data necessary to construct a Session.
35 /** Minimum allowed priority */
36 const MIN_PRIORITY
= 1;
38 /** Maximum allowed priority */
39 const MAX_PRIORITY
= 100;
41 /** @var SessionProvider|null */
50 /** @var UserInfo|null */
51 private $userInfo = null;
54 private $persisted = false;
57 private $remembered = false;
60 private $forceHTTPS = false;
63 private $idIsSafe = false;
66 private $forceUse = false;
68 /** @var array|null */
69 private $providerMetadata = null;
72 * @param int $priority Session priority
74 * - provider: (SessionProvider|null) If not given, the provider will be
75 * determined from the saved session data.
76 * - id: (string|null) Session ID
77 * - userInfo: (UserInfo|null) User known from the request. If
78 * $provider->canChangeUser() is false, a verified user
80 * - persisted: (bool) Whether this session was persisted
81 * - remembered: (bool) Whether the verified user was remembered.
83 * - forceHTTPS: (bool) Whether to force HTTPS for this session
84 * - metadata: (array) Provider metadata, to be returned by
85 * Session::getProviderMetadata(). See SessionProvider::mergeMetadata()
86 * and SessionProvider::refreshSessionInfo().
87 * - idIsSafe: (bool) Set true if the 'id' did not come from the user.
88 * Generally you'll use this from SessionProvider::newEmptySession(),
89 * and not from any other method.
90 * - forceUse: (bool) Set true if the 'id' is from
91 * SessionProvider::hashToSessionId() to delete conflicting session
92 * store data instead of discarding this SessionInfo. Ignored unless
93 * both 'provider' and 'id' are given.
94 * - copyFrom: (SessionInfo) SessionInfo to copy other data items from.
96 public function __construct( $priority, array $data ) {
97 if ( $priority < self
::MIN_PRIORITY ||
$priority > self
::MAX_PRIORITY
) {
98 throw new \
InvalidArgumentException( 'Invalid priority' );
101 if ( isset( $data['copyFrom'] ) ) {
102 $from = $data['copyFrom'];
103 if ( !$from instanceof SessionInfo
) {
104 throw new \
InvalidArgumentException( 'Invalid copyFrom' );
107 'provider' => $from->provider
,
109 'userInfo' => $from->userInfo
,
110 'persisted' => $from->persisted
,
111 'remembered' => $from->remembered
,
112 'forceHTTPS' => $from->forceHTTPS
,
113 'metadata' => $from->providerMetadata
,
114 'idIsSafe' => $from->idIsSafe
,
115 'forceUse' => $from->forceUse
,
116 // @codeCoverageIgnoreStart
118 // @codeCoverageIgnoreEnd
124 'persisted' => false,
125 'remembered' => true,
126 'forceHTTPS' => false,
130 // @codeCoverageIgnoreStart
132 // @codeCoverageIgnoreEnd
135 if ( $data['id'] !== null && !SessionManager
::validateSessionId( $data['id'] ) ) {
136 throw new \
InvalidArgumentException( 'Invalid session ID' );
139 if ( $data['userInfo'] !== null && !$data['userInfo'] instanceof UserInfo
) {
140 throw new \
InvalidArgumentException( 'Invalid userInfo' );
143 if ( !$data['provider'] && $data['id'] === null ) {
144 throw new \
InvalidArgumentException(
145 'Must supply an ID when no provider is given'
149 if ( $data['metadata'] !== null && !is_array( $data['metadata'] ) ) {
150 throw new \
InvalidArgumentException( 'Invalid metadata' );
153 $this->provider
= $data['provider'];
154 if ( $data['id'] !== null ) {
155 $this->id
= $data['id'];
156 $this->idIsSafe
= $data['idIsSafe'];
157 $this->forceUse
= $data['forceUse'] && $this->provider
;
159 $this->id
= $this->provider
->getManager()->generateSessionId();
160 $this->idIsSafe
= true;
161 $this->forceUse
= false;
163 $this->priority
= (int)$priority;
164 $this->userInfo
= $data['userInfo'];
165 $this->persisted
= (bool)$data['persisted'];
166 if ( $data['provider'] !== null ) {
167 if ( $this->userInfo
!== null && !$this->userInfo
->isAnon() && $this->userInfo
->isVerified() ) {
168 $this->remembered
= (bool)$data['remembered'];
170 $this->providerMetadata
= $data['metadata'];
172 $this->forceHTTPS
= (bool)$data['forceHTTPS'];
176 * Return the provider
177 * @return SessionProvider|null
179 final public function getProvider() {
180 return $this->provider
;
184 * Return the session ID
187 final public function getId() {
192 * Indicate whether the ID is "safe"
194 * The ID is safe in the following cases:
195 * - The ID was randomly generated by the constructor.
196 * - The ID was found in the backend data store.
197 * - $this->getProvider()->persistsSessionId() is false.
198 * - The constructor was explicitly told it's safe using the 'idIsSafe'
203 final public function isIdSafe() {
204 return $this->idIsSafe
;
208 * Force use of this SessionInfo if validation fails
210 * The normal behavior is to discard the SessionInfo if validation against
211 * the data stored in the session store fails. If this returns true,
212 * SessionManager will instead delete the session store data so this
213 * SessionInfo may still be used. This is important for providers which use
214 * deterministic IDs and so cannot just generate a random new one.
218 final public function forceUse() {
219 return $this->forceUse
;
223 * Return the priority
226 final public function getPriority() {
227 return $this->priority
;
232 * @return UserInfo|null
234 final public function getUserInfo() {
235 return $this->userInfo
;
239 * Return whether the session is persisted
242 final public function wasPersisted() {
243 return $this->persisted
;
247 * Return provider metadata
250 final public function getProviderMetadata() {
251 return $this->providerMetadata
;
255 * Return whether the user was remembered
257 * For providers that can persist the user separately from the session,
258 * the human using it may not actually *want* that to be done. For example,
259 * a cookie-based provider can set cookies that are longer-lived than the
260 * backend session data, but on a public terminal the human likely doesn't
261 * want those cookies set.
263 * This is false unless a non-anonymous verified user was passed to
264 * the SessionInfo constructor by the provider, and the provider didn't
265 * pass false for the 'remembered' data item.
269 final public function wasRemembered() {
270 return $this->remembered
;
274 * Whether this session should only be used over HTTPS
277 final public function forceHTTPS() {
278 return $this->forceHTTPS
;
281 public function __toString() {
282 return '[' . $this->getPriority() . ']' .
283 ( $this->getProvider() ?
: 'null' ) .
284 ( $this->userInfo ?
: '<null>' ) . $this->getId();
288 * Compare two SessionInfo objects by priority
289 * @param SessionInfo $a
290 * @param SessionInfo $b
291 * @return int Negative if $a < $b, positive if $a > $b, zero if equal
293 public static function compare( $a, $b ) {
294 return $a->getPriority() <=> $b->getPriority();