Storage Capabilities

Storage capabilities describe how a storage adapter works, and which features it supports.

To get capabilities of a storage adapter, you can use the method getCapabilities(), but only the storage adapter and its plugins have permissions to change them.

Because capabilities are mutable, you can subscribe to the "change" event to get notifications; see the examples for details.

If you are writing your own plugin or adapter, you can also change capabilities because you have access to the marker object and can create your own marker to instantiate a new instance of Laminas\Cache\Storage\Capabilities.

Available Methods

namespace Laminas\Cache\Storage;

use ArrayObject;
use stdClass;
use Laminas\Cache\Exception;
use Laminas\EventManager\EventsCapableInterface;

class Capabilities
{
    /**
     * Constructor
     *
     * [@param](https://github.com/param) StorageInterface  $storage
     * [@param](https://github.com/param) stdClass          $marker
     * [@param](https://github.com/param) array             $capabilities
     * [@param](https://github.com/param) null|Capabilities $baseCapabilities
     */
    public function __construct(
        StorageInterface $storage,
        stdClass $marker,
        array $capabilities = [],
        Capabilities $baseCapabilities = null
    );

    /**
     * Get the storage adapter
     *
     * [@return](https://github.com/return) StorageInterface
     */
    public function getAdapter();

    /**
     * Get supported datatypes
     *
     * [@return](https://github.com/return) array
     */
    public function getSupportedDatatypes();

    /**
     * Set supported datatypes
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  array $datatypes
     * [@throws](https://github.com/throws) Exception\InvalidArgumentException
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setSupportedDatatypes(stdClass $marker, array $datatypes);

    /**
     * Get supported metadata
     *
     * [@return](https://github.com/return) array
     */
    public function getSupportedMetadata();

    /**
     * Set supported metadata
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  string[] $metadata
     * [@throws](https://github.com/throws) Exception\InvalidArgumentException
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setSupportedMetadata(stdClass $marker, array $metadata);

    /**
     * Get minimum supported time-to-live
     *
     * [@return](https://github.com/return) int 0 means items never expire
     */
    public function getMinTtl();

    /**
     * Set minimum supported time-to-live
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  int $minTtl
     * [@throws](https://github.com/throws) Exception\InvalidArgumentException
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setMinTtl(stdClass $marker, $minTtl);

    /**
     * Get maximum supported time-to-live
     *
     * [@return](https://github.com/return) int 0 means infinite
     */
    public function getMaxTtl();

    /**
     * Set maximum supported time-to-live
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  int $maxTtl
     * [@throws](https://github.com/throws) Exception\InvalidArgumentException
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setMaxTtl(stdClass $marker, $maxTtl);

    /**
     * Is the time-to-live handled static (on write)
     * or dynamic (on read)
     *
     * [@return](https://github.com/return) bool
     */
    public function getStaticTtl();

    /**
     * Set if the time-to-live handled static (on write) or dynamic (on read)
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  bool $flag
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setStaticTtl(stdClass $marker, $flag);

    /**
     * Get time-to-live precision
     *
     * [@return](https://github.com/return) float
     */
    public function getTtlPrecision();

    /**
     * Set time-to-live precision
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  float $ttlPrecision
     * [@throws](https://github.com/throws) Exception\InvalidArgumentException
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setTtlPrecision(stdClass $marker, $ttlPrecision);

    /**
     * Get use request time
     *
     * [@return](https://github.com/return) bool
     */
    public function getUseRequestTime();

    /**
     * Set use request time
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  bool $flag
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setUseRequestTime(stdClass $marker, $flag);


    /**
     * Get "lock-on-expire" support in seconds.
     *
     * [@return](https://github.com/return) int  0 = Expired items will never be retrieved
     *             >0 = Time in seconds an expired item could be retrieved
     *             -1 = Expired items could be retrieved forever
     */
    public function getLockOnExpire()
    {
        return $this->getCapability('lockOnExpire', 0);
    }

    /**
     * Set "lock-on-expire" support in seconds.
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  int      $timeout
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setLockOnExpire(stdClass $marker, $timeout)
    {
        return $this->setCapability($marker, 'lockOnExpire', (int) $timeout);
    }

    /**
     * Get maximum key length
     *
     * [@return](https://github.com/return) int -1 means unknown, 0 means infinite
     */
    public function getMaxKeyLength();

    /**
     * Set maximum key length
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  int $maxKeyLength
     * [@throws](https://github.com/throws) Exception\InvalidArgumentException
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setMaxKeyLength(stdClass $marker, $maxKeyLength);

    /**
     * Get if namespace support is implemented as prefix
     *
     * [@return](https://github.com/return) bool
     */
    public function getNamespaceIsPrefix();

    /**
     * Set if namespace support is implemented as prefix
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  bool $flag
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setNamespaceIsPrefix(stdClass $marker, $flag);

    /**
     * Get namespace separator if namespace is implemented as prefix
     *
     * [@return](https://github.com/return) string
     */
    public function getNamespaceSeparator();

    /**
     * Set the namespace separator if namespace is implemented as prefix
     *
     * [@param](https://github.com/param)  stdClass $marker
     * [@param](https://github.com/param)  string $separator
     * [@return](https://github.com/return) Capabilities Fluent interface
     */
    public function setNamespaceSeparator(stdClass $marker, $separator);
}

Examples

Get Storage Capabilities and do specific Stuff based on them

use Laminas\Cache\Service\StorageAdapterFactoryInterface;
use Psr\Container\ContainerInterface;

/** [@var](https://github.com/var) ContainerInterface $container */
$container = null; // can be any configured PSR-11 container

/** [@var](https://github.com/var) StorageAdapterFactoryInterface $storageFactory */
$storageFactory = $container->get(StorageAdapterFactoryInterface::class);

$cache = $storageFactory->create('filesystem');
$supportedDatatypes = $cache->getCapabilities()->getSupportedDatatypes();

// now you can run specific stuff in base of supported feature
if ($supportedDatatypes['object']) {
    $cache->set($key, $object);
} else {
    $cache->set($key, serialize($object));
}

Listen to the change Event

use Laminas\Cache\Service\StorageAdapterFactoryInterface;
use Psr\Container\ContainerInterface;

/** [@var](https://github.com/var) ContainerInterface $container */
$container = null; // can be any configured PSR-11 container

/** [@var](https://github.com/var) StorageAdapterFactoryInterface $storageFactory */
$storageFactory = $container->get(StorageAdapterFactoryInterface::class);

$cache = $storageFactory->create('filesystem', [
    'no_atime' => false,
]);

// Catching capability changes
$cache->getEventManager()->attach('capability', function($event) {
    echo count($event->getParams()) . ' capabilities changed';
});

// change option which changes capabilities
$cache->getOptions()->setNoATime(true);