[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 deployment.
  21   *
  22   * This class represents an LTI Advantage Tool Deployment (http://www.imsglobal.org/spec/lti/v1p3/#tool-deployment).
  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 deployment {
  29      /** @var int|null the id of this object instance, or null if it has not been saved yet. */
  30      private $id;
  31  
  32      /** @var string the name of this deployment. */
  33      private $deploymentname;
  34  
  35      /** @var string The platform-issued deployment id. */
  36      private $deploymentid;
  37  
  38      /** @var int the local ID of the application registration to which this deployment belongs. */
  39      private $registrationid;
  40  
  41      /** @var string|null the legacy consumer key, if the deployment instance is migrated from a legacy consumer. */
  42      private $legacyconsumerkey;
  43  
  44      /**
  45       * The private deployment constructor.
  46       *
  47       * @param string $deploymentname the name of this deployment.
  48       * @param string $deploymentid the platform-issued deployment id.
  49       * @param int $registrationid the local ID of the application registration.
  50       * @param int|null $id the id of this object instance, or null if it is a new instance which has not yet been saved.
  51       * @param string|null $legacyconsumerkey the 1.1 consumer key associated with this deployment, used for upgrades.
  52       */
  53      private function __construct(string $deploymentname, string $deploymentid, int $registrationid, ?int $id = null,
  54              ?string $legacyconsumerkey = null) {
  55  
  56          if (!is_null($id) && $id <= 0) {
  57              throw new \coding_exception('id must be a positive int');
  58          }
  59          if (empty($deploymentname)) {
  60              throw new \coding_exception("Invalid 'deploymentname' arg. Cannot be an empty string.");
  61          }
  62          if (empty($deploymentid)) {
  63              throw new \coding_exception("Invalid 'deploymentid' arg. Cannot be an empty string.");
  64          }
  65          $this->deploymentname = $deploymentname;
  66          $this->deploymentid = $deploymentid;
  67          $this->registrationid = $registrationid;
  68          $this->id = $id;
  69          $this->legacyconsumerkey = $legacyconsumerkey;
  70      }
  71  
  72      /**
  73       * Factory method to create a new instance of a deployment.
  74       *
  75       * @param int $registrationid the local ID of the application registration.
  76       * @param string $deploymentid the platform-issued deployment id.
  77       * @param string $deploymentname the name of this deployment.
  78       * @param int|null $id optional local id of this object instance, omitted for new deployment objects.
  79       * @param string|null $legacyconsumerkey the 1.1 consumer key associated with this deployment, used for upgrades.
  80       * @return deployment the deployment instance.
  81       */
  82      public static function create(int $registrationid, string $deploymentid, string $deploymentname,
  83              ?int $id = null, ?string $legacyconsumerkey = null): deployment {
  84          return new self($deploymentname, $deploymentid, $registrationid, $id, $legacyconsumerkey);
  85      }
  86  
  87      /**
  88       * Return the object id.
  89       *
  90       * @return int|null the id.
  91       */
  92      public function get_id(): ?int {
  93          return $this->id;
  94      }
  95  
  96      /**
  97       * Return the short name of this tool deployment.
  98       *
  99       * @return string the short name.
 100       */
 101      public function get_deploymentname(): string {
 102          return $this->deploymentname;
 103      }
 104  
 105      /**
 106       * Get the deployment id string.
 107       *
 108       * @return string deploymentid
 109       */
 110      public function get_deploymentid(): string {
 111          return $this->deploymentid;
 112      }
 113  
 114      /**
 115       * Get the id of the application_registration.
 116       *
 117       * @return int the id of the application_registration instance to which this deployment belongs.
 118       */
 119      public function get_registrationid(): int {
 120          return $this->registrationid;
 121      }
 122  
 123      /**
 124       * Get the legacy consumer key to which this deployment instance is mapped.
 125       *
 126       * @return string|null the legacy consumer key, if set, else null.
 127       */
 128      public function get_legacy_consumer_key(): ?string {
 129          return $this->legacyconsumerkey;
 130      }
 131  
 132      /**
 133       * Factory method to add a platform-specific context to the deployment.
 134       *
 135       * @param string $contextid the contextid, as supplied by the platform during launch.
 136       * @param array $types the context types the context represents, as supplied by the platform during launch.
 137       * @return context the context instance.
 138       * @throws \coding_exception if the context could not be created.
 139       */
 140      public function add_context(string $contextid, array $types): context {
 141          if (!$this->get_id()) {
 142              throw new \coding_exception('Can\'t add context to a deployment that hasn\'t first been saved');
 143          }
 144  
 145          return context::create($this->get_id(), $contextid, $types);
 146      }
 147  
 148      /**
 149       * Factory method to create a resource link from this deployment instance.
 150       *
 151       * @param string $resourcelinkid the platform-issued string id of the resource link.
 152       * @param int $resourceid the local published resource to which this link points.
 153       * @param int|null $contextid the platform context instance in which the resource link resides, if available.
 154       * @return resource_link the resource_link instance.
 155       * @throws \coding_exception if the resource_link can't be created.
 156       */
 157      public function add_resource_link(string $resourcelinkid, int $resourceid,
 158              int $contextid = null): resource_link {
 159  
 160          if (!$this->get_id()) {
 161              throw new \coding_exception('Can\'t add resource_link to a deployment that hasn\'t first been saved');
 162          }
 163          return resource_link::create($resourcelinkid, $this->get_id(), $resourceid, $contextid);
 164      }
 165  
 166      /**
 167       * Set the legacy consumer key for this instance, indicating that the deployment has been migrated from a consumer.
 168       *
 169       * @param string $key the legacy consumer key.
 170       * @throws \coding_exception if the key is invalid.
 171       */
 172      public function set_legacy_consumer_key(string $key): void {
 173          if (strlen($key) > 255) {
 174              throw new \coding_exception('Legacy consumer key too long. Cannot exceed 255 chars.');
 175          }
 176          $this->legacyconsumerkey = $key;
 177      }
 178  }