Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

   1  <?php
   2  /**
   3   * Copyright 2010 Google Inc.
   4   *
   5   * Licensed under the Apache License, Version 2.0 (the "License");
   6   * you may not use this file except in compliance with the License.
   7   * You may obtain a copy of the License at
   8   *
   9   *     http://www.apache.org/licenses/LICENSE-2.0
  10   *
  11   * Unless required by applicable law or agreed to in writing, software
  12   * distributed under the License is distributed on an "AS IS" BASIS,
  13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14   * See the License for the specific language governing permissions and
  15   * limitations under the License.
  16   */
  17  
  18  if (!class_exists('Google_Client')) {
  19    require_once dirname(__FILE__) . '/../autoload.php';
  20  }
  21  
  22  /**
  23   * Implements the actual methods/resources of the discovered Google API using magic function
  24   * calling overloading (__call()), which on call will see if the method name (plus.activities.list)
  25   * is available in this service, and if so construct an apiHttpRequest representing it.
  26   *
  27   */
  28  class Google_Service_Resource
  29  {
  30    // Valid query parameters that work, but don't appear in discovery.
  31    private $stackParameters = array(
  32        'alt' => array('type' => 'string', 'location' => 'query'),
  33        'fields' => array('type' => 'string', 'location' => 'query'),
  34        'trace' => array('type' => 'string', 'location' => 'query'),
  35        'userIp' => array('type' => 'string', 'location' => 'query'),
  36        'quotaUser' => array('type' => 'string', 'location' => 'query'),
  37        'data' => array('type' => 'string', 'location' => 'body'),
  38        'mimeType' => array('type' => 'string', 'location' => 'header'),
  39        'uploadType' => array('type' => 'string', 'location' => 'query'),
  40        'mediaUpload' => array('type' => 'complex', 'location' => 'query'),
  41        'prettyPrint' => array('type' => 'string', 'location' => 'query'),
  42    );
  43  
  44    /** @var string $rootUrl */
  45    private $rootUrl;
  46  
  47    /** @var Google_Client $client */
  48    private $client;
  49  
  50    /** @var string $serviceName */
  51    private $serviceName;
  52  
  53    /** @var string $servicePath */
  54    private $servicePath;
  55  
  56    /** @var string $resourceName */
  57    private $resourceName;
  58  
  59    /** @var array $methods */
  60    private $methods;
  61  
  62    public function __construct($service, $serviceName, $resourceName, $resource)
  63    {
  64      $this->rootUrl = $service->rootUrl;
  65      $this->client = $service->getClient();
  66      $this->servicePath = $service->servicePath;
  67      $this->serviceName = $serviceName;
  68      $this->resourceName = $resourceName;
  69      $this->methods = is_array($resource) && isset($resource['methods']) ?
  70          $resource['methods'] :
  71          array($resourceName => $resource);
  72    }
  73  
  74    /**
  75     * TODO: This function needs simplifying.
  76     * @param $name
  77     * @param $arguments
  78     * @param $expected_class - optional, the expected class name
  79     * @return Google_Http_Request|expected_class
  80     * @throws Google_Exception
  81     */
  82    public function call($name, $arguments, $expected_class = null)
  83    {
  84      if (! isset($this->methods[$name])) {
  85        $this->client->getLogger()->error(
  86            'Service method unknown',
  87            array(
  88                'service' => $this->serviceName,
  89                'resource' => $this->resourceName,
  90                'method' => $name
  91            )
  92        );
  93  
  94        throw new Google_Exception(
  95            "Unknown function: " .
  96            "{$this->serviceName}->{$this->resourceName}->{$name}()"
  97        );
  98      }
  99      $method = $this->methods[$name];
 100      $parameters = $arguments[0];
 101  
 102      // postBody is a special case since it's not defined in the discovery
 103      // document as parameter, but we abuse the param entry for storing it.
 104      $postBody = null;
 105      if (isset($parameters['postBody'])) {
 106        if ($parameters['postBody'] instanceof Google_Model) {
 107          // In the cases the post body is an existing object, we want
 108          // to use the smart method to create a simple object for
 109          // for JSONification.
 110          $parameters['postBody'] = $parameters['postBody']->toSimpleObject();
 111        } else if (is_object($parameters['postBody'])) {
 112          // If the post body is another kind of object, we will try and
 113          // wrangle it into a sensible format.
 114          $parameters['postBody'] =
 115              $this->convertToArrayAndStripNulls($parameters['postBody']);
 116        }
 117        $postBody = json_encode($parameters['postBody']);
 118        if ($postBody === false && $parameters['postBody'] !== false) {
 119          throw new Google_Exception("JSON encoding failed. Ensure all strings in the request are UTF-8 encoded.");
 120        }
 121        unset($parameters['postBody']);
 122      }
 123  
 124      // TODO: optParams here probably should have been
 125      // handled already - this may well be redundant code.
 126      if (isset($parameters['optParams'])) {
 127        $optParams = $parameters['optParams'];
 128        unset($parameters['optParams']);
 129        $parameters = array_merge($parameters, $optParams);
 130      }
 131  
 132      if (!isset($method['parameters'])) {
 133        $method['parameters'] = array();
 134      }
 135  
 136      $method['parameters'] = array_merge(
 137          $this->stackParameters,
 138          $method['parameters']
 139      );
 140      foreach ($parameters as $key => $val) {
 141        if ($key != 'postBody' && ! isset($method['parameters'][$key])) {
 142          $this->client->getLogger()->error(
 143              'Service parameter unknown',
 144              array(
 145                  'service' => $this->serviceName,
 146                  'resource' => $this->resourceName,
 147                  'method' => $name,
 148                  'parameter' => $key
 149              )
 150          );
 151          throw new Google_Exception("($name) unknown parameter: '$key'");
 152        }
 153      }
 154  
 155      foreach ($method['parameters'] as $paramName => $paramSpec) {
 156        if (isset($paramSpec['required']) &&
 157            $paramSpec['required'] &&
 158            ! isset($parameters[$paramName])
 159        ) {
 160          $this->client->getLogger()->error(
 161              'Service parameter missing',
 162              array(
 163                  'service' => $this->serviceName,
 164                  'resource' => $this->resourceName,
 165                  'method' => $name,
 166                  'parameter' => $paramName
 167              )
 168          );
 169          throw new Google_Exception("($name) missing required param: '$paramName'");
 170        }
 171        if (isset($parameters[$paramName])) {
 172          $value = $parameters[$paramName];
 173          $parameters[$paramName] = $paramSpec;
 174          $parameters[$paramName]['value'] = $value;
 175          unset($parameters[$paramName]['required']);
 176        } else {
 177          // Ensure we don't pass nulls.
 178          unset($parameters[$paramName]);
 179        }
 180      }
 181  
 182      $this->client->getLogger()->info(
 183          'Service Call',
 184          array(
 185              'service' => $this->serviceName,
 186              'resource' => $this->resourceName,
 187              'method' => $name,
 188              'arguments' => $parameters,
 189          )
 190      );
 191  
 192      $url = Google_Http_REST::createRequestUri(
 193          $this->servicePath,
 194          $method['path'],
 195          $parameters
 196      );
 197      $httpRequest = new Google_Http_Request(
 198          $url,
 199          $method['httpMethod'],
 200          null,
 201          $postBody
 202      );
 203  
 204      if ($this->rootUrl) {
 205        $httpRequest->setBaseComponent($this->rootUrl);
 206      } else {
 207        $httpRequest->setBaseComponent($this->client->getBasePath());
 208      }
 209  
 210      if ($postBody) {
 211        $contentTypeHeader = array();
 212        $contentTypeHeader['content-type'] = 'application/json; charset=UTF-8';
 213        $httpRequest->setRequestHeaders($contentTypeHeader);
 214        $httpRequest->setPostBody($postBody);
 215      }
 216  
 217      $httpRequest = $this->client->getAuth()->sign($httpRequest);
 218      $httpRequest->setExpectedClass($expected_class);
 219  
 220      if (isset($parameters['data']) &&
 221          ($parameters['uploadType']['value'] == 'media' || $parameters['uploadType']['value'] == 'multipart')) {
 222        // If we are doing a simple media upload, trigger that as a convenience.
 223        $mfu = new Google_Http_MediaFileUpload(
 224            $this->client,
 225            $httpRequest,
 226            isset($parameters['mimeType']) ? $parameters['mimeType']['value'] : 'application/octet-stream',
 227            $parameters['data']['value']
 228        );
 229      }
 230  
 231      if (isset($parameters['alt']) && $parameters['alt']['value'] == 'media') {
 232        $httpRequest->enableExpectedRaw();
 233      }
 234  
 235      if ($this->client->shouldDefer()) {
 236        // If we are in batch or upload mode, return the raw request.
 237        return $httpRequest;
 238      }
 239  
 240      return $this->client->execute($httpRequest);
 241    }
 242  
 243    protected function convertToArrayAndStripNulls($o)
 244    {
 245      $o = (array) $o;
 246      foreach ($o as $k => $v) {
 247        if ($v === null) {
 248          unset($o[$k]);
 249        } elseif (is_object($v) || is_array($v)) {
 250          $o[$k] = $this->convertToArrayAndStripNulls($o[$k]);
 251        }
 252      }
 253      return $o;
 254    }
 255  }