[Summary view] [Print] [Text view]

   1  <?php
   2  namespace GuzzleHttp;
   3  
   4  use GuzzleHttp\Ring\Client\CurlHandler;
   5  use GuzzleHttp\Ring\Client\CurlMultiHandler;
   6  use GuzzleHttp\Ring\Client\StreamHandler;
   7  use GuzzleHttp\Ring\Client\Middleware;
   8  
   9  /**
  10   * Utility methods used throughout Guzzle.
  11   */
  12  final class Utils
  13  {
  14      /**
  15       * Gets a value from an array using a path syntax to retrieve nested data.
  16       *
  17       * This method does not allow for keys that contain "/". You must traverse
  18       * the array manually or using something more advanced like JMESPath to
  19       * work with keys that contain "/".
  20       *
  21       *     // Get the bar key of a set of nested arrays.
  22       *     // This is equivalent to $collection['foo']['baz']['bar'] but won't
  23       *     // throw warnings for missing keys.
  24       *     GuzzleHttp\get_path($data, 'foo/baz/bar');
  25       *
  26       * @param array  $data Data to retrieve values from
  27       * @param string $path Path to traverse and retrieve a value from
  28       *
  29       * @return mixed|null
  30       */
  31      public static function getPath($data, $path)
  32      {
  33          $path = explode('/', $path);
  34  
  35          while (null !== ($part = array_shift($path))) {
  36              if (!is_array($data) || !isset($data[$part])) {
  37                  return null;
  38              }
  39              $data = $data[$part];
  40          }
  41  
  42          return $data;
  43      }
  44  
  45      /**
  46       * Set a value in a nested array key. Keys will be created as needed to set
  47       * the value.
  48       *
  49       * This function does not support keys that contain "/" or "[]" characters
  50       * because these are special tokens used when traversing the data structure.
  51       * A value may be prepended to an existing array by using "[]" as the final
  52       * key of a path.
  53       *
  54       *     GuzzleHttp\get_path($data, 'foo/baz'); // null
  55       *     GuzzleHttp\set_path($data, 'foo/baz/[]', 'a');
  56       *     GuzzleHttp\set_path($data, 'foo/baz/[]', 'b');
  57       *     GuzzleHttp\get_path($data, 'foo/baz');
  58       *     // Returns ['a', 'b']
  59       *
  60       * @param array  $data  Data to modify by reference
  61       * @param string $path  Path to set
  62       * @param mixed  $value Value to set at the key
  63       *
  64       * @throws \RuntimeException when trying to setPath using a nested path
  65       *     that travels through a scalar value.
  66       */
  67      public static function setPath(&$data, $path, $value)
  68      {
  69          $queue = explode('/', $path);
  70          // Optimization for simple sets.
  71          if (count($queue) === 1) {
  72              $data[$path] = $value;
  73              return;
  74          }
  75  
  76          $current =& $data;
  77          while (null !== ($key = array_shift($queue))) {
  78              if (!is_array($current)) {
  79                  throw new \RuntimeException("Trying to setPath {$path}, but "
  80                      . "{$key} is set and is not an array");
  81              } elseif (!$queue) {
  82                  if ($key == '[]') {
  83                      $current[] = $value;
  84                  } else {
  85                      $current[$key] = $value;
  86                  }
  87              } elseif (isset($current[$key])) {
  88                  $current =& $current[$key];
  89              } else {
  90                  $current[$key] = [];
  91                  $current =& $current[$key];
  92              }
  93          }
  94      }
  95  
  96      /**
  97       * Expands a URI template
  98       *
  99       * @param string $template  URI template
 100       * @param array  $variables Template variables
 101       *
 102       * @return string
 103       */
 104      public static function uriTemplate($template, array $variables)
 105      {
 106          if (function_exists('\\uri_template')) {
 107              return \uri_template($template, $variables);
 108          }
 109  
 110          static $uriTemplate;
 111          if (!$uriTemplate) {
 112              $uriTemplate = new UriTemplate();
 113          }
 114  
 115          return $uriTemplate->expand($template, $variables);
 116      }
 117  
 118      /**
 119       * Wrapper for JSON decode that implements error detection with helpful
 120       * error messages.
 121       *
 122       * @param string $json    JSON data to parse
 123       * @param bool $assoc     When true, returned objects will be converted
 124       *                        into associative arrays.
 125       * @param int    $depth   User specified recursion depth.
 126       * @param int    $options Bitmask of JSON decode options.
 127       *
 128       * @return mixed
 129       * @throws \InvalidArgumentException if the JSON cannot be parsed.
 130       * @link http://www.php.net/manual/en/function.json-decode.php
 131       */
 132      public static function jsonDecode($json, $assoc = false, $depth = 512, $options = 0)
 133      {
 134          if ($json === '' || $json === null) {
 135              return null;
 136          }
 137  
 138          static $jsonErrors = [
 139              JSON_ERROR_DEPTH => 'JSON_ERROR_DEPTH - Maximum stack depth exceeded',
 140              JSON_ERROR_STATE_MISMATCH => 'JSON_ERROR_STATE_MISMATCH - Underflow or the modes mismatch',
 141              JSON_ERROR_CTRL_CHAR => 'JSON_ERROR_CTRL_CHAR - Unexpected control character found',
 142              JSON_ERROR_SYNTAX => 'JSON_ERROR_SYNTAX - Syntax error, malformed JSON',
 143              JSON_ERROR_UTF8 => 'JSON_ERROR_UTF8 - Malformed UTF-8 characters, possibly incorrectly encoded'
 144          ];
 145  
 146          $data = \json_decode($json, $assoc, $depth, $options);
 147  
 148          if (JSON_ERROR_NONE !== json_last_error()) {
 149              $last = json_last_error();
 150              throw new \InvalidArgumentException(
 151                  'Unable to parse JSON data: '
 152                  . (isset($jsonErrors[$last])
 153                      ? $jsonErrors[$last]
 154                      : 'Unknown error')
 155              );
 156          }
 157  
 158          return $data;
 159      }
 160  
 161      /**
 162       * Get the default User-Agent string to use with Guzzle
 163       *
 164       * @return string
 165       */
 166      public static function getDefaultUserAgent()
 167      {
 168          static $defaultAgent = '';
 169          if (!$defaultAgent) {
 170              $defaultAgent = 'Guzzle/' . ClientInterface::VERSION;
 171              if (extension_loaded('curl')) {
 172                  $defaultAgent .= ' curl/' . curl_version()['version'];
 173              }
 174              $defaultAgent .= ' PHP/' . PHP_VERSION;
 175          }
 176  
 177          return $defaultAgent;
 178      }
 179  
 180      /**
 181       * Create a default handler to use based on the environment
 182       *
 183       * @throws \RuntimeException if no viable Handler is available.
 184       */
 185      public static function getDefaultHandler()
 186      {
 187          $default = $future = null;
 188  
 189          if (extension_loaded('curl')) {
 190              $config = [
 191                  'select_timeout' => getenv('GUZZLE_CURL_SELECT_TIMEOUT') ?: 1
 192              ];
 193              if ($maxHandles = getenv('GUZZLE_CURL_MAX_HANDLES')) {
 194                  $config['max_handles'] = $maxHandles;
 195              }
 196              if (function_exists('curl_reset')) {
 197                  $default = new CurlHandler();
 198                  $future = new CurlMultiHandler($config);
 199              } else {
 200                  $default = new CurlMultiHandler($config);
 201              }
 202          }
 203  
 204          if (ini_get('allow_url_fopen')) {
 205              $default = !$default
 206                  ? new StreamHandler()
 207                  : Middleware::wrapStreaming($default, new StreamHandler());
 208          } elseif (!$default) {
 209              throw new \RuntimeException('Guzzle requires cURL, the '
 210                  . 'allow_url_fopen ini setting, or a custom HTTP handler.');
 211          }
 212  
 213          return $future ? Middleware::wrapFuture($default, $future) : $default;
 214      }
 215  }