[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 context, instances of which represent a context in the platform.
  21   *
  22   * See: http://www.imsglobal.org/spec/lti/v1p3/#context-type-vocabulary for supported context types.
  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  class context {
  28  
  29      // The following full contexts are per the spec:
  30      // http://www.imsglobal.org/spec/lti/v1p3/#context-type-vocabulary.
  31      /** @var string course template context */
  32      private const CONTEXT_TYPE_COURSE_TEMPLATE = 'http://purl.imsglobal.org/vocab/lis/v2/course#CourseTemplate';
  33  
  34      /** @var string course offering context */
  35      private const CONTEXT_TYPE_COURSE_OFFERING = 'http://purl.imsglobal.org/vocab/lis/v2/course#CourseOffering';
  36  
  37      /** @var string course section context */
  38      private const CONTEXT_TYPE_COURSE_SECTION = 'http://purl.imsglobal.org/vocab/lis/v2/course#CourseSection';
  39  
  40      /** @var string group context */
  41      private const CONTEXT_TYPE_GROUP = 'http://purl.imsglobal.org/vocab/lis/v2/course#Group';
  42  
  43      // The following simple names are deprecated but are still supported in 1.3 for backwards compatibility.
  44      // http://www.imsglobal.org/spec/lti/v1p3/#context-type-vocabulary.
  45      /** @var string deprecated simple course template context */
  46      private const LEGACY_CONTEXT_TYPE_COURSE_TEMPLATE = 'CourseTemplate';
  47  
  48      /** @var string deprecated simple course offering context */
  49      private const LEGACY_CONTEXT_TYPE_COURSE_OFFERING = 'CourseOffering';
  50  
  51      /** @var string deprecated simple course section context */
  52      private const LEGACY_CONTEXT_TYPE_COURSE_SECTION = 'CourseSection';
  53  
  54      /** @var string deprecated simple group context */
  55      private const LEGACY_CONTEXT_TYPE_GROUP = 'Group';
  56  
  57      /** @var int the local id of the deployment instance to which this context belongs. */
  58      private $deploymentid;
  59  
  60      /** @var string the contextid as supplied by the platform. */
  61      private $contextid;
  62  
  63      /** @var int|null the local id of this object instance, which can be null if the object hasn't been stored before */
  64      private $id;
  65  
  66      /** @var string[] the array of context types */
  67      private $types;
  68  
  69      /**
  70       * Private constructor.
  71       *
  72       * @param int $deploymentid the local id of the deployment instance to which this context belongs.
  73       * @param string $contextid the context id string, as provided by the platform during launch.
  74       * @param array $types an array of string context types, as provided by the platform during launch.
  75       * @param int|null $id local id of this object instance, nullable for new objects.
  76       */
  77      private function __construct(int $deploymentid, string $contextid, array $types, ?int $id) {
  78          if (!is_null($id) && $id <= 0) {
  79              throw new \coding_exception('id must be a positive int');
  80          }
  81          $this->deploymentid = $deploymentid;
  82          $this->contextid = $contextid;
  83          $this->set_types($types); // Handles type validation.
  84          $this->id = $id;
  85      }
  86  
  87      /**
  88       * Factory method for creating a context instance.
  89       *
  90       * @param int $deploymentid the local id of the deployment instance to which this context belongs.
  91       * @param string $contextid the context id string, as provided by the platform during launch.
  92       * @param array $types an array of string context types, as provided by the platform during launch.
  93       * @param int|null $id local id of this object instance, nullable for new objects.
  94       * @return context the context instance.
  95       */
  96      public static function create(int $deploymentid, string $contextid, array $types, int $id = null): context {
  97          return new self($deploymentid, $contextid, $types, $id);
  98      }
  99  
 100      /**
 101       * Check whether a context is valid or not, checking also deprecated but supported legacy context names.
 102       *
 103       * @param string $type context type to check.
 104       * @param bool $includelegacy whether to check the legacy simple context names too.
 105       * @return bool true if the type is valid, false otherwise.
 106       */
 107      private function is_valid_type(string $type, bool $includelegacy = false): bool {
 108          // Check LTI Advantage types.
 109          $valid = in_array($type, [
 110              self::CONTEXT_TYPE_COURSE_TEMPLATE,
 111              self::CONTEXT_TYPE_COURSE_OFFERING,
 112              self::CONTEXT_TYPE_COURSE_SECTION,
 113              self::CONTEXT_TYPE_GROUP
 114          ]);
 115  
 116          // Check legacy short names.
 117          if ($includelegacy) {
 118              $valid = $valid || in_array($type, [
 119                  self::LEGACY_CONTEXT_TYPE_COURSE_TEMPLATE,
 120                  self::LEGACY_CONTEXT_TYPE_COURSE_OFFERING,
 121                  self::LEGACY_CONTEXT_TYPE_COURSE_SECTION,
 122                  self::LEGACY_CONTEXT_TYPE_GROUP
 123              ]);
 124          }
 125  
 126          return $valid;
 127      }
 128  
 129      /**
 130       * Get the object instance id.
 131       *
 132       * @return int|null the id, or null if the object doesn't yet have one assigned.
 133       */
 134      public function get_id(): ?int {
 135          return $this->id;
 136      }
 137  
 138      /**
 139       * Return the platform contextid string.
 140       *
 141       * @return string the id of the context in the platform.
 142       */
 143      public function get_contextid(): string {
 144          return $this->contextid;
 145      }
 146  
 147      /**
 148       * Get the id of the local deployment instance to which this context instance belongs.
 149       *
 150       * @return int the id of the local deployment instance to which this context instance belongs.
 151       */
 152      public function get_deploymentid(): int {
 153          return $this->deploymentid;
 154      }
 155  
 156      /**
 157       * Get the context types this context instance represents.
 158       *
 159       * @return string[] the array of context types this context instance represents.
 160       */
 161      public function get_types(): array {
 162          return $this->types;
 163      }
 164  
 165      /**
 166       * Set the list of types this context instance represents.
 167       *
 168       * @param array $types the array of string types.
 169       * @throws \coding_exception if any of the supplied types are invalid.
 170       */
 171      public function set_types(array $types): void {
 172          foreach ($types as $type) {
 173              if (!$this->is_valid_type($type, true)) {
 174                  throw new \coding_exception("Cannot set invalid context type '{$type}'.");
 175              }
 176          }
 177          $this->types = $types;
 178      }
 179  }