[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4  * @package   s9e\TextFormatter
   5  * @copyright Copyright (c) 2010-2022 The s9e authors
   6  * @license   http://www.opensource.org/licenses/mit-license.php The MIT License
   7  */
   8  namespace s9e\TextFormatter\Configurator\Collections;
   9  
  10  use ArrayAccess;
  11  use InvalidArgumentException;
  12  use RuntimeException;
  13  
  14  class NormalizedCollection extends Collection implements ArrayAccess
  15  {
  16      /**
  17      * @var string Action to take when add() is called with a key that already exists
  18      */
  19      protected $onDuplicateAction = 'error';
  20  
  21      /**
  22      * {@inheritdoc}
  23      */
  24  	public function asConfig()
  25      {
  26          $config = parent::asConfig();
  27          ksort($config);
  28  
  29          return $config;
  30      }
  31  
  32      /**
  33      * Query and set the action to take when add() is called with a key that already exists
  34      *
  35      * @param  string|null $action If specified: either "error", "ignore" or "replace"
  36      * @return string              Old action
  37      */
  38  	public function onDuplicate($action = null)
  39      {
  40          // Save the old action so it can be returned
  41          $old = $this->onDuplicateAction;
  42  
  43          if (func_num_args() && $action !== 'error' && $action !== 'ignore' && $action !== 'replace')
  44          {
  45              throw new InvalidArgumentException("Invalid onDuplicate action '" . $action . "'. Expected: 'error', 'ignore' or 'replace'");
  46          }
  47  
  48          $this->onDuplicateAction = $action;
  49  
  50          return $old;
  51      }
  52  
  53      //==========================================================================
  54      // Overridable methods
  55      //==========================================================================
  56  
  57      /**
  58      * Return the exception that is thrown when creating an item using a key that already exists
  59      *
  60      * @param  string           $key Item's key
  61      * @return RuntimeException
  62      */
  63  	protected function getAlreadyExistsException($key)
  64      {
  65          return new RuntimeException("Item '" . $key . "' already exists");
  66      }
  67  
  68      /**
  69      * Return the exception that is thrown when accessing an item that does not exist
  70      *
  71      * @param  string           $key Item's key
  72      * @return RuntimeException
  73      */
  74  	protected function getNotExistException($key)
  75      {
  76          return new RuntimeException("Item '" . $key . "' does not exist");
  77      }
  78  
  79      /**
  80      * Normalize an item's key
  81      *
  82      * This method can be overridden to implement keys normalization or implement constraints
  83      *
  84      * @param  string $key Original key
  85      * @return string      Normalized key
  86      */
  87  	public function normalizeKey($key)
  88      {
  89          return $key;
  90      }
  91  
  92      /**
  93      * Normalize a value for storage
  94      *
  95      * This method can be overridden to implement value normalization
  96      *
  97      * @param  mixed $value Original value
  98      * @return mixed        Normalized value
  99      */
 100  	public function normalizeValue($value)
 101      {
 102          return $value;
 103      }
 104  
 105      //==========================================================================
 106      // Items access/manipulation
 107      //==========================================================================
 108  
 109      /**
 110      * Add an item to this collection
 111      *
 112      * NOTE: relies on exists() to check the key for invalid values and on set() to normalize it
 113      *
 114      * @param  string $key   Item's key
 115      * @param  mixed  $value Item's value
 116      * @return mixed         Normalized value
 117      */
 118  	public function add($key, $value = null)
 119      {
 120          // Test whether this key is already in use
 121          if ($this->exists($key))
 122          {
 123              // If the action is "ignore" we return the old value, if it's "error" we throw an
 124              // exception. Otherwise, we keep going and replace the value
 125              if ($this->onDuplicateAction === 'ignore')
 126              {
 127                  return $this->get($key);
 128              }
 129              elseif ($this->onDuplicateAction === 'error')
 130              {
 131                  throw $this->getAlreadyExistsException($key);
 132              }
 133          }
 134  
 135          return $this->set($key, $value);
 136      }
 137  
 138      /**
 139      * Test whether a given value is present in this collection
 140      *
 141      * @param  mixed $value Original value
 142      * @return bool         Whether the normalized value was found in this collection
 143      */
 144  	public function contains($value)
 145      {
 146          return in_array($this->normalizeValue($value), $this->items);
 147      }
 148  
 149      /**
 150      * Delete an item from this collection
 151      *
 152      * @param  string $key Item's key
 153      * @return void
 154      */
 155  	public function delete($key)
 156      {
 157          try
 158          {
 159              $key = $this->normalizeKey($key);
 160  
 161              unset($this->items[$key]);
 162          }
 163          catch (InvalidArgumentException $e)
 164          {
 165              // Do nothing
 166          }
 167      }
 168  
 169      /**
 170      * Test whether an item of given key exists
 171      *
 172      * @param  string $key Item's key
 173      * @return bool        Whether this key exists in this collection
 174      */
 175  	public function exists($key)
 176      {
 177          try
 178          {
 179              $key = $this->normalizeKey($key);
 180          }
 181          catch (InvalidArgumentException $e)
 182          {
 183              return false;
 184          }
 185  
 186          return array_key_exists($key, $this->items);
 187      }
 188  
 189      /**
 190      * Return a value from this collection
 191      *
 192      * @param  string $key Item's key
 193      * @return mixed       Normalized value
 194      */
 195  	public function get($key)
 196      {
 197          if (!$this->exists($key))
 198          {
 199              throw $this->getNotExistException($key);
 200          }
 201  
 202          $key = $this->normalizeKey($key);
 203  
 204          return $this->items[$key];
 205      }
 206  
 207      /**
 208      * Find the index of a given value
 209      *
 210      * Will return the first key associated with the given value, or FALSE if the value is not found
 211      *
 212      * @param  mixed $value Original value
 213      * @return mixed        Index of the value, or FALSE if not found
 214      */
 215  	public function indexOf($value)
 216      {
 217          return array_search($this->normalizeValue($value), $this->items);
 218      }
 219  
 220      /**
 221      * Set and overwrite a value in this collection
 222      *
 223      * @param  string $key   Item's key
 224      * @param  mixed  $value Item's value
 225      * @return mixed         Normalized value
 226      */
 227  	public function set($key, $value)
 228      {
 229          $key = $this->normalizeKey($key);
 230  
 231          $this->items[$key] = $this->normalizeValue($value);
 232  
 233          return $this->items[$key];
 234      }
 235  
 236      //==========================================================================
 237      // ArrayAccess stuff
 238      //==========================================================================
 239  
 240      /**
 241      * @param  string|integer $offset
 242      * @return bool
 243      */
 244  	public function offsetExists($offset): bool
 245      {
 246          return $this->exists($offset);
 247      }
 248  
 249      /**
 250      * @param  string|integer $offset
 251      * @return mixed
 252      */
 253      #[\ReturnTypeWillChange]
 254  	public function offsetGet($offset)
 255      {
 256          return $this->get($offset);
 257      }
 258  
 259      /**
 260      * @param  string|integer $offset
 261      * @param  mixed          $value
 262      * @return void
 263      */
 264  	public function offsetSet($offset, $value): void
 265      {
 266          $this->set($offset, $value);
 267      }
 268  
 269      /**
 270      * @param  string|integer $offset
 271      * @return void
 272      */
 273  	public function offsetUnset($offset): void
 274      {
 275          $this->delete($offset);
 276      }
 277  }