Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide Capabilities as a read-only class #308

Merged
merged 1 commit into from
Jun 14, 2024
Merged

Provide Capabilities as a read-only class #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 32 additions & 63 deletions docs/book/v4/storage/adapter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,15 +515,11 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|---------------------------------------------------------------------------------------|
| `supportedDatatypes` | `null`, `bool`, `int`, `float`, `string`, `array` (serialized), `object` (serialized) |
| `minTtl` | 1 |
| `maxTtl` | 0 |
| `staticTtl` | `true` |
| `ttlPrecision` | 1 |
| `useRequestTime` | value of `apc.use_request_time` from `php.ini` |
| `lockOnExpire` | 0 |
| `maxKeyLength` | 5182 |
| `ttlSupported` | `true` |
| `ttlPrecision` | `1` |
| `usesRequestTime` | value of `apc.use_request_time` INI value, disabled by default. |
| `maxKeyLength` | `5182` |
| `namespaceIsPrefix` | `true` |
| `namespaceSeparator` | Option value of `namespace_separator` |

### Metadata

Expand Down Expand Up @@ -570,15 +566,11 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|-------------------------------------------------------------|
| `supportedDatatypes` | `null`, `bool`, `int`, `float`, `string`, `array`, `object` |
| `minTtl` | 1 |
| `maxTtl` | 0 |
| `staticTtl` | `false` or `true`, depending on `psr` option |
| `ttlPrecision` | 1 |
| `useRequestTime` | false |
| `lockOnExpire` | 0 |
| `maxKeyLength` | -1 |
| `ttlSupported` | `true` |
| `ttlPrecision` | `1` |
| `usesRequestTime` | `false` |
| `maxKeyLength` | unlimited as nothing will be cached anyways |
| `namespaceIsPrefix` | `true` |
| `namespaceSeparator` | none |

## Filesystem Adapter

Expand All @@ -602,15 +594,11 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|--------------------------------------------------------------------------------------------------|
| `supportedDatatypes` | `string`, `null` => `string`, `boolean` => `string`, `integer` => `string`, `double` => `string` |
| `minTtl` | 1 |
| `maxTtl` | 0 |
| `staticTtl` | `false` |
| `ttlPrecision` | 1 |
| `useRequestTime` | `false` |
| `lockOnExpire` | 0 |
| `maxKeyLength` | 251 |
| `ttlSupported` | `true` |
| `ttlPrecision` | `1` |
| `usesRequestTime` | `false` |
| `maxKeyLength` | `251` |
| `namespaceIsPrefix` | `true` |
| `namespaceSeparator` | Option value of `namespace_separator` |

### Metadata

Expand Down Expand Up @@ -661,15 +649,11 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|-----------------------------------------------------------------------------------------------|
| `supportedDatatypes` | `null`, `boolean`, `integer`, `double`, `string`, `array` (serialized), `object` (serialized) |
| `minTtl` | 1 |
| `maxTtl` | 0 |
| `staticTtl` | `true` |
| `ttlPrecision` | 1 |
| `useRequestTime` | `false` |
| `lockOnExpire` | 0 |
| `maxKeyLength` | 255 |
| `ttlSupported` | `true` |
| `ttlPrecision` | `1` |
| `usesRequestTime` | `false` |
| `maxKeyLength` | `255` |
| `namespaceIsPrefix` | `true` |
| `namespaceSeparator` | none |

### Adapter Specific Options

Expand All @@ -695,15 +679,11 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|-------------------------------------------------------|
| `supportedDatatypes` | `string`, `array` (serialized), `object` (serialized) |
| `minTtl` | 1 |
| `maxTtl` | 0 |
| `staticTtl` | `true` |
| `ttlPrecision` | 1 |
| `useRequestTime` | `false` |
| `lockOnExpire` | 0 |
| `maxKeyLength` | 512000000 (in Redis v3+, 255 otherwise) |
| `ttlSupported` | `true` |
| `ttlPrecision` | `1` |
| `usesRequestTime` | `false` |
| `maxKeyLength` | `512000000` (in Redis v3+, `255` in older versions) |
| `namespaceIsPrefix` | `true` |
| `namespaceSeparator` | none |

### Metadata

Expand Down Expand Up @@ -745,15 +725,11 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|-------------------------------------------------------|
| `supportedDatatypes` | `string`, `array` (serialized), `object` (serialized) |
| `minTtl` | 1 |
| `maxTtl` | 0 |
| `staticTtl` | `true` |
| `ttlPrecision` | 1 |
| `useRequestTime` | `false` |
| `lockOnExpire` | 0 |
| `maxKeyLength` | 512000000 (in Redis v3+, 255 otherwise) |
| `ttlSupported` | `true` |
| `ttlPrecision` | `1` |
| `usesRequestTime` | `false` |
| `maxKeyLength` | `512000000` (in Redis v3+, `255` in older versions) |
| `namespaceIsPrefix` | `true` |
| `namespaceSeparator` | none |

### Metadata

Expand Down Expand Up @@ -796,13 +772,10 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|---------------------------------------------------------------------------------|
| `supportedDatatypes` | `string`, `null`, `boolean`, `integer`, `double`, `array`, `object`, `resource` |
| `minTtl` | 1 |
| `maxTtl` | Value of `PHP_INT_MAX` |
| `staticTtl` | `false` |
| `ttlPrecision` | 0.05 |
| `useRequestTime` | `false` |
| `lockOnExpire` | 0 |
| `maxKeyLength` | 0 |
| `ttlSupported` | `true` |
| `ttlPrecision` | `0.05` |
| `usesRequestTime` | `false` |
| `maxKeyLength` | `0` |
| `namespaceIsPrefix` | `false` |

### Metadata
Expand Down Expand Up @@ -851,15 +824,11 @@ This adapter implements the following interfaces:
| Capability | Value |
|----------------------|-----------------------------------------------------------|
| `supportedDatatypes` | `string`, `null`, `boolean`, `integer`, `double`, `array` |
| `minTtl` | 0 |
| `maxTtl` | 0 |
| `staticTtl` | `true` |
| `ttlPrecision` | 1 |
| `useRequestTime` | `false` |
| `lockOnExpire` | 0 |
| `maxKeyLength` | 255 |
| `ttlSupported` | `true` |
| `ttlPrecision` | `1` |
| `usesRequestTime` | `false` |
| `maxKeyLength` | `255` |
| `namespaceIsPrefix` | `true` |
| `namespaceSeparator` | *Option value of `namespace_separator`* |

### Metadata

Expand Down
197 changes: 24 additions & 173 deletions docs/book/v4/storage/capabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,156 +24,32 @@ use stdClass;
use Laminas\Cache\Exception;
use Laminas\EventManager\EventsCapableInterface;

class Capabilities
final class Capabilities
{
/**
* Constructor
*
* @param int<-1,max> $maxKeyLength
* @param SupportedDataTypesArrayShape $supportedDataTypes
*/
public function __construct(
StorageInterface $storage,
stdClass $marker,
array $capabilities = [],
Capabilities|null $baseCapabilities = null
);

/**
* Get the storage adapter
*/
public function getAdapter(): StorageInterface;

/**
* Get supported datatypes
*/
public function getSupportedDatatypes(): array;

/**
* Set supported datatypes
*
* @param stdClass $marker
* @param array $datatypes
* @throws Exception\InvalidArgumentException
* @return Capabilities Fluent interface
*/
public function setSupportedDatatypes(stdClass $marker, array $datatypes);

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

/**
* Set minimum supported time-to-live
*
* @param stdClass $marker
* @param int $minTtl
* @throws Exception\InvalidArgumentException
*/
public function setMinTtl(stdClass $marker, int $minTtl): self;

/**
* Get maximum supported time-to-live
*
* @return int 0 means infinite
*/
public function getMaxTtl(): int;

/**
* Set maximum supported time-to-live
*
* @throws Exception\InvalidArgumentException
*/
public function setMaxTtl(stdClass $marker, int $maxTtl): self;

/**
* Is the time-to-live handled static (on write)
* or dynamic (on read)
*/
public function getStaticTtl(): bool;

/**
* Set if the time-to-live handled static (on write) or dynamic (on read)
*/
public function setStaticTtl(stdClass $marker, bool $flag): self;

/**
* Get time-to-live precision
*/
public function getTtlPrecision(): float;

/**
* Set time-to-live precision
*
* @throws Exception\InvalidArgumentException
*/
public function setTtlPrecision(stdClass $marker, float $ttlPrecision): self;

/**
* Get use request time
*/
public function getUseRequestTime(): bool;

/**
* Set use request time
*/
public function setUseRequestTime(stdClass $marker, bool $flag): self;


/**
* Get "lock-on-expire" support in seconds.
*
* @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(): int
{
return $this->getCapability('lockOnExpire', 0);
}

/**
* Set "lock-on-expire" support in seconds.
*/
public function setLockOnExpire(stdClass $marker, int $timeout): self
{
return $this->setCapability($marker, 'lockOnExpire', (int) $timeout);
/**
* Maximum supported key length for the cache backend
*/
public readonly int $maxKeyLength,
/**
* Whether the cache backend supports TTL
*/
public readonly bool $ttlSupported,
public readonly bool $namespaceIsPrefix,
/**
* Contains the supported data types.
* Depending on the cache backend in use, the type remains as is, is converted to a different type or is not
* supported at all.
*/
public readonly array $supportedDataTypes,
public readonly int|float $ttlPrecision,
public readonly bool $usesRequestTime,
) {
}

/**
* Get maximum key length
*
* @return int -1 means unknown, 0 means infinite
*/
public function getMaxKeyLength(): int;

/**
* Set maximum key length
*
* @throws Exception\InvalidArgumentException
*/
public function setMaxKeyLength(stdClass $marker, int $maxKeyLength): self;

/**
* Get if namespace support is implemented as prefix
*/
public function getNamespaceIsPrefix(): bool;

/**
* Set if namespace support is implemented as prefix
*/
public function setNamespaceIsPrefix(stdClass $marker, bool $flag): self;

/**
* Get namespace separator if namespace is implemented as prefix
*/
public function getNamespaceSeparator(): string;

/**
* Set the namespace separator if namespace is implemented as prefix
*/
public function setNamespaceSeparator(stdClass $marker, string $separator): self;
}
```

Expand All @@ -192,37 +68,12 @@ $container = null; // can be any configured PSR-11 container
$storageFactory = $container->get(StorageAdapterFactoryInterface::class);

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

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

### Listen to the change Event

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

/** @var ContainerInterface $container */
$container = null; // can be any configured PSR-11 container

/** @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);
```
```
Loading