Merge pull request #46 from ianbarber/master

silvolu · silvolu · commit 0450aec07528 · 2014-01-21T13:34:01.000-08:00
URITemplate level 4 and README/Version update
diff --git a/README.md b/README.md
@@ -28,6 +28,26 @@ See the examples/ directory for examples of the key client features.
   }
 ```
 
+## Frequently Asked Questions ##
+
+### What do I do if something isn't woring? ###
+
+For support with the library the best place to ask is via the  google-api-php-client tag on StackOverflow: http://stackoverflow.com/questions/tagged/google-api-php-client
+
+If there is a specific bug with the library, please file a issue in the Github issues tracker, including a (minimal) example of the failing code and any specific errors retrieved. Feature requests can also be filed, as long as they are core library requests, and not-API specific: for those, refer to the documentation for the individual APIs for the best place to file requests. Please try to provide a clear statement of the problem that the feature would address.
+
+### How do I contribute? ###
+
+We accept contributions via Github Pull Requests, but all contributors need to be covered by the standard Google Contributor License Agreement. You can find links, and more instructions, in the documentation: https://developers.google.com/api-client-library/php/contribute
+
+### Why do you still support 5.2? ###
+
+When we started working on the 1.0.0 branch we knew there were several fundamental issues to fix with the 0.6 releases of the library. At that time we looked at the usage of the library, and other related projects, and determined that there was still a large and active base of PHP 5.2 installs. You can see this in statistics such as the PHP versions chart in the Wordpress stats: http://wordpress.org/about/stats/. We will keep looking at the types of usage we see, and try to take advantage of newer PHP features where possible.
+
+### Why does Google_..._Service have weird names? ###
+
+The _Service classes are generally automatically generated from the API discovery documents: https://developers.google.com/discovery/. Sometimes new features are added to APIs with unusual names, which can cause some unexpected or non-standard style naming in the PHP classes. 
+
 ## Code Quality ##
 
 Copy the ruleset.xml in style/ into a new directory named GAPI/ in your
diff --git a/src/Google/Client.php b/src/Google/Client.php
@@ -35,7 +35,7 @@
  */
 class Google_Client
 {
-  const LIBVER = "1.0.1-alpha";
+  const LIBVER = "1.0.1-beta";
   const USER_AGENT_SUFFIX = "google-api-php-client/";
   const GZIP_UA = " (gzip)";
   /**
diff --git a/src/Google/Utils/URITemplate.php b/src/Google/Utils/URITemplate.php
@@ -21,6 +21,10 @@
  */
 class Google_Utils_URITemplate
 {
+  const TYPE_MAP = "1";
+  const TYPE_LIST = "2";
+  const TYPE_SCALAR = "4";
+
   /**
    * @var $operators array 
    * These are valid at the start of a template block to
@@ -86,36 +90,53 @@ private function replace($string, $start, $end, $parameters)
     if (isset($this->operators[$data[0]])) {
       $op = $this->operators[$data[0]];
       $data = substr($data, 1);
+      $prefix = "";
+      $prefix_on_missing = false;
+
       switch ($op) {
         case "reserved":
           // Reserved means certain characters should not be URL encoded
           $data = $this->replaceVars($data, $parameters, ",", null, true);
           break;
         case "fragment":
           // Comma separated with fragment prefix. Bare values only.
-          $data = "#" . $this->replaceVars($data, $parameters, ",", null, true);
+          $prefix = "#";
+          $prefix_on_missing = true;
+          $data = $this->replaceVars($data, $parameters, ",", null, true);
           break;
         case "segments":
           // Slash separated data. Bare values only.
-          $data = "/" . $this->replaceVars($data, $parameters, "/");
+          $prefix = "/";
+          $data =$this->replaceVars($data, $parameters, "/");
           break;
         case "dotprefix":
           // Dot separated data. Bare values only.
-          $data = "." . $this->replaceVars($data, $parameters, ".");
+          $prefix = ".";
+          $prefix_on_missing = true;
+          $data = $this->replaceVars($data, $parameters, ".");
           break;
         case "semicolon":
           // Semicolon prefixed and separated. Uses the key name
-          $data = ";" . $this->replaceVars($data, $parameters, ";", "=", false, true);
+          $prefix = ";";
+          $data = $this->replaceVars($data, $parameters, ";", "=", false, true, false);
           break;
         case "form":
           // Standard URL format. Uses the key name
-          $data = "?" . $this->replaceVars($data, $parameters, "&", "=");
+          $prefix = "?";
+          $data = $this->replaceVars($data, $parameters, "&", "=");
           break;
         case "continuation":
           // Standard URL, but with leading ampersand. Uses key name.
-          $data = "&" . $this->replaceVars($data, $parameters, "&", "=");
+          $prefix = "&";
+          $data = $this->replaceVars($data, $parameters, "&", "=");
           break;
       }
+
+      // Add the initial prefix character if data is valid.
+      if ($data || ($data !== false && $prefix_on_missing)) {
+        $data = $prefix . $data;
+      }
+
     } else {
       // If no operator we replace with the defaults.
       $data = $this->replaceVars($data, $parameters);
@@ -130,45 +151,183 @@ private function replaceVars(
       $sep = ",",
       $combine = null,
       $reserved = false,
-      $tag_empty = false
+      $tag_empty = false,
+      $combine_on_empty = true
   ) {
     if (strpos($section, ",") === false) {
       // If we only have a single value, we can immediately process.
-      return $this->combine($section, $parameters, $combine, $reserved, $tag_empty);
+      return $this->combine(
+          $section,
+          $parameters,
+          $sep,
+          $combine,
+          $reserved,
+          $tag_empty,
+          $combine_on_empty
+      );
     } else {
       // If we have multiple values, we need to split and loop over them.
       // Each is treated individually, then glued together with the
       // separator character.
       $vars = explode(",", $section);
-      $ret = array();
-      foreach ($vars as $var) {
-        $ret[] = $this->combine($var, $parameters, $combine, $reserved, $tag_empty);
-      }
-      return implode($sep, $ret);
+      return $this->combineList(
+          $vars,
+          $sep,
+          $parameters,
+          $combine,
+          $reserved,
+          false, // Never emit empty strings in multi-param replacements
+          $combine_on_empty
+      );
     }
   }
+ 
+  public function combine(
+      $key,
+      $parameters,
+      $sep,
+      $combine,
+      $reserved,
+      $tag_empty,
+      $combine_on_empty
+  ) {
+    $length = false;
+    $explode = false;
+    $skip_final_combine = false;
+    $value = false;
 
-  public function combine($key, $parameters, $combine, $reserved, $tag_empty)
-  {
-    if (!empty($parameters[$key])) {
-      // For an individual value, we need to URL encode the data.
-      $value = rawurlencode($parameters[$key]);
+    // Check for length restriction.
+    if (strpos($key, ":") !== false) {
+      list($key, $length) = explode(":", $key);
+    }
+    
+    // Check for explode parameter.
+    if ($key[strlen($key) - 1] == "*") {
+      $explode = true;
+      $key = substr($key, 0, -1);
+      $skip_final_combine = true;
+    }
+    
+    // Define the list separator.
+    $list_sep = $explode ? $sep : ",";
+    
+    if (isset($parameters[$key])) {
+      $data_type = $this->getDataType($parameters[$key]);
+      switch($data_type) {
+        case self::TYPE_SCALAR:
+          $value = $this->getValue($parameters[$key], $length);
+          break;
+        case self::TYPE_LIST:
+          $values = array();
+          foreach ($parameters[$key] as $pkey => $pvalue) {
+            $pvalue = $this->getValue($pvalue, $length);
+            if ($combine && $explode) {
+              $values[$pkey] = $key . $combine . $pvalue;
+            } else {
+              $values[$pkey] = $pvalue;
+            }
+          }
+          $value = implode($list_sep, $values);
+          if ($value == '') {
+            return '';
+          }
+          break;
+        case self::TYPE_MAP:
+          $values = array();
+          foreach ($parameters[$key] as $pkey => $pvalue) {
+            $pvalue = $this->getValue($pvalue, $length);
+            if ($explode) {
+              $pkey = $this->getValue($pkey, $length);
+              $values[] = $pkey . "=" . $pvalue; // Explode triggers = combine.
+            } else {
+              $values[] = $pkey;
+              $values[] = $pvalue;
+            }
+          }
+          $value = implode($list_sep, $values);
+          if ($value == '') {
+            return false;
+          }
+          break;
+      }
     } else if ($tag_empty) {
       // If we are just indicating empty values with their key name, return that.
       return $key;
     } else {
-      // Otherwise we can return empty string.
-      $value = "";
+      // Otherwise we can skip this variable due to not being defined.
+      return false;
     }
+
     if ($reserved) {
       $value = str_replace($this->reservedEncoded, $this->reserved, $value);
     }
+
     // If we do not need to include the key name, we just return the raw
     // value.
-    if (!$combine) {
+    if (!$combine || $skip_final_combine) {
       return $value;
     }
-    // Else we combine the key name: foo=bar
-    return $key . $combine . $value;
+        
+    // Else we combine the key name: foo=bar, if value is not the empty string.
+    return $key . ($value != '' || $combine_on_empty ? $combine . $value : '');
+  }
+  
+  /**
+   * Return the type of a passed in value
+   */
+  private function getDataType($data)
+  {
+    if (is_array($data)) {
+      reset($data);
+      if (key($data) !== 0) {
+        return self::TYPE_MAP;
+      }
+      return self::TYPE_LIST;
+    }
+    return self::TYPE_SCALAR;
+  }
+  
+  /**
+   * Utility function that merges multiple combine calls
+   * for multi-key templates.
+   */
+  private function combineList(
+      $vars,
+      $sep,
+      $parameters,
+      $combine,
+      $reserved,
+      $tag_empty,
+      $combine_on_empty
+  ) {
+    $ret = array();
+    foreach ($vars as $var) {
+      $response = $this->combine(
+          $var,
+          $parameters,
+          $sep,
+          $combine,
+          $reserved,
+          $tag_empty,
+          $combine_on_empty
+      );
+      if ($response === false) {
+        continue;
+      }
+      $ret[] = $response;
+    }
+    return implode($sep, $ret);
+  }
+  
+  /**
+   * Utility function to encode and trim values
+   */
+  private function getValue($value, $length)
+  {
+    if ($length) {
+      $value = substr($value, 0, $length);
+    }
+    $value = rawurlencode($value);
+    return $value;
   }
 }
diff --git a/tests/general/URITemplateTest.php b/tests/general/URITemplateTest.php

Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,7 @@`
`35`	`35`	`*/`
`36`	`36`	`class Google_Client`
`37`	`37`	`{`
`38`		`- const LIBVER = "1.0.1-alpha";`
	`38`	`+ const LIBVER = "1.0.1-beta";`
`39`	`39`	`const USER_AGENT_SUFFIX = "google-api-php-client/";`
`40`	`40`	`const GZIP_UA = " (gzip)";`
`41`	`41`	`/**`