Skip to content

Commit

Permalink
Merge pull request #98 from boesing/qa/pattern-options-storage-option
Browse files Browse the repository at this point in the history 
Deprecate `PatternOptions` `storage` option
  • Loading branch information
@boesing
boesing committed Jul 11, 2021
2 parents e419f8b + 1a9caf6 commit 93ea2fe
Show file tree
Hide file tree
Showing 32 changed files with 888 additions and 418 deletions.
54 changes: 25 additions & 29 deletions docs/book/pattern/callback-cache.md
View file
Expand Up @@ -5,42 +5,50 @@ The callback cache pattern caches the results of arbitrary PHP callables.
## Quick Start

```php
use Laminas\Cache\PatternFactory;
use Laminas\Cache\Pattern\CallbackCache;
use Laminas\Cache\Pattern\PatternOptions;

// Via the factory:
$callbackCache = PatternFactory::factory('callback', [
'storage' => 'apc',
'cache_output' => true,
]);

// Or the equivalent manual instantiation:
$callbackCache = new \Laminas\Cache\Pattern\CallbackCache();
$callbackCache->setOptions(new PatternOptions([
'storage' => 'apc',
'cache_output' => true,
]));
$callbackCache = new CallbackCache(
$storage,
new PatternOptions([
'cache_output' => true,
])
);
```

> ### Storage Adapter
>
> The `$storage` adapter can be any adapter which implements the `StorageInterface`. Check out the [Pattern Quick Start](./intro.md#quick-start)-Section for a standard adapter which can be used here.
## Configuration Options

Option | Data Type | Default Value | Description
------ | --------- | ------------- | -----------
`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | Adapter used for reading and writing cached data.
`cache_output` | `boolean` | `true` | Whether or not to cache callback output.
`storage` | `string\|array\|Laminas\Cache\Storage\StorageInterface` | none | **deprecated** Adapter used for reading and writing cached data.
`cache_output` | `bool` | `true` | Whether or not to cache callback output.

## Examples

### Instantiating the Callback Cache Pattern

```php
use Laminas\Cache\Pattern\CallbackCache;

$callbackCache = new CallbackCache($storage);
```

## Available Methods

In addition to the methods defined in the `PatternInterface`, this
In addition to the methods defined in the `PatternInterface` and the `StorageCapableInterface`, this
implementation provides the following methods.

```php
namespace Laminas\Cache\Pattern;

use Laminas\Cache\Exception;
use Laminas\Stdlib\ErrorHandler;

class CallbackCache extends AbstractPattern
class CallbackCache extends AbstractStorageCapablePattern
{
/**
* Call the specified callback or get the result from cache
Expand Down Expand Up @@ -77,15 +85,3 @@ class CallbackCache extends AbstractPattern
public function generateKey($callback, array $args = []);
}
```

## Examples

### Instantiating the Callback Cache Pattern

```php
use Laminas\Cache\PatternFactory;

$callbackCache = PatternFactory::factory('callback', [
'storage' => 'apc'
]);
```
66 changes: 36 additions & 30 deletions docs/book/pattern/capture-cache.md
View file
Expand Up @@ -20,10 +20,14 @@ ErrorDocument 404 /index.php
And add the cache to the related application script, e.g. `index.php`:

```php
use Laminas\Cache\PatternFactory;
$capture = Laminas\Cache\PatternFactory::factory('capture', [
'public_dir' => __DIR__,
]);
use Laminas\Cache\Pattern\CaptureCache;
use Laminas\Cache\Pattern\PatternOptions;

$capture = new CaptureCache(
new PatternOptions([
'public_dir' => __DIR__,
])
);

// Start capturing all output, excluding headers, and write to the public
// directory:
Expand All @@ -42,9 +46,34 @@ Option | Data Type | Default Value | Description
`public_dir` | `string` | none | Location of the public web root directory in which to write output.
`index_filename` | `string` | "index.html" | The name of the index file if only a directory was requested.
`file_locking` | `bool` | `true` | Whether or not to lock output files when writing.
`file_permission` | `int | bool` | `0600` (`false` on Windows) | Default permissions for generated output files.
`dir_permission` | `int | bool` | `0700` (`false` on Windows) | Default permissions for generated output directories.
`umask` | `int` | `bool` | `false` | Whether or not to umask generated output files / directories.
`file_permission` | `int\|false` | `0600` (`false` on Windows) | Default permissions for generated output files.
`dir_permission` | `int\|false` | `0700` (`false` on Windows) | Default permissions for generated output directories.
`umask` | `int\|false` | `false` | Whether or not to umask generated output files / directories.

## Examples

### Scaling Images in the Web Root

Using the following Apache 404 configuration:

```apacheconf
# .htdocs
ErrorDocument 404 /index.php
```

Use the following script:

```php
// index.php
use Laminas\Cache\Pattern\CaptureCache;
use Laminas\Cache\Pattern\PatternOptions;

$capture = new CaptureCache(
new PatternOptions([
'public_dir' => __DIR__,
])
);
```

## Available Methods

Expand All @@ -55,7 +84,6 @@ exposes the following methods.
namespace Laminas\Cache\Pattern;

use Laminas\Cache\Exception;
use Laminas\Stdlib\ErrorHandler;

class CaptureCache extends AbstractPattern
{
Expand Down Expand Up @@ -122,25 +150,3 @@ class CaptureCache extends AbstractPattern
public function getFilename($pageId = null);
}
```

## Examples

### Scaling Images in the Web Root

Using the following Apache 404 configuration:

```apacheconf
# .htdocs
ErrorDocument 404 /index.php
```

Use the following script:

```php
// index.php
$captureCache = Laminas\Cache\PatternFactory::factory('capture', [
'public_dir' => __DIR__,
]);

// TODO
```
73 changes: 42 additions & 31 deletions docs/book/pattern/class-cache.md
View file
Expand Up @@ -8,34 +8,65 @@ class being cached, and caches static properties.
## Quick Start

```php
use Laminas\Cache\PatternFactory;

$classCache = PatternFactory::factory('class', [
'class' => 'MyClass',
'storage' => 'apc',
]);
use Laminas\Cache\Pattern\ClassCache;
use Laminas\Cache\Pattern\PatternOptions;

$classCache = new ClassCache(
$storage,
new PatternOptions([
'class' => 'MyClass',
])
);
```

> ### Storage Adapter
>
> The `$storage` adapter can be any adapter which implements the `StorageInterface`. Check out the [Pattern Quick Start](./intro.md#quick-start)-Section for a standard adapter which can be used here.
## Configuration Options

Option | Data Type | Default Value | Description
------ | --------- | ------------- | -----------
`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | Adapter used for reading and writing cached data.
`storage` | `string\|array\|Laminas\Cache\Storage\StorageInterface` | none | **deprecated** Adapter used for reading and writing cached data.
`class` | `string` | none | Name of the class for which to cache method output.
`cache_output` | `boolean` | `true` | Whether or not to cache method output.
`cache_by_default` | `boolean` | `true` | Cache all method calls by default.
`cache_output` | `bool` | `true` | Whether or not to cache method output.
`cache_by_default` | `bool` | `true` | Cache all method calls by default.
`class_cache_methods` | `array` | `[]` | List of methods to cache (if `cache_by_default` is disabled).
`class_non_cache_methods` | `array` | `[]` | List of methods to omit from caching (if `cache_by_default` is enabled).

## Examples

### Caching of Import Feeds

```php
use Laminas\Cache\Pattern\ClassCache;
use Laminas\Cache\Pattern\PatternOptions;
use \Laminas\Feed\Reader\Reader;

$cachedFeedReader = new ClassCache(
$storage,
new PatternOptions([
'class' => Reader::class,

// The feed reader doesn't output anything,
// so the output doesn't need to be caught and cached:
'cache_output' => false,
])
);

$feed = $cachedFeedReader->call("import", ['https://github.com/laminas/laminas-cache/releases.atom']);
// or
$feed = $cachedFeedReader->import('https://github.com/laminas/laminas-cache/releases.atom');
```

## Available Methods

In addition to the methods defined in `PatternInterface`, this implementation
In addition to the methods defined in `PatternInterface` and the `StorageCapableInterface`, this implementation
exposes the following methods.

```php
namespace Laminas\Cache\Pattern;

use Laminas\Cache;
use Laminas\Cache\Exception;

class ClassCache extends CallbackCache
Expand Down Expand Up @@ -128,23 +159,3 @@ class ClassCache extends CallbackCache
}
}
```

## Examples

### Caching of Import Feeds

```php
$cachedFeedReader = Laminas\Cache\PatternFactory::factory('class', [
'class' => 'Laminas\Feed\Reader\Reader',
'storage' => 'apc',

// The feed reader doesn't output anything,
// so the output doesn't need to be caught and cached:
'cache_output' => false,
]);

$feed = $cachedFeedReader->call("import", array('http://www.planet-php.net/rdf/'));

// OR
$feed = $cachedFeedReader->import('http://www.planet-php.net/rdf/');
```
51 changes: 32 additions & 19 deletions docs/book/pattern/intro.md
View file
Expand Up @@ -22,39 +22,39 @@ It's also possible to use a single instance of

## Quick Start

Pattern objects can either be created from the provided `Laminas\Cache\PatternFactory`, or
Pattern objects can be created
by instantiating one of the `Laminas\Cache\Pattern\*Cache` classes.

> ### Standard Storage Adapter for Documentation
>
> A cache adapter needs a storage adapter. To be able to follow the examples in the documentation, the [adapter for the filesystem](https://docs.laminas.dev/laminas-cache/storage/adapter/#filesystem-adapter) or the [BlackHole adapter](https://docs.laminas.dev/laminas-cache/storage/adapter/#blackhole-adapter) can be used, for example.
>
> ```php
> $storage = new Laminas\Cache\Storage\Adapter\Filesystem();
> // or
> $storage = new Laminas\Cache\Storage\Adapter\BlackHole();
> ```
```php
// Via the factory:
$callbackCache = Laminas\Cache\PatternFactory::factory('callback', [
'storage' => 'apc',
]);

// Or the equivalent manual instantiation:
$callbackCache = new Laminas\Cache\Pattern\CallbackCache();
$callbackCache->setOptions(new Laminas\Cache\Pattern\PatternOptions([
'storage' => 'apc',
]));
use Laminas\Cache\Pattern\CallbackCache;
use Laminas\Cache\Pattern\PatternOptions;

$callbackCache = new CallbackCache(
$storage,
new PatternOptions()
);
```

## Available Methods

The following methods are implemented by `Laminas\Cache\Pattern\AbstractPattern`.
The following methods are implemented by every cache pattern.
Please read documentation of specific patterns to get more information.

```php
namespace Laminas\Cache\Pattern;

interface PatternInterface
{
/**
* Set pattern options
*
* @param PatternOptions $options
* @return PatternInterface
*/
public function setOptions(PatternOptions $options);

/**
* Get all pattern options
Expand All @@ -64,3 +64,16 @@ interface PatternInterface
public function getOptions();
}
```

There are cache patterns which depend on a storage. In this case, these adapters implement the `StorageCapableInterface`:

```php
namespace Laminas\Cache\Pattern;

use Laminas\Cache\Storage\StorageInterface;

interface StorageCapableInterface extends PatternInterface
{
public function getStorage(): ?StorageInterface;
}
```

0 comments on commit 93ea2fe

Please sign in to comment.