moodle/user/classes/route/api/preferences.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core_user\route\api;

use core\exception\coding_exception;
use core\exception\invalid_parameter_exception;
use core\param;
use core\router\route;
use core\router\schema\objects\scalar_type;
use core\router\schema\response\payload_response;
use core\router\schema\response\content\payload_response_type;
use core\router\schema\response\response_type;
use core\user;
use core_user\route\responses\user_preferences_response;
use stdClass;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

/**
 * User preference API handler.
 *
 * @package    core_user
 * @copyright  Andrew Lyons <andrew@nicols.co.uk>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
#[route(
    path: '/{user}/preferences',
    pathtypes: [
        new \core\router\parameters\path_user(),
    ],
)]
class preferences {
    /**
     * Fetch all user preferences, or a specific user preference.
     *
     * @param ResponseInterface $response
     * @param ServerRequestInterface $request
     * @param stdClass $user
     * @param null|string $preference
     * @return payload_response
     */
    #[route(
        path: '[/{preference}]',
        title: 'Fetch user preferences',
        description: 'Fetch one user preference, or all user preferences',
        pathtypes: [
            new \core\router\schema\parameters\path_parameter(
                name: 'preference',
                type: param::RAW,
            ),
        ],
        responses: [
            new user_preferences_response(),
        ],
    )]
    public function get_preferences(
        ResponseInterface $response,
        ServerRequestInterface $request,
        stdClass $user,
        ?string  $preference,
    ): payload_response {
        $this->check_user($user);

        $result = get_user_preferences(
            name: $preference,
            user: $user,
        );

        if (!is_array($result)) {
            // Check if we received just one preference.
            $result = [$preference => $result];
        }

        return new payload_response($result, $request, $response);
    }

    /**
     * Set a set of user preferences.
     *
     * @param ResponseInterface $response
     * @param stdClass $user
     * @return payload_response
     */
    #[route(
        method: ['POST'],
        title: 'Set or update multiple user preferences',
        requestbody: new \core\router\schema\request_body(
            content: new payload_response_type(
                schema: new \core\router\schema\objects\schema_object(
                    content: [
                        'preferences' => new \core\router\schema\objects\array_of_strings(
                            keyparamtype: param::TEXT,
                            valueparamtype: param::RAW,
                        ),
                    ],
                ),
            ),
        ),
        responses: [
            new user_preferences_response(),
        ],
    )]
    public function set_preferences(
        ResponseInterface $response,
        ServerRequestInterface $request,
        stdClass $user,
    ): payload_response {
        $this->check_user($user);

        $values = $request->getParsedBody();
        $preferences = $values['preferences'] ?? [];

        foreach ($preferences as $preference => $value) {
            $this->set_single_preference($user, $preference, $value);
        }

        $result = array_filter(
            get_user_preferences(
                user: $user,
            ),
            fn ($preference) => array_key_exists($preference, $preferences),
            ARRAY_FILTER_USE_KEY,
        );

        return new payload_response($result, $request, $response);
    }

    /**
     * Set a single user preference.
     *
     * @param ResponseInterface $response
     * @param string $themename
     * @param string $component
     * @param null|string $identifier
     * @return response_type
     */
    #[route(
        path: '/{preference}',
        method: ['POST'],
        title: 'Set a single user preference',
        description: 'Set a single user preference',
        pathtypes: [
            new \core\router\schema\parameters\path_parameter(
                name: 'preference',
                type: param::RAW,
            ),
        ],
        requestbody: new \core\router\schema\request_body(
            content: new payload_response_type(
                schema: new \core\router\schema\objects\schema_object(
                    content: [
                        'value' => new scalar_type(param::RAW),
                    ],
                ),
            ),
        ),
        responses: [
            new \core\router\schema\response\response(
                statuscode: 200,
                description: 'OK',
                content: [
                    new \core\router\schema\response\content\json_media_type(
                        schema: new \core\router\schema\objects\array_of_strings(
                            keyparamtype: param::TEXT,
                            valueparamtype: param::RAW,
                        ),
                        examples: [
                            new \core\router\schema\example(
                                name: 'A single preference value',
                                summary: 'A json response containing a single preference',
                                value: [
                                    "drawers-open-index" => "1",
                                ],
                            ),
                        ]
                    ),
                ],
            ),
        ],
    )]
    public function set_preference(
        ResponseInterface $response,
        ServerRequestInterface $request,
        stdClass $user,
        ?string $preference,
    ): response_type {
        $this->check_user($user);

        $values = $request->getParsedBody();
        $value = $values['value'] ?? null;
        $this->set_single_preference($user, $preference, $value);

        return $this->get_preferences($response, $request, $user, $preference);
    }

    /**
     * Set a single user preference.
     *
     * @param \stdClass $user
     * @param string $preference
     * @param mixed $value
     * @throws \core\exception\access_denied_exception
     * @throws \invalid_parameter_exception
     */
    protected function set_single_preference(
        stdClass $user,
        string $preference,
        mixed $value,
    ): void {
        try {
            $definition = user::get_preference_definition($preference);
        } catch (coding_exception $e) {
            throw new invalid_parameter_exception("Invalid preference '$preference'");
        }

        if (!user::can_edit_preference($preference, $user)) {
            throw new \core\exception\access_denied_exception('You do not have permission to edit this preference.');
        }

        if (isset($definition['type'])) {
            $type = param::from_type($definition['type']);
            $value = $this->standardise_value($type, $value);
        }

        $cleanvalue = user::clean_preference($value, $preference);
        if ($cleanvalue !== $value) {
            throw new \invalid_parameter_exception("Invalid value for preference '$preference': '{$value}'");
        }
        $value = $cleanvalue;
        set_user_preference($preference, $value, $user->id);
    }

    /**
     * Ensure that the requested user meets the requirements.
     *
     * @param stdClass $user
     * @throws invalid_parameter_exception
     */
    protected function check_user(stdClass $user): void {
        global $USER;

        if ($user->id !== $USER->id) {
            throw new \core\exception\access_denied_exception(
                'You do not have permission to view or edit preferences for other users.',
            );
        }
    }

    /**
     * Standardise value based on type.
     *
     * Note: We cannot use \core\param here because we only want to cast some types.
     * Requests do not have an inherent understanding of anything but strings. We need to be strict on typing of integers and bools.
     *
     * @param string param $type
     * @param mixed $value
     * @return mixed
     */
    protected function standardise_value(param $type, mixed $value): mixed {
        if (is_numeric($value) || is_bool($value)) {
            switch ($type) {
                case param::INT:
                case param::BOOL:
                    $value = (int) $value;
            }
        }

        return $value;
    }
}