vendor/zendframework/zend-cache/src/Storage/Capabilities.php

   1 <?php
   2 /**
   3  * Zend Framework (http://framework.zend.com/)
   4  *
   5  * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6  * @copyright Copyright (c) 2005-2016 Zend Technologies USA Inc. (http://www.zend.com)
   7  * @license   http://framework.zend.com/license/new-bsd New BSD License
   8  */
   9
  10 namespace Zend\Cache\Storage;
  11
  12 use ArrayObject;
  13 use stdClass;
  14 use Zend\Cache\Exception;
  15 use Zend\EventManager\EventsCapableInterface;
  16
  17 class Capabilities
  18 {
  19     /**
  20      * The storage instance
  21      *
  22      * @var StorageInterface
  23      */
  24     protected $storage;
  25
  26     /**
  27      * A marker to set/change capabilities
  28      *
  29      * @var stdClass
  30      */
  31     protected $marker;
  32
  33     /**
  34      * Base capabilities
  35      *
  36      * @var null|Capabilities
  37      */
  38     protected $baseCapabilities;
  39
  40     /**
  41      * "lock-on-expire" support in seconds.
  42      *
  43      *      0 = Expired items will never be retrieved
  44      *     >0 = Time in seconds an expired item could be retrieved
  45      *     -1 = Expired items could be retrieved forever
  46      *
  47      * If it's NULL the capability isn't set and the getter
  48      * returns the base capability or the default value.
  49      *
  50      * @var null|bool
  51      */
  52     protected $lockOnExpire;
  53
  54     /**
  55      * Max. key length
  56      *
  57      * If it's NULL the capability isn't set and the getter
  58      * returns the base capability or the default value.
  59      *
  60      * @var null|int
  61      */
  62     protected $maxKeyLength;
  63
  64     /**
  65      * Min. TTL (0 means items never expire)
  66      *
  67      * If it's NULL the capability isn't set and the getter
  68      * returns the base capability or the default value.
  69      *
  70      * @var null|int
  71      */
  72     protected $minTtl;
  73
  74     /**
  75      * Max. TTL (0 means infinite)
  76      *
  77      * If it's NULL the capability isn't set and the getter
  78      * returns the base capability or the default value.
  79      *
  80      * @var null|int
  81      */
  82     protected $maxTtl;
  83
  84     /**
  85      * Namespace is prefix
  86      *
  87      * If it's NULL the capability isn't set and the getter
  88      * returns the base capability or the default value.
  89      *
  90      * @var null|bool
  91      */
  92     protected $namespaceIsPrefix;
  93
  94     /**
  95      * Namespace separator
  96      *
  97      * If it's NULL the capability isn't set and the getter
  98      * returns the base capability or the default value.
  99      *
 100      * @var null|string
 101      */
 102     protected $namespaceSeparator;
 103
 104     /**
 105      * Static ttl
 106      *
 107      * If it's NULL the capability isn't set and the getter
 108      * returns the base capability or the default value.
 109      *
 110      * @var null|bool
 111      */
 112     protected $staticTtl;
 113
 114     /**
 115      * Supported datatypes
 116      *
 117      * If it's NULL the capability isn't set and the getter
 118      * returns the base capability or the default value.
 119      *
 120      * @var null|array
 121      */
 122     protected $supportedDatatypes;
 123
 124     /**
 125      * Supported metdata
 126      *
 127      * If it's NULL the capability isn't set and the getter
 128      * returns the base capability or the default value.
 129      *
 130      * @var null|array
 131      */
 132     protected $supportedMetadata;
 133
 134     /**
 135      * TTL precision
 136      *
 137      * If it's NULL the capability isn't set and the getter
 138      * returns the base capability or the default value.
 139      *
 140      * @var null|int
 141      */
 142     protected $ttlPrecision;
 143
 144     /**
 145      * Use request time
 146      *
 147      * If it's NULL the capability isn't set and the getter
 148      * returns the base capability or the default value.
 149      *
 150      * @var null|bool
 151      */
 152     protected $useRequestTime;
 153
 154     /**
 155      * Constructor
 156      *
 157      * @param StorageInterface  $storage
 158      * @param stdClass          $marker
 159      * @param array             $capabilities
 160      * @param null|Capabilities $baseCapabilities
 161      */
 162     public function __construct(
 163         StorageInterface $storage,
 164         stdClass $marker,
 165         array $capabilities = [],
 166         Capabilities $baseCapabilities = null
 167     ) {
 168         $this->storage = $storage;
 169         $this->marker  = $marker;
 170         $this->baseCapabilities = $baseCapabilities;
 171
 172         foreach ($capabilities as $name => $value) {
 173             $this->setCapability($marker, $name, $value);
 174         }
 175     }
 176
 177     /**
 178      * Get the storage adapter
 179      *
 180      * @return StorageInterface
 181      */
 182     public function getAdapter()
 183     {
 184         return $this->storage;
 185     }
 186
 187     /**
 188      * Get supported datatypes
 189      *
 190      * @return array
 191      */
 192     public function getSupportedDatatypes()
 193     {
 194         return $this->getCapability('supportedDatatypes', [
 195             'NULL'     => false,
 196             'boolean'  => false,
 197             'integer'  => false,
 198             'double'   => false,
 199             'string'   => true,
 200             'array'    => false,
 201             'object'   => false,
 202             'resource' => false,
 203         ]);
 204     }
 205
 206     /**
 207      * Set supported datatypes
 208      *
 209      * @param  stdClass $marker
 210      * @param  array $datatypes
 211      * @throws Exception\InvalidArgumentException
 212      * @return Capabilities Fluent interface
 213      */
 214     public function setSupportedDatatypes(stdClass $marker, array $datatypes)
 215     {
 216         $allTypes = [
 217             'array',
 218             'boolean',
 219             'double',
 220             'integer',
 221             'NULL',
 222             'object',
 223             'resource',
 224             'string',
 225         ];
 226
 227         // check/normalize datatype values
 228         foreach ($datatypes as $type => &$toType) {
 229             if (! in_array($type, $allTypes)) {
 230                 throw new Exception\InvalidArgumentException("Unknown datatype '{$type}'");
 231             }
 232
 233             if (is_string($toType)) {
 234                 $toType = strtolower($toType);
 235                 if (! in_array($toType, $allTypes)) {
 236                     throw new Exception\InvalidArgumentException("Unknown datatype '{$toType}'");
 237                 }
 238             } else {
 239                 $toType = (bool) $toType;
 240             }
 241         }
 242
 243         // add missing datatypes as not supported
 244         $missingTypes = array_diff($allTypes, array_keys($datatypes));
 245         foreach ($missingTypes as $type) {
 246             $datatypes[$type] = false;
 247         }
 248
 249         return $this->setCapability($marker, 'supportedDatatypes', $datatypes);
 250     }
 251
 252     /**
 253      * Get supported metadata
 254      *
 255      * @return array
 256      */
 257     public function getSupportedMetadata()
 258     {
 259         return $this->getCapability('supportedMetadata', []);
 260     }
 261
 262     /**
 263      * Set supported metadata
 264      *
 265      * @param  stdClass $marker
 266      * @param  string[] $metadata
 267      * @throws Exception\InvalidArgumentException
 268      * @return Capabilities Fluent interface
 269      */
 270     public function setSupportedMetadata(stdClass $marker, array $metadata)
 271     {
 272         foreach ($metadata as $name) {
 273             if (! is_string($name)) {
 274                 throw new Exception\InvalidArgumentException('$metadata must be an array of strings');
 275             }
 276         }
 277         return $this->setCapability($marker, 'supportedMetadata', $metadata);
 278     }
 279
 280     /**
 281      * Get minimum supported time-to-live
 282      *
 283      * @return int 0 means items never expire
 284      */
 285     public function getMinTtl()
 286     {
 287         return $this->getCapability('minTtl', 0);
 288     }
 289
 290     /**
 291      * Set minimum supported time-to-live
 292      *
 293      * @param  stdClass $marker
 294      * @param  int $minTtl
 295      * @throws Exception\InvalidArgumentException
 296      * @return Capabilities Fluent interface
 297      */
 298     public function setMinTtl(stdClass $marker, $minTtl)
 299     {
 300         $minTtl = (int) $minTtl;
 301         if ($minTtl < 0) {
 302             throw new Exception\InvalidArgumentException('$minTtl must be greater or equal 0');
 303         }
 304         return $this->setCapability($marker, 'minTtl', $minTtl);
 305     }
 306
 307     /**
 308      * Get maximum supported time-to-live
 309      *
 310      * @return int 0 means infinite
 311      */
 312     public function getMaxTtl()
 313     {
 314         return $this->getCapability('maxTtl', 0);
 315     }
 316
 317     /**
 318      * Set maximum supported time-to-live
 319      *
 320      * @param  stdClass $marker
 321      * @param  int $maxTtl
 322      * @throws Exception\InvalidArgumentException
 323      * @return Capabilities Fluent interface
 324      */
 325     public function setMaxTtl(stdClass $marker, $maxTtl)
 326     {
 327         $maxTtl = (int) $maxTtl;
 328         if ($maxTtl < 0) {
 329             throw new Exception\InvalidArgumentException('$maxTtl must be greater or equal 0');
 330         }
 331         return $this->setCapability($marker, 'maxTtl', $maxTtl);
 332     }
 333
 334     /**
 335      * Is the time-to-live handled static (on write)
 336      * or dynamic (on read)
 337      *
 338      * @return bool
 339      */
 340     public function getStaticTtl()
 341     {
 342         return $this->getCapability('staticTtl', false);
 343     }
 344
 345     /**
 346      * Set if the time-to-live handled static (on write) or dynamic (on read)
 347      *
 348      * @param  stdClass $marker
 349      * @param  bool $flag
 350      * @return Capabilities Fluent interface
 351      */
 352     public function setStaticTtl(stdClass $marker, $flag)
 353     {
 354         return $this->setCapability($marker, 'staticTtl', (bool) $flag);
 355     }
 356
 357     /**
 358      * Get time-to-live precision
 359      *
 360      * @return float
 361      */
 362     public function getTtlPrecision()
 363     {
 364         return $this->getCapability('ttlPrecision', 1);
 365     }
 366
 367     /**
 368      * Set time-to-live precision
 369      *
 370      * @param  stdClass $marker
 371      * @param  float $ttlPrecision
 372      * @throws Exception\InvalidArgumentException
 373      * @return Capabilities Fluent interface
 374      */
 375     public function setTtlPrecision(stdClass $marker, $ttlPrecision)
 376     {
 377         $ttlPrecision = (float) $ttlPrecision;
 378         if ($ttlPrecision <= 0) {
 379             throw new Exception\InvalidArgumentException('$ttlPrecision must be greater than 0');
 380         }
 381         return $this->setCapability($marker, 'ttlPrecision', $ttlPrecision);
 382     }
 383
 384     /**
 385      * Get use request time
 386      *
 387      * @return bool
 388      */
 389     public function getUseRequestTime()
 390     {
 391         return $this->getCapability('useRequestTime', false);
 392     }
 393
 394     /**
 395      * Set use request time
 396      *
 397      * @param  stdClass $marker
 398      * @param  bool $flag
 399      * @return Capabilities Fluent interface
 400      */
 401     public function setUseRequestTime(stdClass $marker, $flag)
 402     {
 403         return $this->setCapability($marker, 'useRequestTime', (bool) $flag);
 404     }
 405
 406     /**
 407      * Get if expired items are readable
 408      *
 409      * @return bool
 410      * @deprecated This capability has been deprecated and will be removed in the future.
 411      *             Please use getStaticTtl() instead
 412      */
 413     public function getExpiredRead()
 414     {
 415         trigger_error(
 416             'This capability has been deprecated and will be removed in the future. Please use static_ttl instead',
 417             E_USER_DEPRECATED
 418         );
 419         return ! $this->getCapability('staticTtl', true);
 420     }
 421
 422     /**
 423      * Set if expired items are readable
 424      *
 425      * @param  stdClass $marker
 426      * @param  bool $flag
 427      * @return Capabilities Fluent interface
 428      * @deprecated This capability has been deprecated and will be removed in the future.
 429      *             Please use setStaticTtl() instead
 430      */
 431     public function setExpiredRead(stdClass $marker, $flag)
 432     {
 433         trigger_error(
 434             'This capability has been deprecated and will be removed in the future. Please use static_ttl instead',
 435             E_USER_DEPRECATED
 436         );
 437         return $this->setCapability($marker, 'staticTtl', (bool) $flag);
 438     }
 439
 440     /**
 441      * Get "lock-on-expire" support in seconds.
 442      *
 443      * @return int 0  = Expired items will never be retrieved
 444      *             >0 = Time in seconds an expired item could be retrieved
 445      *             -1 = Expired items could be retrieved forever
 446      */
 447     public function getLockOnExpire()
 448     {
 449         return $this->getCapability('lockOnExpire', 0);
 450     }
 451
 452     /**
 453      * Set "lock-on-expire" support in seconds.
 454      *
 455      * @param  stdClass $marker
 456      * @param  int      $timeout
 457      * @return Capabilities Fluent interface
 458      */
 459     public function setLockOnExpire(stdClass $marker, $timeout)
 460     {
 461         return $this->setCapability($marker, 'lockOnExpire', (int) $timeout);
 462     }
 463
 464     /**
 465      * Get maximum key length
 466      *
 467      * @return int -1 means unknown, 0 means infinite
 468      */
 469     public function getMaxKeyLength()
 470     {
 471         return $this->getCapability('maxKeyLength', -1);
 472     }
 473
 474     /**
 475      * Set maximum key length
 476      *
 477      * @param  stdClass $marker
 478      * @param  int $maxKeyLength
 479      * @throws Exception\InvalidArgumentException
 480      * @return Capabilities Fluent interface
 481      */
 482     public function setMaxKeyLength(stdClass $marker, $maxKeyLength)
 483     {
 484         $maxKeyLength = (int) $maxKeyLength;
 485         if ($maxKeyLength < -1) {
 486             throw new Exception\InvalidArgumentException('$maxKeyLength must be greater or equal than -1');
 487         }
 488         return $this->setCapability($marker, 'maxKeyLength', $maxKeyLength);
 489     }
 490
 491     /**
 492      * Get if namespace support is implemented as prefix
 493      *
 494      * @return bool
 495      */
 496     public function getNamespaceIsPrefix()
 497     {
 498         return $this->getCapability('namespaceIsPrefix', true);
 499     }
 500
 501     /**
 502      * Set if namespace support is implemented as prefix
 503      *
 504      * @param  stdClass $marker
 505      * @param  bool $flag
 506      * @return Capabilities Fluent interface
 507      */
 508     public function setNamespaceIsPrefix(stdClass $marker, $flag)
 509     {
 510         return $this->setCapability($marker, 'namespaceIsPrefix', (bool) $flag);
 511     }
 512
 513     /**
 514      * Get namespace separator if namespace is implemented as prefix
 515      *
 516      * @return string
 517      */
 518     public function getNamespaceSeparator()
 519     {
 520         return $this->getCapability('namespaceSeparator', '');
 521     }
 522
 523     /**
 524      * Set the namespace separator if namespace is implemented as prefix
 525      *
 526      * @param  stdClass $marker
 527      * @param  string $separator
 528      * @return Capabilities Fluent interface
 529      */
 530     public function setNamespaceSeparator(stdClass $marker, $separator)
 531     {
 532         return $this->setCapability($marker, 'namespaceSeparator', (string) $separator);
 533     }
 534
 535     /**
 536      * Get a capability
 537      *
 538      * @param  string $property
 539      * @param  mixed $default
 540      * @return mixed
 541      */
 542     protected function getCapability($property, $default = null)
 543     {
 544         if ($this->$property !== null) {
 545             return $this->$property;
 546         } elseif ($this->baseCapabilities) {
 547             $getMethod = 'get' . $property;
 548             return $this->baseCapabilities->$getMethod();
 549         }
 550         return $default;
 551     }
 552
 553     /**
 554      * Change a capability
 555      *
 556      * @param  stdClass $marker
 557      * @param  string $property
 558      * @param  mixed $value
 559      * @return Capabilities Fluent interface
 560      * @throws Exception\InvalidArgumentException
 561      */
 562     protected function setCapability(stdClass $marker, $property, $value)
 563     {
 564         if ($this->marker !== $marker) {
 565             throw new Exception\InvalidArgumentException('Invalid marker');
 566         }
 567
 568         if ($this->$property !== $value) {
 569             $this->$property = $value;
 570
 571             // trigger event
 572             if ($this->storage instanceof EventsCapableInterface) {
 573                 $this->storage->getEventManager()->trigger('capability', $this->storage, new ArrayObject([
 574                     $property => $value
 575                 ]));
 576             }
 577         }
 578
 579         return $this;
 580     }
 581 }