Proyectos de Subversion Moodle

<?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 enrol_lti\local\ltiadvantage\entity;

/**
 * Class user, instances of which represent a specific lti user in the tool.
 *
 * A user is always associated with a resource, as lti users cannot exist without a tool-published-resource. A user will
 * always come from either:
 * - a resource link launch or
 * - a membership sync
 * Both of which required a published resource.
 *
 * Additionally, a user may be associated with a given resource_link instance, to signify that the user originated from
 * that resource_link. If a user is not associated with a resource_link, such as when creating a user during a member
 * sync, that param is nullable. This can be achieved via the factory method user::create_from_resource_link() or set
 * after instantiation via the user::set_resource_link_id() method.
 *
 * @package    enrol_lti
 * @copyright  2021 Jake Dallimore <jrhdallimore@gmail.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */
class user {

    /** @var int the id of the published resource to which this user belongs. */
    private $resourceid;

    /** @var int the local id of the deployment instance to which this user belongs. */
    private $deploymentid;

    /** @var string the id of the user in the platform site. */
    private $sourceid;

    /** @var int|null the id of this user instance, or null if not stored yet. */
    private $id;

    /** @var int|null the id of the user in the tool site, or null if the instance hasn't been stored yet. */
    private $localid;

    /** @var string city of the user. */
    private $city;

    /** @var string country of the user. */
    private $country;

    /** @var string institution of the user.*/
    private $institution;

    /** @var string timezone of the user. */
    private $timezone;

    /** @var int maildisplay of the user. */
    private $maildisplay;

    /** @var string language code of the user. */
    private $lang;

    /** @var float the user's last grade value. */
    private $lastgrade;

    /** @var int|null the user's last access unix timestamp, or null if they have not accessed the resource yet.*/
    private $lastaccess;

    /** @var int|null the id of the resource_link instance, or null if the user doesn't originate from one. */
    private $resourcelinkid;

    /**
     * Private constructor.
     *
     * @param int $resourceid the id of the published resource to which this user belongs.
     * @param int $userid the id of the Moodle user to which this LTI user relates.
     * @param int $deploymentid the local id of the deployment instance to which this user belongs.
     * @param string $sourceid the id of the user in the platform site.
     * @param string $lang the user's language code.
     * @param string $city the user's city.
     * @param string $country the user's country.
     * @param string $institution the user's institution.
     * @param string $timezone the user's timezone.
     * @param int|null $maildisplay the user's maildisplay, or null to select defaults.
     * @param float|null $lastgrade the user's last grade value.
     * @param int|null $lastaccess the user's last access time, or null if they haven't accessed the resource.
     * @param int|null $resourcelinkid the id of the resource link to link to the user, or null if not applicable.
     * @param int|null $id the id of this object instance, or null if it's a not-yet-persisted object.
     * @throws \coding_exception
     */
    private function __construct(int $resourceid, int $userid, int $deploymentid, string $sourceid,
            string $lang, string $city, string $country,
            string $institution, string $timezone, ?int $maildisplay, ?float $lastgrade, ?int $lastaccess,
            ?int $resourcelinkid = null, ?int $id = null) {

        global $CFG;
        $this->resourceid = $resourceid;
        $this->localid = $userid;
        $this->deploymentid = $deploymentid;
        if (empty($sourceid)) {
            throw new \coding_exception('Invalid sourceid value. Cannot be an empty string.');
        }
        $this->sourceid = $sourceid;
        $this->set_lang($lang);
        $this->set_city($city);
        $this->set_country($country);
        $this->set_institution($institution);
        $this->set_timezone($timezone);
        $maildisplay = $maildisplay ?? ($CFG->defaultpreference_maildisplay ?? 2);
        $this->set_maildisplay($maildisplay);
        $this->lastgrade = $lastgrade ?? 0.0;
        $this->lastaccess = $lastaccess;
        $this->resourcelinkid = $resourcelinkid;
        $this->id = $id;
    }

    /**
     * Factory method for creating a user instance associated with a given resource_link instance.
     *
     * @param int $resourcelinkid the local id of the resource link instance to link to the user.
     * @param int $resourceid the id of the published resource to which this user belongs.
     * @param int $userid the id of the Moodle user to which this LTI user relates.
     * @param int $deploymentid the local id of the deployment instance to which this user belongs.
     * @param string $sourceid the id of the user in the platform site.
     * @param string $lang the user's language code.
     * @param string $timezone the user's timezone.
     * @param string $city the user's city.
     * @param string $country the user's country.
     * @param string $institution the user's institution.
     * @param int|null $maildisplay the user's maildisplay, or null to select defaults.
     * @return user the user instance.
     */
    public static function create_from_resource_link(int $resourcelinkid, int $resourceid, int $userid,
            int $deploymentid, string $sourceid, string $lang, string $timezone,
            string $city = '', string $country = '', string $institution = '',
            ?int $maildisplay = null): user {

        return new self($resourceid, $userid, $deploymentid, $sourceid, $lang, $city,
            $country, $institution, $timezone, $maildisplay, null, null, $resourcelinkid);
    }

    /**
     * Factory method for creating a user.
     *
     * @param int $resourceid the id of the published resource to which this user belongs.
     * @param int $userid the id of the Moodle user to which this LTI user relates.
     * @param int $deploymentid the local id of the deployment instance to which this user belongs.
     * @param string $sourceid the id of the user in the platform site.
     * @param string $lang the user's language code.
     * @param string $timezone the user's timezone.
     * @param string $city the user's city.
     * @param string $country the user's country.
     * @param string $institution the user's institution.
     * @param int|null $maildisplay the user's maildisplay, or null to select defaults.
     * @param float|null $lastgrade the user's last grade value.
     * @param int|null $lastaccess the user's last access time, or null if they haven't accessed the resource.
     * @param int|null $resourcelinkid the local id of the resource link instance associated with the user.
     * @param int|null $id the id of this lti user instance, or null if it's a not-yet-persisted object.
     * @return user the user instance.
     */
    public static function create(int $resourceid, int $userid, int $deploymentid, string $sourceid,
            string $lang, string $timezone, string $city = '',
            string $country = '', string $institution = '', ?int $maildisplay = null, ?float $lastgrade = null,
            ?int $lastaccess = null, ?int $resourcelinkid = null, int $id = null): user {

        return new self($resourceid, $userid, $deploymentid, $sourceid, $lang, $city,
            $country, $institution, $timezone, $maildisplay, $lastgrade, $lastaccess, $resourcelinkid, $id);
    }

    /**
     * Get the id of this user instance.
     *
     * @return int|null the object id, or null if not yet persisted.
     */
    public function get_id(): ?int {
        return $this->id;
    }

    /**
     * Get the id of the resource_link instance to which this user is associated.
     *
     * @return int|null the object id, or null if the user isn't associated with one.
     */
    public function get_resourcelinkid(): ?int {
        return $this->resourcelinkid;
    }

    /**
     * Associate this user with the given resource_link instance, denoting that this user launched from the instance.
     *
     * @param int $resourcelinkid the id of the resource_link instance.
     */
    public function set_resourcelinkid(int $resourcelinkid): void {
        if ($resourcelinkid <= 0) {
            throw new \coding_exception("Invalid resourcelinkid '$resourcelinkid' provided. Must be > 0.");
        }
        $this->resourcelinkid = $resourcelinkid;
    }

    /**
     * Get the id of the published resource to which this user is associated.
     *
     * @return int the resource id.
     */
    public function get_resourceid(): int {
        return $this->resourceid;
    }

    /**
     * Get the id of the deployment instance to which this user belongs.
     *
     * @return int id of the deployment instance.
     */
    public function get_deploymentid(): int {
        return $this->deploymentid;
    }

    /**
     * Get the id of the user in the platform.
     *
     * @return string the source id.
     */
    public function get_sourceid(): string {
        return $this->sourceid;
    }

    /**
     * Get the id of the user in the tool.
     *
     * @return int|null the id, or null if the object instance hasn't yet been persisted.
     */
    public function get_localid(): ?int {
        return $this->localid;
    }

    /**
     * Get the user's city.
     *
     * @return string the city.
     */
    public function get_city(): string {
        return $this->city;
    }

    /**
     * Set the user's city.
     *
     * @param string $city the city string.
     */
    public function set_city(string $city): void {
        $this->city = $city;
    }

    /**
     * Get the user's country code.
     *
     * @return string the country code.
     */
    public function get_country(): string {
        return $this->country;
    }

    /**
     * Set the user's country.
     *
     * @param string $countrycode the 2 digit country code representing the country, or '' to denote none.
     */
    public function set_country(string $countrycode): void {
        global $CFG;
        require_once($CFG->libdir . '/moodlelib.php');
        $validcountrycodes = array_merge([''], array_keys(get_string_manager()->get_list_of_countries(true)));
        if (!in_array($countrycode, $validcountrycodes)) {
            throw new \coding_exception("Invalid country code '$countrycode'.");
        }
        $this->country = $countrycode;
    }

    /**
     * Get the instituation of the user.
     *
     * @return string the institution.
     */
    public function get_institution(): string {
        return $this->institution;
    }

    /**
     * Set the user's institution.
     *
     * @param string $institution the name of the institution.
     */
    public function set_institution(string $institution): void {
        $this->institution = $institution;
    }

    /**
     * Get the timezone of the user.
     *
     * @return string the user timezone.
     */
    public function get_timezone(): string {
        return $this->timezone;
    }

    /**
     * Set the user's timezone, or set '99' to specify server timezone.
     *
     * @param string $timezone the timezone string, or '99' to use server timezone.
     */
    public function set_timezone(string $timezone): void {
        if (empty($timezone)) {
            throw new \coding_exception('Invalid timezone value. Cannot be an empty string.');
        }
        $validtimezones = array_keys(\core_date::get_list_of_timezones(null, true));
        if (!in_array($timezone, $validtimezones)) {
            throw new \coding_exception("Invalid timezone '$timezone' provided.");
        }
        $this->timezone = $timezone;
    }

    /**
     * Get the maildisplay of the user.
     *
     * @return int the maildisplay.
     */
    public function get_maildisplay(): int {
        return $this->maildisplay;
    }

    /**
     * Set the user's mail display preference from a range of supported options.
     *
     * 0 - hide from non privileged users
     * 1 - allow everyone to see
     * 2 - allow only course participants to see
     *
     * @param int $maildisplay the maildisplay preference to set.
     */
    public function set_maildisplay(int $maildisplay): void {
        if (!in_array($maildisplay, range(0, 2))) {
            throw new \coding_exception("Invalid maildisplay value '$maildisplay'. Must be in the range {0..2}.");
        }
        $this->maildisplay = $maildisplay;
    }

    /**
     * Get the lang code of the user.
     *
     * @return string the user's language code.
     */
    public function get_lang(): string {
        return $this->lang;
    }

    /**
     * Set the user's language.
     *
     * @param string $langcode the language code representing the user's language.
     */
    public function set_lang(string $langcode): void {
        if (empty($langcode)) {
            throw new \coding_exception('Invalid lang value. Cannot be an empty string.');
        }
        $validlangcodes = array_keys(get_string_manager()->get_list_of_translations());
        if (!in_array($langcode, $validlangcodes)) {
            throw new \coding_exception("Invalid lang '$langcode' provided.");
        }
        $this->lang = $langcode;
    }

    /**
     * Get the last grade value for this user.
     *
     * @return float the float grade.
     */
    public function get_lastgrade(): float {
        return $this->lastgrade;
    }

    /**
     * Set the last grade for the user.
     *
     * @param float $lastgrade the last grade the user received.
     */
    public function set_lastgrade(float $lastgrade): void {
        global $CFG;
        require_once($CFG->libdir . '/gradelib.php');
        $this->lastgrade = grade_floatval($lastgrade);
    }

    /**
     * Get the last access timestamp for this user.
     *
     * @return int|null the last access timestampt, or null if the user hasn't accessed the resource.
     */
    public function get_lastaccess(): ?int {
        return $this->lastaccess;
    }

    /**
     * Set the last access time for the user.
     *
     * @param int $time unix timestamp representing the last time the user accessed the published resource.
     * @throws \coding_exception if $time is not a positive int.
     */
    public function set_lastaccess(int $time): void {
        if ($time < 0) {
            throw new \coding_exception('Cannot set negative access time');
        }
        $this->lastaccess = $time;
    }
}