[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 nrps_info, instances of which represent a names and roles provisioning service for a resource.
  21   *
  22   * For information about Names and Role Provisioning Services 2.0, see http://www.imsglobal.org/spec/lti-nrps/v2p0.
  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 nrps_info {
  28  
  29      /** @var \moodle_url the memberships URL for the service. */
  30      private $contextmembershipsurl;
  31  
  32      /** @var float[] the array of supported service versions. */
  33      private $serviceversions;
  34  
  35      // Service versions are specified by the platform during launch.
  36      // See http://www.imsglobal.org/spec/lti-nrps/v2p0#lti-1-3-integration.
  37      /** @var string version 1.0 */
  38      private const SERVICE_VERSION_1 = '1.0';
  39  
  40      /** @var string version 2.0 */
  41      private const SERVICE_VERSION_2 = '2.0';
  42  
  43      // Scope that must be requested as part of making a service call.
  44      // See: http://www.imsglobal.org/spec/lti-nrps/v2p0#lti-1-3-integration.
  45      /** @var string the scope to request to make service calls. */
  46      private $servicescope = 'https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly';
  47  
  48      /**
  49       * The private nrps_info constructor.
  50       *
  51       * @param \moodle_url $contextmembershipsurl the memberships URL.
  52       * @param string[] $serviceversions the supported service versions.
  53       */
  54      private function __construct(\moodle_url $contextmembershipsurl, array $serviceversions = [self::SERVICE_VERSION_2]) {
  55          $this->contextmembershipsurl = $contextmembershipsurl;
  56          $this->set_service_versions($serviceversions);
  57      }
  58  
  59      /**
  60       * Factory method to create a new nrps_info instance.
  61       *
  62       * @param \moodle_url $contextmembershipsurl the memberships URL.
  63       * @param string[] $serviceversions the supported service versions.
  64       * @return nrps_info the object instance.
  65       */
  66      public static function create(\moodle_url $contextmembershipsurl,
  67              array $serviceversions = [self::SERVICE_VERSION_2]): nrps_info {
  68          return new self($contextmembershipsurl, $serviceversions);
  69      }
  70  
  71      /**
  72       * Check whether the supplied service version is valid or not.
  73       *
  74       * @param string $serviceversion the service version to check.
  75       * @return bool true if valid, false otherwise.
  76       */
  77      private function is_valid_service_version(string $serviceversion): bool {
  78          $validversions = [
  79              self::SERVICE_VERSION_1,
  80              self::SERVICE_VERSION_2
  81          ];
  82  
  83          return in_array($serviceversion, $validversions);
  84      }
  85  
  86      /**
  87       * Tries to set the supported service versions for this instance.
  88       *
  89       * @param array $serviceversions the service versions to set.
  90       * @throws \coding_exception if any of the supplied versions are not valid.
  91       */
  92      private function set_service_versions(array $serviceversions): void {
  93          if (empty($serviceversions)) {
  94              throw new \coding_exception('Service versions array cannot be empty');
  95          }
  96          $serviceversions = array_unique($serviceversions);
  97          foreach ($serviceversions as $serviceversion) {
  98              if (!$this->is_valid_service_version($serviceversion)) {
  99                  throw new \coding_exception("Invalid Names and Roles service version '{$serviceversion}'");
 100              }
 101          }
 102          $this->serviceversions = $serviceversions;
 103      }
 104  
 105      /**
 106       * Get the service URL for this grade service instance.
 107       *
 108       * @return \moodle_url the service URL.
 109       */
 110      public function get_context_memberships_url(): \moodle_url {
 111          return $this->contextmembershipsurl;
 112      }
 113  
 114      /**
 115       * Get the supported service versions for this grade service instance.
 116       *
 117       * @return string[] the array of supported service versions.
 118       */
 119      public function get_service_versions(): array {
 120          return $this->serviceversions;
 121      }
 122  
 123      /**
 124       * Get the nrps service scope.
 125       *
 126       * @return string the service scope.
 127       */
 128      public function get_service_scope(): string {
 129          return $this->servicescope;
 130      }
 131  }