[Summary view] [Print] [Text view]

   1  <?php
   2  namespace GuzzleHttp;
   3  
   4  /**
   5   * Key value pair collection object
   6   */
   7  class Collection implements
   8      \ArrayAccess,
   9      \IteratorAggregate,
  10      \Countable,
  11      ToArrayInterface
  12  {
  13      use HasDataTrait;
  14  
  15      /**
  16       * @param array $data Associative array of data to set
  17       */
  18      public function __construct(array $data = [])
  19      {
  20          $this->data = $data;
  21      }
  22  
  23      /**
  24       * Create a new collection from an array, validate the keys, and add default
  25       * values where missing
  26       *
  27       * @param array $config   Configuration values to apply.
  28       * @param array $defaults Default parameters
  29       * @param array $required Required parameter names
  30       *
  31       * @return self
  32       * @throws \InvalidArgumentException if a parameter is missing
  33       */
  34      public static function fromConfig(
  35          array $config = [],
  36          array $defaults = [],
  37          array $required = []
  38      ) {
  39          $data = $config + $defaults;
  40  
  41          if ($missing = array_diff($required, array_keys($data))) {
  42              throw new \InvalidArgumentException(
  43                  'Config is missing the following keys: ' .
  44                  implode(', ', $missing));
  45          }
  46  
  47          return new self($data);
  48      }
  49  
  50      /**
  51       * Removes all key value pairs
  52       */
  53      public function clear()
  54      {
  55          $this->data = [];
  56      }
  57  
  58      /**
  59       * Get a specific key value.
  60       *
  61       * @param string $key Key to retrieve.
  62       *
  63       * @return mixed|null Value of the key or NULL
  64       */
  65      public function get($key)
  66      {
  67          return isset($this->data[$key]) ? $this->data[$key] : null;
  68      }
  69  
  70      /**
  71       * Set a key value pair
  72       *
  73       * @param string $key   Key to set
  74       * @param mixed  $value Value to set
  75       */
  76      public function set($key, $value)
  77      {
  78          $this->data[$key] = $value;
  79      }
  80  
  81      /**
  82       * Add a value to a key.  If a key of the same name has already been added,
  83       * the key value will be converted into an array and the new value will be
  84       * pushed to the end of the array.
  85       *
  86       * @param string $key   Key to add
  87       * @param mixed  $value Value to add to the key
  88       */
  89      public function add($key, $value)
  90      {
  91          if (!array_key_exists($key, $this->data)) {
  92              $this->data[$key] = $value;
  93          } elseif (is_array($this->data[$key])) {
  94              $this->data[$key][] = $value;
  95          } else {
  96              $this->data[$key] = array($this->data[$key], $value);
  97          }
  98      }
  99  
 100      /**
 101       * Remove a specific key value pair
 102       *
 103       * @param string $key A key to remove
 104       */
 105      public function remove($key)
 106      {
 107          unset($this->data[$key]);
 108      }
 109  
 110      /**
 111       * Get all keys in the collection
 112       *
 113       * @return array
 114       */
 115      public function getKeys()
 116      {
 117          return array_keys($this->data);
 118      }
 119  
 120      /**
 121       * Returns whether or not the specified key is present.
 122       *
 123       * @param string $key The key for which to check the existence.
 124       *
 125       * @return bool
 126       */
 127      public function hasKey($key)
 128      {
 129          return array_key_exists($key, $this->data);
 130      }
 131  
 132      /**
 133       * Checks if any keys contains a certain value
 134       *
 135       * @param string $value Value to search for
 136       *
 137       * @return mixed Returns the key if the value was found FALSE if the value
 138       *     was not found.
 139       */
 140      public function hasValue($value)
 141      {
 142          return array_search($value, $this->data, true);
 143      }
 144  
 145      /**
 146       * Replace the data of the object with the value of an array
 147       *
 148       * @param array $data Associative array of data
 149       */
 150      public function replace(array $data)
 151      {
 152          $this->data = $data;
 153      }
 154  
 155      /**
 156       * Add and merge in a Collection or array of key value pair data.
 157       *
 158       * @param Collection|array $data Associative array of key value pair data
 159       */
 160      public function merge($data)
 161      {
 162          foreach ($data as $key => $value) {
 163              $this->add($key, $value);
 164          }
 165      }
 166  
 167      /**
 168       * Overwrite key value pairs in this collection with all of the data from
 169       * an array or collection.
 170       *
 171       * @param array|\Traversable $data Values to override over this config
 172       */
 173      public function overwriteWith($data)
 174      {
 175          if (is_array($data)) {
 176              $this->data = $data + $this->data;
 177          } elseif ($data instanceof Collection) {
 178              $this->data = $data->toArray() + $this->data;
 179          } else {
 180              foreach ($data as $key => $value) {
 181                  $this->data[$key] = $value;
 182              }
 183          }
 184      }
 185  
 186      /**
 187       * Returns a Collection containing all the elements of the collection after
 188       * applying the callback function to each one.
 189       *
 190       * The callable should accept three arguments:
 191       * - (string) $key
 192       * - (string) $value
 193       * - (array) $context
 194       *
 195       * The callable must return a the altered or unaltered value.
 196       *
 197       * @param callable $closure Map function to apply
 198       * @param array    $context Context to pass to the callable
 199       *
 200       * @return Collection
 201       */
 202      public function map(callable $closure, array $context = [])
 203      {
 204          $collection = new static();
 205          foreach ($this as $key => $value) {
 206              $collection[$key] = $closure($key, $value, $context);
 207          }
 208  
 209          return $collection;
 210      }
 211  
 212      /**
 213       * Iterates over each key value pair in the collection passing them to the
 214       * callable. If the callable returns true, the current value from input is
 215       * returned into the result Collection.
 216       *
 217       * The callable must accept two arguments:
 218       * - (string) $key
 219       * - (string) $value
 220       *
 221       * @param callable $closure Evaluation function
 222       *
 223       * @return Collection
 224       */
 225      public function filter(callable $closure)
 226      {
 227          $collection = new static();
 228          foreach ($this->data as $key => $value) {
 229              if ($closure($key, $value)) {
 230                  $collection[$key] = $value;
 231              }
 232          }
 233  
 234          return $collection;
 235      }
 236  }