[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 resource_link.
  21   *
  22   * This class represents an LTI Advantage Resource Link (http://www.imsglobal.org/spec/lti/v1p3/#resource-link).
  23   *
  24   * @package    enrol_lti
  25   * @copyright 2021 Jake Dallimore <jrhdallimore@gmail.com>
  26   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  27   */
  28  class resource_link {
  29  
  30      /** @var int|null the id of this object, or null if the object hasn't been stored yet. */
  31      private $id;
  32  
  33      /** @var string resourcelinkid the id of the resource link as supplied by the platform. */
  34      private $resourcelinkid;
  35  
  36      /** @var int $deploymentid the local id of the deployment instance to which this resource link belongs. */
  37      private $deploymentid;
  38  
  39      /** @var int|null $contextid the id of local context object representing the platform context, or null. */
  40      private $contextid;
  41  
  42      /** @var int The id of the local published resource this resource_link points to. */
  43      private $resourceid;
  44  
  45      /** @var ags_info|null the grade service for this resource_link, null if not applicable/not provided. */
  46      private $gradeservice;
  47  
  48      /** @var nrps_info|null the names and roles service for this resource_link, null if not applicable/not provided. */
  49      private $namesrolesservice;
  50  
  51      /**
  52       * The private resource_link constructor.
  53       *
  54       * @param string $resourcelinkid the id of the resource link as supplied by the platform.
  55       * @param int $deploymentid the local id of the deployment instance to which this resource link belongs.
  56       * @param int $resourceid the id of the local resource to which this link refers.
  57       * @param int|null $contextid the id local context object representing the context within the platform.
  58       * @param int|null $id the local id of this resource_link object.
  59       * @throws \coding_exception if the instance is unable to be created.
  60       */
  61      private function __construct(string $resourcelinkid, int $deploymentid, int $resourceid, ?int $contextid = null,
  62              int $id = null) {
  63  
  64          if (empty($resourcelinkid)) {
  65              throw new \coding_exception('Error: resourcelinkid cannot be an empty string');
  66          }
  67          $this->resourcelinkid = $resourcelinkid;
  68          $this->deploymentid = $deploymentid;
  69          $this->resourceid = $resourceid;
  70          $this->contextid = $contextid;
  71          $this->id = $id;
  72          $this->gradeservice = null;
  73          $this->namesrolesservice = null;
  74      }
  75  
  76      /**
  77       * Factory method to create an instance.
  78       *
  79       * @param string $resourcelinkid the resourcelinkid, as provided by the platform.
  80       * @param int $deploymentid the local id of the deployment to which this resource link belongs.
  81       * @param int $resourceid the id of the local resource this resource_link refers to.
  82       * @param int|null $contextid the id of the local context object representing the platform context.
  83       * @param int|null $id the local id of the resource link instance.
  84       * @return resource_link the newly created instance.
  85       */
  86      public static function create(string $resourcelinkid, int $deploymentid, int $resourceid, ?int $contextid = null,
  87              int $id = null): resource_link {
  88  
  89          return new self($resourcelinkid, $deploymentid, $resourceid, $contextid, $id);
  90      }
  91  
  92      /**
  93       * Return the id of this object instance.
  94       *
  95       * @return null|int the id or null if the object has not yet been stored.
  96       */
  97      public function get_id(): ?int {
  98          return $this->id;
  99      }
 100  
 101      /**
 102       * Get the resourcelinkid as provided by the platform.
 103       *
 104       * @return string the resourcelinkid.
 105       */
 106      public function get_resourcelinkid(): string {
 107          return $this->resourcelinkid;
 108      }
 109  
 110      /**
 111       * Return the id of the deployment to which this resource link belongs.
 112       *
 113       * This id is the local id of the deployment instance, not the deploymentid provided by the platform.
 114       *
 115       * @return int the deployment id.
 116       */
 117      public function get_deploymentid(): int {
 118          return $this->deploymentid;
 119      }
 120  
 121      /**
 122       * Get the local id of the published resource to which this resource link refers.
 123       *
 124       * @return int the id of the published resource.
 125       */
 126      public function get_resourceid(): int {
 127          return $this->resourceid;
 128      }
 129  
 130      /**
 131       * Return the id of the context object holding information about where this resource link resides.
 132       *
 133       * @return int|null the id or null if not present.
 134       */
 135      public function get_contextid(): ?int {
 136          return $this->contextid;
 137      }
 138  
 139      /**
 140       * Link this resource_link instance with a context.
 141       *
 142       * @param int $contextid the local id of the context instance containing information about the platform context.
 143       */
 144      public function set_contextid(int $contextid): void {
 145          if ($contextid <= 0) {
 146              throw new \coding_exception('Context id must be a positive int');
 147          }
 148          $this->contextid = $contextid;
 149      }
 150  
 151      /**
 152       * Set which local published resource this resource link refers to.
 153       *
 154       * @param int $resourceid the published resource id.
 155       */
 156      public function set_resourceid(int $resourceid): void {
 157          if ($resourceid <= 0) {
 158              throw new \coding_exception('Resource id must be a positive int');
 159          }
 160          $this->resourceid = $resourceid;
 161      }
 162  
 163      /**
 164       * Add grade service information to this resource_link instance.
 165       *
 166       * @param \moodle_url|null $lineitemsurl the service URL for get/put of line items, if supported.
 167       * @param \moodle_url|null $lineitemurl the service URL if only a single line item is present in the platform.
 168       * @param string[] $scopes the string array of grade service scopes which may be used by the service.
 169       */
 170      public function add_grade_service(?\moodle_url $lineitemsurl = null, ?\moodle_url $lineitemurl = null, array $scopes = []) {
 171          $this->gradeservice = ags_info::create($lineitemsurl, $lineitemurl, $scopes);
 172      }
 173  
 174      /**
 175       * Get the grade service attached to this resource_link instance, or null if there isn't one associated.
 176       *
 177       * @return ags_info|null the grade service object instance, or null if not found.
 178       */
 179      public function get_grade_service(): ?ags_info {
 180          return $this->gradeservice;
 181      }
 182  
 183      /**
 184       * Add names and roles service information to this resource_link instance.
 185       *
 186       * @param \moodle_url $contextmembershipurl the service URL for memberships.
 187       * @param string[] $serviceversions the string array of supported service versions.
 188       */
 189      public function add_names_and_roles_service(\moodle_url $contextmembershipurl, array $serviceversions): void {
 190          $this->namesrolesservice = nrps_info::create($contextmembershipurl, $serviceversions);
 191      }
 192  
 193      /**
 194       * Get the names and roles service attached to this resource_link instance, or null if there isn't one associated.
 195       *
 196       * @return nrps_info|null the names and roles service object instance, or null if not found.
 197       */
 198      public function get_names_and_roles_service(): ?nrps_info {
 199          return $this->namesrolesservice;
 200      }
 201  
 202      /**
 203       * Factory method to create a user from this resource_link instance.
 204       *
 205       * This is useful for associating the user with the resource link and resource I.e. the user was created when
 206       * launching a specific resource link.
 207       *
 208       * @param int $userid the id of the Moodle user record.
 209       * @param string $sourceid the id of the user on the platform.
 210       * @param string $lang the user's lang code.
 211       * @param string $city the user's city.
 212       * @param string $country the user's country.
 213       * @param string $institution the user's institution.
 214       * @param string $timezone the user's timezone.
 215       * @param int|null $maildisplay the user's maildisplay, which can be omitted to use sensible defaults.
 216       * @return user the user instance.
 217       * @throws \coding_exception if trying to add a user to an as-yet-unsaved resource_link instance.
 218       */
 219      public function add_user(int $userid, string $sourceid, string $lang,
 220              string $city, string $country, string $institution, string $timezone,
 221              ?int $maildisplay = null): user {
 222  
 223          if (empty($this->get_id())) {
 224              throw new \coding_exception('Can\'t add user to a resource_link that hasn\'t first been saved');
 225          }
 226  
 227          return user::create_from_resource_link($this->get_id(), $this->get_resourceid(), $userid,
 228              $this->get_deploymentid(), $sourceid, $lang, $timezone, $city, $country,
 229              $institution, $maildisplay);
 230      }
 231  }