UserOptionsManager.php

Go to the documentation of this file.

<?php
namespace MediaWiki\User;
 
use DBAccessObjectUtils;
use HTMLCheckMatrix;
use HTMLFormField;
use HTMLMultiSelectField;
use IContextSource;
use InvalidArgumentException;
use LanguageCode;
use MediaWiki\Config\ServiceOptions;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\Languages\LanguageConverterFactory;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use Psr\Log\LoggerInterface;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\ILoadBalancer;
 
class UserOptionsManager extends UserOptionsLookup {
 
    public const CONSTRUCTOR_OPTIONS = [
        MainConfigNames::HiddenPrefs,
        MainConfigNames::LocalTZoffset,
    ];
 
    public const MAX_BYTES_OPTION_VALUE = 65530;
 
    private $serviceOptions;
 
    private $defaultOptionsLookup;
 
    private $languageConverterFactory;
 
    private $loadBalancer;
 
    private $userFactory;
 
    private $logger;
 
    private $modifiedOptions = [];
 
    private $originalOptionsCache = [];
 
    private $optionsFromDb = [];
 
    private $hookRunner;
 
    private $queryFlagsUsedForCaching = [];
 
    public function __construct(
        ServiceOptions $options,
        DefaultOptionsLookup $defaultOptionsLookup,
        LanguageConverterFactory $languageConverterFactory,
        ILoadBalancer $loadBalancer,
        LoggerInterface $logger,
        HookContainer $hookContainer,
        UserFactory $userFactory
    ) {
        $options->assertRequiredOptions( self::CONSTRUCTOR_OPTIONS );
        $this->serviceOptions = $options;
        $this->defaultOptionsLookup = $defaultOptionsLookup;
        $this->languageConverterFactory = $languageConverterFactory;
        $this->loadBalancer = $loadBalancer;
        $this->logger = $logger;
        $this->hookRunner = new HookRunner( $hookContainer );
        $this->userFactory = $userFactory;
    }
 
    public function getDefaultOptions(): array {
        return $this->defaultOptionsLookup->getDefaultOptions();
    }
 
    public function getOption(
        UserIdentity $user,
        string $oname,
        $defaultOverride = null,
        bool $ignoreHidden = false,
        int $queryFlags = self::READ_NORMAL
    ) {
        # We want 'disabled' preferences to always behave as the default value for
        # users, even if they have set the option explicitly in their settings (ie they
        # set it, and then it was disabled removing their ability to change it).  But
        # we don't want to erase the preferences in the database in case the preference
        # is re-enabled again.  So don't touch $mOptions, just override the returned value
        if ( !$ignoreHidden && in_array( $oname, $this->serviceOptions->get( MainConfigNames::HiddenPrefs ) ) ) {
            return $this->defaultOptionsLookup->getDefaultOption( $oname );
        }
 
        $options = $this->loadUserOptions( $user, $queryFlags );
        if ( array_key_exists( $oname, $options ) ) {
            return $options[$oname];
        }
        return $defaultOverride;
    }
 
    public function getOptions(
        UserIdentity $user,
        int $flags = 0,
        int $queryFlags = self::READ_NORMAL
    ): array {
        $options = $this->loadUserOptions( $user, $queryFlags );
 
        # We want 'disabled' preferences to always behave as the default value for
        # users, even if they have set the option explicitly in their settings (ie they
        # set it, and then it was disabled removing their ability to change it).  But
        # we don't want to erase the preferences in the database in case the preference
        # is re-enabled again.  So don't touch $mOptions, just override the returned value
        foreach ( $this->serviceOptions->get( MainConfigNames::HiddenPrefs ) as $pref ) {
            $default = $this->defaultOptionsLookup->getDefaultOption( $pref );
            if ( $default !== null ) {
                $options[$pref] = $default;
            }
        }
 
        if ( $flags & self::EXCLUDE_DEFAULTS ) {
            $defaultOptions = $this->defaultOptionsLookup->getDefaultOptions();
            foreach ( $options as $option => $value ) {
                if ( array_key_exists( $option, $defaultOptions )
                    && $this->isValueEqual( $value, $defaultOptions[$option] )
                ) {
                    unset( $options[$option] );
                }
            }
        }
 
        return $options;
    }
 
    public function setOption( UserIdentity $user, string $oname, $val ) {
        // Explicitly NULL values should refer to defaults
        if ( $val === null ) {
            $val = $this->defaultOptionsLookup->getDefaultOption( $oname );
        }
        $this->modifiedOptions[$this->getCacheKey( $user )][$oname] = $val;
    }
 
    public function resetOptions(
        UserIdentity $user,
        IContextSource $context,
        $resetKinds = [ 'registered', 'registered-multiselect', 'registered-checkmatrix', 'unused' ]
    ) {
        $oldOptions = $this->loadUserOptions( $user, self::READ_LATEST );
        $defaultOptions = $this->defaultOptionsLookup->getDefaultOptions();
 
        if ( !is_array( $resetKinds ) ) {
            $resetKinds = [ $resetKinds ];
        }
 
        if ( in_array( 'all', $resetKinds ) ) {
            $newOptions = $defaultOptions + array_fill_keys( array_keys( $oldOptions ), null );
        } else {
            $optionKinds = $this->getOptionKinds( $user, $context );
            $resetKinds = array_intersect( $resetKinds, $this->listOptionKinds() );
            $newOptions = [];
 
            // Use default values for the options that should be deleted, and
            // copy old values for the ones that shouldn't.
            foreach ( $oldOptions as $key => $value ) {
                if ( in_array( $optionKinds[$key], $resetKinds ) ) {
                    if ( array_key_exists( $key, $defaultOptions ) ) {
                        $newOptions[$key] = $defaultOptions[$key];
                    }
                } else {
                    $newOptions[$key] = $value;
                }
            }
        }
        $this->modifiedOptions[$this->getCacheKey( $user )] = $newOptions;
    }
 
    public function listOptionKinds(): array {
        return [
            'registered',
            'registered-multiselect',
            'registered-checkmatrix',
            'userjs',
            'special',
            'unused'
        ];
    }
 
    public function getOptionKinds(
        UserIdentity $userIdentity,
        IContextSource $context,
        $options = null
    ): array {
        if ( $options === null ) {
            $options = $this->loadUserOptions( $userIdentity );
        }
 
        // TODO: injecting the preferences factory creates a cyclic dependency between
        // PreferencesFactory and UserOptionsManager. See T250822
        $preferencesFactory = MediaWikiServices::getInstance()->getPreferencesFactory();
        $user = $this->userFactory->newFromUserIdentity( $userIdentity );
        $prefs = $preferencesFactory->getFormDescriptor( $user, $context );
        $mapping = [];
 
        // Pull out the "special" options, so they don't get converted as
        // multiselect or checkmatrix.
        $specialOptions = array_fill_keys( $preferencesFactory->getSaveBlacklist(), true );
        foreach ( $specialOptions as $name => $value ) {
            unset( $prefs[$name] );
        }
 
        // Multiselect and checkmatrix options are stored in the database with
        // one key per option, each having a boolean value. Extract those keys.
        $multiselectOptions = [];
        foreach ( $prefs as $name => $info ) {
            if ( ( isset( $info['type'] ) && $info['type'] == 'multiselect' ) ||
                ( isset( $info['class'] ) && $info['class'] == HTMLMultiSelectField::class )
            ) {
                $opts = HTMLFormField::flattenOptions( $info['options'] ?? $info['options-messages'] );
                $prefix = $info['prefix'] ?? $name;
 
                foreach ( $opts as $value ) {
                    $multiselectOptions["$prefix$value"] = true;
                }
 
                unset( $prefs[$name] );
            }
        }
        $checkmatrixOptions = [];
        foreach ( $prefs as $name => $info ) {
            if ( ( isset( $info['type'] ) && $info['type'] == 'checkmatrix' ) ||
                ( isset( $info['class'] ) && $info['class'] == HTMLCheckMatrix::class )
            ) {
                $columns = HTMLFormField::flattenOptions( $info['columns'] );
                $rows = HTMLFormField::flattenOptions( $info['rows'] );
                $prefix = $info['prefix'] ?? $name;
 
                foreach ( $columns as $column ) {
                    foreach ( $rows as $row ) {
                        $checkmatrixOptions["$prefix$column-$row"] = true;
                    }
                }
 
                unset( $prefs[$name] );
            }
        }
 
        // $value is ignored
        foreach ( $options as $key => $value ) {
            if ( isset( $prefs[$key] ) ) {
                $mapping[$key] = 'registered';
            } elseif ( isset( $multiselectOptions[$key] ) ) {
                $mapping[$key] = 'registered-multiselect';
            } elseif ( isset( $checkmatrixOptions[$key] ) ) {
                $mapping[$key] = 'registered-checkmatrix';
            } elseif ( isset( $specialOptions[$key] ) ) {
                $mapping[$key] = 'special';
            } elseif ( str_starts_with( $key, 'userjs-' ) ) {
                $mapping[$key] = 'userjs';
            } else {
                $mapping[$key] = 'unused';
            }
        }
 
        return $mapping;
    }
 
    public function saveOptions( UserIdentity $user ) {
        $dbw = $this->loadBalancer->getConnectionRef( DB_PRIMARY );
        $changed = $this->saveOptionsInternal( $user, $dbw );
        $legacyUser = $this->userFactory->newFromUserIdentity( $user );
        // Before UserOptionsManager, User::saveSettings was used for user options
        // saving. Some extensions might depend on UserSaveSettings hook being run
        // when options are saved, so run this hook for legacy reasons.
        // Once UserSaveSettings hook is deprecated and replaced with a different hook
        // with more modern interface, extensions should use 'SaveUserOptions' hook.
        $this->hookRunner->onUserSaveSettings( $legacyUser );
        if ( $changed ) {
            $dbw->onTransactionCommitOrIdle( static function () use ( $legacyUser ) {
                $legacyUser->checkAndSetTouched();
            }, __METHOD__ );
        }
    }
 
    public function saveOptionsInternal( UserIdentity $user, IDatabase $dbw ): bool {
        if ( !$user->isRegistered() ) {
            throw new InvalidArgumentException( __METHOD__ . ' was called on anon user' );
        }
 
        $userKey = $this->getCacheKey( $user );
        $modifiedOptions = $this->modifiedOptions[$userKey] ?? [];
        $originalOptions = $this->loadOriginalOptions( $user );
        if ( !$this->hookRunner->onSaveUserOptions( $user, $modifiedOptions, $originalOptions ) ) {
            return false;
        }
 
        $rowsToInsert = [];
        $keysToDelete = [];
        foreach ( $modifiedOptions as $key => $value ) {
            // Don't store unchanged or default values
            $defaultValue = $this->defaultOptionsLookup->getDefaultOption( $key );
            $oldValue = $this->optionsFromDb[$userKey][$key] ?? null;
            if ( $value === null || $this->isValueEqual( $value, $defaultValue ) ) {
                if ( array_key_exists( $key, $this->optionsFromDb[$userKey] ) ) {
                    // Delete the default value from the database
                    $keysToDelete[] = $key;
                }
            } elseif ( !$this->isValueEqual( $value, $oldValue ) ) {
                // Update by deleting (if old value exists) and reinserting
                $rowsToInsert[] = [
                    'up_user' => $user->getId(),
                    'up_property' => $key,
                    'up_value' => mb_strcut( $value, 0, self::MAX_BYTES_OPTION_VALUE ),
                ];
                if ( array_key_exists( $key, $this->optionsFromDb[$userKey] ) ) {
                    $keysToDelete[] = $key;
                }
            }
        }
 
        if ( !count( $keysToDelete ) && !count( $rowsToInsert ) ) {
            // Nothing to do
            return false;
        }
 
        // Do the DELETE
        if ( $keysToDelete ) {
            $dbw->delete(
                'user_properties',
                [
                    'up_user' => $user->getId(),
                    'up_property' => $keysToDelete
                ],
                __METHOD__
            );
        }
        if ( $rowsToInsert ) {
            // Insert the new preference rows
            $dbw->insert( 'user_properties', $rowsToInsert, __METHOD__, [ 'IGNORE' ] );
        }
 
        // It's pretty cheap to recalculate new original later
        // to apply whatever adjustments we apply when fetching from DB
        // and re-merge with the defaults.
        unset( $this->originalOptionsCache[$userKey] );
        // And nothing is modified anymore
        unset( $this->modifiedOptions[$userKey] );
        return true;
    }
 
    public function loadUserOptions(
        UserIdentity $user,
        int $queryFlags = self::READ_NORMAL,
        array $data = null
    ): array {
        $userKey = $this->getCacheKey( $user );
        $originalOptions = $this->loadOriginalOptions( $user, $queryFlags, $data );
        return array_merge( $originalOptions, $this->modifiedOptions[$userKey] ?? [] );
    }
 
    public function clearUserOptionsCache( UserIdentity $user ) {
        $cacheKey = $this->getCacheKey( $user );
        unset( $this->modifiedOptions[$cacheKey] );
        unset( $this->optionsFromDb[$cacheKey] );
        unset( $this->originalOptionsCache[$cacheKey] );
        unset( $this->queryFlagsUsedForCaching[$cacheKey] );
    }
 
    private function loadOptionsFromDb(
        UserIdentity $user,
        int $queryFlags,
        array $prefetchedOptions = null
    ): array {
        if ( $prefetchedOptions === null ) {
            $this->logger->debug( 'Loading options from database', [ 'user_id' => $user->getId() ] );
            [ $dbr, $options ] = $this->getDBAndOptionsForQueryFlags( $queryFlags );
            $res = $dbr->select(
                'user_properties',
                [ 'up_property', 'up_value' ],
                [ 'up_user' => $user->getId() ],
                __METHOD__,
                $options
            );
        } else {
            $res = [];
            foreach ( $prefetchedOptions as $name => $value ) {
                $res[] = [
                    'up_property' => $name,
                    'up_value' => $value,
                ];
            }
        }
        return $this->setOptionsFromDb( $user, $queryFlags, $res );
    }
 
    private function setOptionsFromDb(
        UserIdentity $user,
        int $queryFlags,
        iterable $rows
    ): array {
        $userKey = $this->getCacheKey( $user );
        $options = [];
        foreach ( $rows as $row ) {
            $row = (object)$row;
            // Convert '0' to 0. PHP's boolean conversion considers them both
            // false, but e.g. JavaScript considers the former as true.
            // @todo: T54542 Somehow determine the desired type (string/int/bool)
            //  and convert all values here.
            if ( $row->up_value === '0' ) {
                $row->up_value = 0;
            }
            $options[$row->up_property] = $row->up_value;
        }
        $this->optionsFromDb[$userKey] = $options;
        $this->queryFlagsUsedForCaching[$userKey] = $queryFlags;
        return $options;
    }
 
    private function loadOriginalOptions(
        UserIdentity $user,
        int $queryFlags = self::READ_NORMAL,
        array $data = null
    ): array {
        $userKey = $this->getCacheKey( $user );
        $defaultOptions = $this->defaultOptionsLookup->getDefaultOptions();
        if ( !$user->isRegistered() ) {
            // For unlogged-in users, load language/variant options from request.
            // There's no need to do it for logged-in users: they can set preferences,
            // and handling of page content is done by $pageLang->getPreferredVariant() and such,
            // so don't override user's choice (especially when the user chooses site default).
            $variant = $this->languageConverterFactory->getLanguageConverter()->getDefaultVariant();
            $defaultOptions['variant'] = $variant;
            $defaultOptions['language'] = $variant;
            $this->originalOptionsCache[$userKey] = $defaultOptions;
            return $defaultOptions;
        }
 
        // In case options were already loaded from the database before and no options
        // changes were saved to the database, we can use the cached original options.
        if ( $this->canUseCachedValues( $user, $queryFlags )
            && isset( $this->originalOptionsCache[$userKey] )
        ) {
            return $this->originalOptionsCache[$userKey];
        }
 
        $options = $this->loadOptionsFromDb( $user, $queryFlags, $data ) + $defaultOptions;
        // Replace deprecated language codes
        $options['language'] = LanguageCode::replaceDeprecatedCodes( $options['language'] );
        // Fix up timezone offset (Due to DST it can change from what was stored in the DB)
        // ZoneInfo|offset|TimeZoneName
        if ( isset( $options['timecorrection'] ) ) {
            $options['timecorrection'] = ( new UserTimeCorrection(
                $options['timecorrection'],
                null,
                $this->serviceOptions->get( MainConfigNames::LocalTZoffset )
            ) )->toString();
        }
 
        // Need to store what we have so far before the hook to prevent
        // infinite recursion if the hook attempts to reload options
        $this->originalOptionsCache[$userKey] = $options;
        $this->queryFlagsUsedForCaching[$userKey] = $queryFlags;
        $this->hookRunner->onLoadUserOptions( $user, $options );
        $this->originalOptionsCache[$userKey] = $options;
        return $options;
    }
 
    private function getCacheKey( UserIdentity $user ): string {
        return $user->isRegistered() ? "u:{$user->getId()}" : 'anon';
    }
 
    private function getDBAndOptionsForQueryFlags( $queryFlags ): array {
        [ $mode, $options ] = DBAccessObjectUtils::getDBOptions( $queryFlags );
        return [ $this->loadBalancer->getConnectionRef( $mode, [] ), $options ];
    }
 
    private function canUseCachedValues( UserIdentity $user, int $queryFlags ): bool {
        if ( !$user->isRegistered() ) {
            // Anon users don't have options stored in the database,
            // so $queryFlags are ignored.
            return true;
        }
        $userKey = $this->getCacheKey( $user );
        $queryFlagsUsed = $this->queryFlagsUsedForCaching[$userKey] ?? self::READ_NONE;
        return $queryFlagsUsed >= $queryFlags;
    }
 
    private function isValueEqual( $a, $b ) {
        if ( is_bool( $a ) ) {
            $a = (int)$a;
        }
        if ( is_bool( $b ) ) {
            $b = (int)$b;
        }
        return (string)$a === (string)$b;
    }
}