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

Jump to bottom

Deprecate PatternOptions storage option #98

Merged
merged 7 commits into from Jul 11, 2021
Merged

Deprecate PatternOptions storage option #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5b9a463
qa: deprecate `storage` option for `PatternOptions`
boesing May 2, 2021
95ed298
qa: escape pipes in markdown to support more markdown reader
boesing May 8, 2021
c92c394
docs: add `Standard Storage Adapter` example to the pattern cache qui…
boesing May 16, 2021
a1adb4c
qa: remove `TODO`
boesing Jun 6, 2021
33a3c9c
docs: optimize standard storage adapter documentation
boesing Jun 6, 2021
1208e17
docs: update documentation header for the example of caching view scr…
boesing Jun 6, 2021
1a9caf6
docs: optimize cached feed reader documentation
boesing Jun 6, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
54 changes: 25 additions & 29 deletions docs/book/pattern/callback-cache.md
View file
Open in desktop
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.

boesing marked this conversation as resolved.
Show resolved Hide resolved
## 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
Open in desktop
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
Open in desktop
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
Open in desktop
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;
}
```