[Summary view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  namespace enrol_lti\local\ltiadvantage\entity;
  18  
  19  /**
  20   * Class user, instances of which represent a specific lti user in the tool.
  21   *
  22   * A user is always associated with a resource, as lti users cannot exist without a tool-published-resource. A user will
  23   * always come from either:
  24   * - a resource link launch or
  25   * - a membership sync
  26   * Both of which required a published resource.
  27   *
  28   * Additionally, a user may be associated with a given resource_link instance, to signify that the user originated from
  29   * that resource_link. If a user is not associated with a resource_link, such as when creating a user during a member
  30   * sync, that param is nullable. This can be achieved via the factory method user::create_from_resource_link() or set
  31   * after instantiation via the user::set_resource_link_id() method.
  32   *
  33   * @package    enrol_lti
  34   * @copyright  2021 Jake Dallimore <jrhdallimore@gmail.com>
  35   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */
  36  class user {
  37  
  38      /** @var int the id of the published resource to which this user belongs. */
  39      private $resourceid;
  40  
  41      /** @var int the local id of the deployment instance to which this user belongs. */
  42      private $deploymentid;
  43  
  44      /** @var string the id of the user in the platform site. */
  45      private $sourceid;
  46  
  47      /** @var int|null the id of this user instance, or null if not stored yet. */
  48      private $id;
  49  
  50      /** @var int|null the id of the user in the tool site, or null if the instance hasn't been stored yet. */
  51      private $localid;
  52  
  53      /** @var string city of the user. */
  54      private $city;
  55  
  56      /** @var string country of the user. */
  57      private $country;
  58  
  59      /** @var string institution of the user.*/
  60      private $institution;
  61  
  62      /** @var string timezone of the user. */
  63      private $timezone;
  64  
  65      /** @var int maildisplay of the user. */
  66      private $maildisplay;
  67  
  68      /** @var string language code of the user. */
  69      private $lang;
  70  
  71      /** @var float the user's last grade value. */
  72      private $lastgrade;
  73  
  74      /** @var int|null the user's last access unix timestamp, or null if they have not accessed the resource yet.*/
  75      private $lastaccess;
  76  
  77      /** @var int|null the id of the resource_link instance, or null if the user doesn't originate from one. */
  78      private $resourcelinkid;
  79  
  80      /**
  81       * Private constructor.
  82       *
  83       * @param int $resourceid the id of the published resource to which this user belongs.
  84       * @param int $userid the id of the Moodle user to which this LTI user relates.
  85       * @param int $deploymentid the local id of the deployment instance to which this user belongs.
  86       * @param string $sourceid the id of the user in the platform site.
  87       * @param string $lang the user's language code.
  88       * @param string $city the user's city.
  89       * @param string $country the user's country.
  90       * @param string $institution the user's institution.
  91       * @param string $timezone the user's timezone.
  92       * @param int|null $maildisplay the user's maildisplay, or null to select defaults.
  93       * @param float|null $lastgrade the user's last grade value.
  94       * @param int|null $lastaccess the user's last access time, or null if they haven't accessed the resource.
  95       * @param int|null $resourcelinkid the id of the resource link to link to the user, or null if not applicable.
  96       * @param int|null $id the id of this object instance, or null if it's a not-yet-persisted object.
  97       * @throws \coding_exception
  98       */
  99      private function __construct(int $resourceid, int $userid, int $deploymentid, string $sourceid,
 100              string $lang, string $city, string $country,
 101              string $institution, string $timezone, ?int $maildisplay, ?float $lastgrade, ?int $lastaccess,
 102              ?int $resourcelinkid = null, ?int $id = null) {
 103  
 104          global $CFG;
 105          $this->resourceid = $resourceid;
 106          $this->localid = $userid;
 107          $this->deploymentid = $deploymentid;
 108          if (empty($sourceid)) {
 109              throw new \coding_exception('Invalid sourceid value. Cannot be an empty string.');
 110          }
 111          $this->sourceid = $sourceid;
 112          $this->set_lang($lang);
 113          $this->set_city($city);
 114          $this->set_country($country);
 115          $this->set_institution($institution);
 116          $this->set_timezone($timezone);
 117          $maildisplay = $maildisplay ?? ($CFG->defaultpreference_maildisplay ?? 2);
 118          $this->set_maildisplay($maildisplay);
 119          $this->lastgrade = $lastgrade ?? 0.0;
 120          $this->lastaccess = $lastaccess;
 121          $this->resourcelinkid = $resourcelinkid;
 122          $this->id = $id;
 123      }
 124  
 125      /**
 126       * Factory method for creating a user instance associated with a given resource_link instance.
 127       *
 128       * @param int $resourcelinkid the local id of the resource link instance to link to the user.
 129       * @param int $resourceid the id of the published resource to which this user belongs.
 130       * @param int $userid the id of the Moodle user to which this LTI user relates.
 131       * @param int $deploymentid the local id of the deployment instance to which this user belongs.
 132       * @param string $sourceid the id of the user in the platform site.
 133       * @param string $lang the user's language code.
 134       * @param string $timezone the user's timezone.
 135       * @param string $city the user's city.
 136       * @param string $country the user's country.
 137       * @param string $institution the user's institution.
 138       * @param int|null $maildisplay the user's maildisplay, or null to select defaults.
 139       * @return user the user instance.
 140       */
 141      public static function create_from_resource_link(int $resourcelinkid, int $resourceid, int $userid,
 142              int $deploymentid, string $sourceid, string $lang, string $timezone,
 143              string $city = '', string $country = '', string $institution = '',
 144              ?int $maildisplay = null): user {
 145  
 146          return new self($resourceid, $userid, $deploymentid, $sourceid, $lang, $city,
 147              $country, $institution, $timezone, $maildisplay, null, null, $resourcelinkid);
 148      }
 149  
 150      /**
 151       * Factory method for creating a user.
 152       *
 153       * @param int $resourceid the id of the published resource to which this user belongs.
 154       * @param int $userid the id of the Moodle user to which this LTI user relates.
 155       * @param int $deploymentid the local id of the deployment instance to which this user belongs.
 156       * @param string $sourceid the id of the user in the platform site.
 157       * @param string $lang the user's language code.
 158       * @param string $timezone the user's timezone.
 159       * @param string $city the user's city.
 160       * @param string $country the user's country.
 161       * @param string $institution the user's institution.
 162       * @param int|null $maildisplay the user's maildisplay, or null to select defaults.
 163       * @param float|null $lastgrade the user's last grade value.
 164       * @param int|null $lastaccess the user's last access time, or null if they haven't accessed the resource.
 165       * @param int|null $resourcelinkid the local id of the resource link instance associated with the user.
 166       * @param int|null $id the id of this lti user instance, or null if it's a not-yet-persisted object.
 167       * @return user the user instance.
 168       */
 169      public static function create(int $resourceid, int $userid, int $deploymentid, string $sourceid,
 170              string $lang, string $timezone, string $city = '',
 171              string $country = '', string $institution = '', ?int $maildisplay = null, ?float $lastgrade = null,
 172              ?int $lastaccess = null, ?int $resourcelinkid = null, int $id = null): user {
 173  
 174          return new self($resourceid, $userid, $deploymentid, $sourceid, $lang, $city,
 175              $country, $institution, $timezone, $maildisplay, $lastgrade, $lastaccess, $resourcelinkid, $id);
 176      }
 177  
 178      /**
 179       * Get the id of this user instance.
 180       *
 181       * @return int|null the object id, or null if not yet persisted.
 182       */
 183      public function get_id(): ?int {
 184          return $this->id;
 185      }
 186  
 187      /**
 188       * Get the id of the resource_link instance to which this user is associated.
 189       *
 190       * @return int|null the object id, or null if the user isn't associated with one.
 191       */
 192      public function get_resourcelinkid(): ?int {
 193          return $this->resourcelinkid;
 194      }
 195  
 196      /**
 197       * Associate this user with the given resource_link instance, denoting that this user launched from the instance.
 198       *
 199       * @param int $resourcelinkid the id of the resource_link instance.
 200       */
 201      public function set_resourcelinkid(int $resourcelinkid): void {
 202          if ($resourcelinkid <= 0) {
 203              throw new \coding_exception("Invalid resourcelinkid '$resourcelinkid' provided. Must be > 0.");
 204          }
 205          $this->resourcelinkid = $resourcelinkid;
 206      }
 207  
 208      /**
 209       * Get the id of the published resource to which this user is associated.
 210       *
 211       * @return int the resource id.
 212       */
 213      public function get_resourceid(): int {
 214          return $this->resourceid;
 215      }
 216  
 217      /**
 218       * Get the id of the deployment instance to which this user belongs.
 219       *
 220       * @return int id of the deployment instance.
 221       */
 222      public function get_deploymentid(): int {
 223          return $this->deploymentid;
 224      }
 225  
 226      /**
 227       * Get the id of the user in the platform.
 228       *
 229       * @return string the source id.
 230       */
 231      public function get_sourceid(): string {
 232          return $this->sourceid;
 233      }
 234  
 235      /**
 236       * Get the id of the user in the tool.
 237       *
 238       * @return int|null the id, or null if the object instance hasn't yet been persisted.
 239       */
 240      public function get_localid(): ?int {
 241          return $this->localid;
 242      }
 243  
 244      /**
 245       * Get the user's city.
 246       *
 247       * @return string the city.
 248       */
 249      public function get_city(): string {
 250          return $this->city;
 251      }
 252  
 253      /**
 254       * Set the user's city.
 255       *
 256       * @param string $city the city string.
 257       */
 258      public function set_city(string $city): void {
 259          $this->city = $city;
 260      }
 261  
 262      /**
 263       * Get the user's country code.
 264       *
 265       * @return string the country code.
 266       */
 267      public function get_country(): string {
 268          return $this->country;
 269      }
 270  
 271      /**
 272       * Set the user's country.
 273       *
 274       * @param string $countrycode the 2 digit country code representing the country, or '' to denote none.
 275       */
 276      public function set_country(string $countrycode): void {
 277          global $CFG;
 278          require_once($CFG->libdir . '/moodlelib.php');
 279          $validcountrycodes = array_merge([''], array_keys(get_string_manager()->get_list_of_countries(true)));
 280          if (!in_array($countrycode, $validcountrycodes)) {
 281              throw new \coding_exception("Invalid country code '$countrycode'.");
 282          }
 283          $this->country = $countrycode;
 284      }
 285  
 286      /**
 287       * Get the instituation of the user.
 288       *
 289       * @return string the institution.
 290       */
 291      public function get_institution(): string {
 292          return $this->institution;
 293      }
 294  
 295      /**
 296       * Set the user's institution.
 297       *
 298       * @param string $institution the name of the institution.
 299       */
 300      public function set_institution(string $institution): void {
 301          $this->institution = $institution;
 302      }
 303  
 304      /**
 305       * Get the timezone of the user.
 306       *
 307       * @return string the user timezone.
 308       */
 309      public function get_timezone(): string {
 310          return $this->timezone;
 311      }
 312  
 313      /**
 314       * Set the user's timezone, or set '99' to specify server timezone.
 315       *
 316       * @param string $timezone the timezone string, or '99' to use server timezone.
 317       */
 318      public function set_timezone(string $timezone): void {
 319          if (empty($timezone)) {
 320              throw new \coding_exception('Invalid timezone value. Cannot be an empty string.');
 321          }
 322          $validtimezones = array_keys(\core_date::get_list_of_timezones(null, true));
 323          if (!in_array($timezone, $validtimezones)) {
 324              throw new \coding_exception("Invalid timezone '$timezone' provided.");
 325          }
 326          $this->timezone = $timezone;
 327      }
 328  
 329      /**
 330       * Get the maildisplay of the user.
 331       *
 332       * @return int the maildisplay.
 333       */
 334      public function get_maildisplay(): int {
 335          return $this->maildisplay;
 336      }
 337  
 338      /**
 339       * Set the user's mail display preference from a range of supported options.
 340       *
 341       * 0 - hide from non privileged users
 342       * 1 - allow everyone to see
 343       * 2 - allow only course participants to see
 344       *
 345       * @param int $maildisplay the maildisplay preference to set.
 346       */
 347      public function set_maildisplay(int $maildisplay): void {
 348          if (!in_array($maildisplay, range(0, 2))) {
 349              throw new \coding_exception("Invalid maildisplay value '$maildisplay'. Must be in the range {0..2}.");
 350          }
 351          $this->maildisplay = $maildisplay;
 352      }
 353  
 354      /**
 355       * Get the lang code of the user.
 356       *
 357       * @return string the user's language code.
 358       */
 359      public function get_lang(): string {
 360          return $this->lang;
 361      }
 362  
 363      /**
 364       * Set the user's language.
 365       *
 366       * @param string $langcode the language code representing the user's language.
 367       */
 368      public function set_lang(string $langcode): void {
 369          if (empty($langcode)) {
 370              throw new \coding_exception('Invalid lang value. Cannot be an empty string.');
 371          }
 372          $validlangcodes = array_keys(get_string_manager()->get_list_of_translations());
 373          if (!in_array($langcode, $validlangcodes)) {
 374              throw new \coding_exception("Invalid lang '$langcode' provided.");
 375          }
 376          $this->lang = $langcode;
 377      }
 378  
 379      /**
 380       * Get the last grade value for this user.
 381       *
 382       * @return float the float grade.
 383       */
 384      public function get_lastgrade(): float {
 385          return $this->lastgrade;
 386      }
 387  
 388      /**
 389       * Set the last grade for the user.
 390       *
 391       * @param float $lastgrade the last grade the user received.
 392       */
 393      public function set_lastgrade(float $lastgrade): void {
 394          global $CFG;
 395          require_once($CFG->libdir . '/gradelib.php');
 396          $this->lastgrade = grade_floatval($lastgrade);
 397      }
 398  
 399      /**
 400       * Get the last access timestamp for this user.
 401       *
 402       * @return int|null the last access timestampt, or null if the user hasn't accessed the resource.
 403       */
 404      public function get_lastaccess(): ?int {
 405          return $this->lastaccess;
 406      }
 407  
 408      /**
 409       * Set the last access time for the user.
 410       *
 411       * @param int $time unix timestamp representing the last time the user accessed the published resource.
 412       * @throws \coding_exception if $time is not a positive int.
 413       */
 414      public function set_lastaccess(int $time): void {
 415          if ($time < 0) {
 416              throw new \coding_exception('Cannot set negative access time');
 417          }
 418          $this->lastaccess = $time;
 419      }
 420  }