1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
<?php
namespace MediaWiki\User\Options;
use MediaWiki\User\UserIdentity;
/**
* Get or change options for a given user in a given backend store.
*
* #### Usage
*
* To read or save a user option, use the UserOptionsManager service instead.
* UserOptionsStore is the backend key-value abstraction used to differentiate
* between local and global preferences. This interface is considered internal
* and should only be called by the UserOptionsManager service. Unless you know
* which backend store an option belongs to, do not call this.
*
* Extension such as GlobalPreferences may implement this interface to create
* additional backend stores, but extensions should not instantiate or call
* classes with this interface.
*
* When creating a new implementation, register it via the UserOptionsStoreProviders
* extension attribute. The UserOptionsManager service will automatically discover
* and merge values from your backend. When calling UserOptionsManager::setOption
* or ApiOptions, we automatically write to the appropiate store, based on where
* a previous value existed, and the `global` flag.
*
* Launch task: https://phabricator.wikimedia.org/T323076
*
* #### See also
*
* Default implementation is MediaWiki\User\Options\LocalUserOptionsStore.
*
* For the frontend "Preferences" concept, and for registering and describing
* which user options can exist, refer to PreferencesFactory, $wgDefaultUserOptions
* and DefaultPreferencesFactory instead.
*
* @stable to implement
* @since 1.43
* @ingroup User
*/
interface UserOptionsStore {
/**
* Fetch all options for a given user from the store.
*
* Note that OptionsStore does not handle fallback to default. Options are
* either present or absent.
*
* @param UserIdentity $user A user with a non-zero ID
* @param int $recency a bit field composed of READ_XXX flags
* @return array<string,string>
*/
public function fetch( UserIdentity $user, int $recency );
/**
* Fetch specific options for multiple users from the store. Return an array
* indexed first by option key, and second by user name.
*
* @since 1.44
*
* @param array $keys
* @param array $userNames
* @return array<string,array<string,string>>
*/
public function fetchBatchForUserNames( array $keys, array $userNames );
/**
* Process a batch of option updates.
*
* The store may assume that fetch() was previously called with a recency
* sufficient to provide reference values for a differential update. It is
* the caller's responsibility to manage recency.
*
* Note that OptionsStore does not have a concept of defaults. The store is
* not required to check whether the value matches the default.
*
* @param UserIdentity $user A user with a non-zero ID
* @param array<string,string|null> $updates A map of option names to new
* values. If the value is null, the key should be deleted from the store
* and subsequently not returned from fetch(). Absent keys should be left
* unchanged.
* @return bool Whether any change was made
*/
public function store( UserIdentity $user, array $updates );
}
|
