Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
42.11% covered (danger)
42.11%
8 / 19
33.33% covered (danger)
33.33%
2 / 6
 CRAP
0.00% covered (danger)
0.00%
0 / 1
UserOptionsLookup
44.44% covered (danger)
44.44%
8 / 18
33.33% covered (danger)
33.33%
2 / 6
 31.75
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getDefaultOptions
n/a
0 / 0
n/a
0 / 0
 0
 getDefaultOption
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 getOption
n/a
0 / 0
n/a
0 / 0
 0
 getOptions
n/a
0 / 0
n/a
0 / 0
 0
 getBoolOption
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 getIntOption
80.00% covered (warning)
80.00%
4 / 5
0.00% covered (danger)
0.00%
0 / 1
 2.03
 getCacheKey
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
 30
 isOptionGlobal
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getOptionBatchForUserNames
n/a
0 / 0
n/a
0 / 0
 0
1<?php
2/**
3 * @license GPL-2.0-or-later
4 * @file
5 */
6
7namespace MediaWiki\User\Options;
8
9use MediaWiki\User\UserIdentity;
10use MediaWiki\User\UserNameUtils;
11use Wikimedia\Rdbms\IDBAccessObject;
12
13/**
14 * Provides access to user options
15 * @since 1.35
16 */
17abstract class UserOptionsLookup {
18
19    /**
20     * Exclude user options that are set to their default value.
21     */
22    public const EXCLUDE_DEFAULTS = 1;
23
24    /**
25     * The suffix appended to preference names for the associated preference
26     * that tracks whether they have a local override.
27     * @since 1.43
28     */
29    public const LOCAL_EXCEPTION_SUFFIX = '-local-exception';
30
31    private UserNameUtils $userNameUtils;
32
33    public function __construct( UserNameUtils $userNameUtils ) {
34        $this->userNameUtils = $userNameUtils;
35    }
36
37    /**
38     * Combine the language default options with any site-specific and user-specific defaults
39     * and add the default language variants.
40     *
41     * @param UserIdentity|null $userIdentity User to look the default up for; set to null to
42     * ignore any user-specific defaults (since 1.42)
43     * @return array
44     */
45    abstract public function getDefaultOptions( ?UserIdentity $userIdentity = null ): array;
46
47    /**
48     * Get a given default option value.
49     *
50     * @param string $opt Name of option to retrieve
51     * @param UserIdentity|null $userIdentity User to look the defaults up for; set to null to
52     * ignore any user-specific defaults (since 1.42)
53     * @return mixed|null Default option value
54     */
55    public function getDefaultOption(
56        string $opt,
57        ?UserIdentity $userIdentity = null
58    ) {
59        $defaultOptions = $this->getDefaultOptions( $userIdentity );
60        return $defaultOptions[$opt] ?? null;
61    }
62
63    /**
64     * Get the user's current setting for a given option.
65     *
66     * @param UserIdentity $user The user to get the option for
67     * @param string $oname The option to check
68     * @param mixed|null $defaultOverride A default value returned if the option does not exist
69     * @param bool $ignoreHidden Whether to ignore the effects of $wgHiddenPrefs
70     * @param int $queryFlags A bit field composed of READ_XXX flags
71     * @return mixed|null User's current value for the option,
72     *   Note that while option values retrieved from the database are always strings, default
73     *   values and values set within the current request and not yet saved may be of another type.
74     * @see getBoolOption()
75     * @see getIntOption()
76     */
77    abstract public function getOption(
78        UserIdentity $user,
79        string $oname,
80        $defaultOverride = null,
81        bool $ignoreHidden = false,
82        int $queryFlags = IDBAccessObject::READ_NORMAL
83    );
84
85    /**
86     * Get all user's options
87     *
88     * @param UserIdentity $user The user to get the option for
89     * @param int $flags Bitwise combination of:
90     *   UserOptionsManager::EXCLUDE_DEFAULTS  Exclude user options that are set
91     *                                         to the default value. Options
92     *                                         that are set to their conditionally
93     *                                         default value are not excluded.
94     * @param int $queryFlags A bit field composed of READ_XXX flags
95     * @return array
96     */
97    abstract public function getOptions(
98        UserIdentity $user,
99        int $flags = 0,
100        int $queryFlags = IDBAccessObject::READ_NORMAL
101    ): array;
102
103    /**
104     * Get the user's current setting for a given option, as a boolean value.
105     *
106     * @param UserIdentity $user The user to get the option for
107     * @param string $oname The option to check
108     * @param int $queryFlags A bit field composed of READ_XXX flags
109     * @return bool User's current value for the option
110     * @see getOption()
111     */
112    public function getBoolOption(
113        UserIdentity $user,
114        string $oname,
115        int $queryFlags = IDBAccessObject::READ_NORMAL
116    ): bool {
117        return (bool)$this->getOption(
118            $user, $oname, null, false, $queryFlags );
119    }
120
121    /**
122     * Get the user's current setting for a given option, as an integer value.
123     *
124     * @param UserIdentity $user The user to get the option for
125     * @param string $oname The option to check
126     * @param int $defaultOverride A default value returned if the option does not exist
127     * @param int $queryFlags A bit field composed of READ_XXX flags
128     * @return int User's current value for the option
129     * @see getOption()
130     */
131    public function getIntOption(
132        UserIdentity $user,
133        string $oname,
134        int $defaultOverride = 0,
135        int $queryFlags = IDBAccessObject::READ_NORMAL
136    ): int {
137        $val = $this->getOption(
138            $user, $oname, $defaultOverride, false, $queryFlags );
139        if ( $val == '' ) {
140            $val = $defaultOverride;
141        }
142        return intval( $val );
143    }
144
145    /**
146     * Get a cache key for a user
147     * @param UserIdentity $user
148     * @return string
149     */
150    protected function getCacheKey( UserIdentity $user ): string {
151        $name = $user->getName();
152        if ( $this->userNameUtils->isIP( $name ) || $this->userNameUtils->isTemp( $name ) ) {
153            // IP and temporary users may not have custom preferences, so they can share a key
154            return 'anon';
155        } elseif ( $user->isRegistered() ) {
156            return "u:{$user->getId()}";
157        } else {
158            // Allow users with no local account to have preferences provided by alternative
159            // UserOptionsStore implementations (e.g. in GlobalPreferences)
160            $canonical = $this->userNameUtils->getCanonical( $name ) ?: $name;
161            return "a:$canonical";
162        }
163    }
164
165    /**
166     * Determine if a user option came from a source other than the local store
167     * or the defaults. If this is true, setting the option will be ignored
168     * unless GLOBAL_OVERRIDE or GLOBAL_UPDATE is passed to setOption().
169     *
170     * @param UserIdentity $user
171     * @param string $key
172     * @return bool
173     */
174    public function isOptionGlobal( UserIdentity $user, string $key ) {
175        return false;
176    }
177
178    /**
179     * Get a single option for a batch of users, given their names.
180     *
181     * Results are uncached. Use getOption() to get options with a per-user
182     * cache.
183     *
184     * User names are used because that's what GenderCache has. If you're
185     * calling this and you're not GenderCache, consider adding a method
186     * taking an array of UserIdentity objects instead.
187     *
188     * @since 1.44
189     * @param string[] $users A normalized list of usernames
190     * @param string $key The option to get
191     * @return array The option values, indexed by the provided usernames
192     */
193    abstract public function getOptionBatchForUserNames( array $users, string $key );
194}
195/** @deprecated class alias since 1.42 */
196class_alias( UserOptionsLookup::class, 'MediaWiki\\User\\UserOptionsLookup' );