redhead/cached

A Kdyby\Aop aspect for caching method return values

Cached

A Nette framework extension providing a Kdyby\Aop aspect for caching method return values., _(*1)

Installation

First, install the Kdyby\Aop extension., _(*2)

Require the extension files using composer:, _(*3)

$ composer require redhead/cached:@dev

In your Nette application configuration, add the extension to be registered and the caching aspect:, _(*4)

extensions:
    cached: Cached\CachedExtension

aspects:
    - Cached\CachingAspect(@cacheStorage)

where @cacheStorage is a reference to a service implementing Nette\Caching\IStorage (you can specify your own storage, or remove the argument so the dependecy will be autowired), _(*5)

Usage

Now, you can put annotation @Cached on methods in your services like this:, _(*6)

class MyService {

  /**
   * @Cached\Cached
   */
  public function getNumber() {
    return rand(1, 1000);
  }

}

Note: due to a bug in Kdyby\Aop, you can't import the annotation with use statements at this moment. Until it's fixed you have to provide fully qualified name of the annotation (@Cached\Cached), _(*7)

After the first call of the method above, the return value is cached. Every other call will not execute the method and will return the cached value instead., _(*8)

Annotation properties

There are few properties you can use in the annotation. They specify the caching options. See the example:, _(*9)

...
  /**
   * @Cached\Cached(key="myService.number", sliding=true, expire="1 hour")
   */
  public function getNumber() {
    return rand(1, 1000);
  }
...

Annotation options are following:, _(*10)

• namespace (string) - the namespace to use for caching, defaults to the name of the profile (see below)
• key (string) - the key under which the return value is stored in the cache, defaults to concatenation of class name, method name and serialized parameters
• profile (string) - the name of the cache profile to use, defaults to 'default' (see below)
• expire (string) - specifies the time the cache will expire
• sliding (boolean) - if the sliding feature should be used
• tags (array) - tags for clearing the cache
• files (array) - the paths to files that will trigger the cache expiration when edited
• priority (integer) - the priority number

Cache profiles

You can specify the settings for the above options that are shared across many advised methods, so you don't need to write them all the time. The settings will be in one place - in your config file!, _(*11)

To create a profile, add section 'cached' and subsection 'profiles' to your configuration. Then add another subsection bearing the name of your profile and set the profile options. See the example:, _(*12)

cached:
    profiles:
        myProfile:
            sliding: true
            expire: 1 hour

Then add annotation property 'profile' with the name of the profile as a value to the advised methods you want to share the options with., _(*13)

...
  /**
   * @Cached\Cached(profile="myProfile")
   */
...

You can set additional options and/or override the options of the profile by adding properties to the annotation., _(*14)

When no profile is specified, it defaults to profile 'default' the options of which you can set in the configuration. The options for this profile will be used for every method annotated without property 'profile'., _(*15)

Profile options

Profile options are almost the same as annotation properties. There are few differences. You can specify these options: - enabled (boolean) - if false, no caching is performed and the original method will get called every time (caching is completely disabled for this profile), defaults to true - namespace (same as above) - expire (same as above) - sliding (same as above) - tags (same as above) - files (same as above) - priority (same as above), _(*16)

Profile options are missing 'key' and 'profile' annotation property counterparts (as they don't make any sense here)., _(*17)

Extension options

You can specify options for the whole extension in the extension's config section:, _(*18)

• enabled (boolean) - if false, caching is disabled for all annotations and profiles, no caching is performed at all, defaults to true

Configuration example

Here is an example of the whole configuration setup and usage of every config option:, _(*19)

extensions:
    aop: Kdyby\Aop\DI\AopExtension
    annotations: Kdyby\Annotations\DI\AnnotationsExtension
        cached: Cached\CachedExtension

aspects:
    - Cached\CachingAspect

cached:
    enabled: true
    profiles:
        default:
            enabled: true
            namespace: myNamespace
            expire: 1 hour
            sliding: true
            files: [file1.php, file2.php]
            tags: [tag1, tag2]
            priority: 1
        myProfile:
            ...