Documentation

CRM_Utils_Cache
in package

Cache is an empty base object, we'll modify the scheme when we have different caching schemes

Table of Contents

Constants

DELIMITER  = '/'

Properties

$_singleton  : object
(Quasi-Private) Treat this as private. It is marked public to facilitate testing.

Methods

__construct()  : CRM_Utils_Cache
Constructor.
assertValidKey()  : string
Assert that a key is well-formed.
cleanKey()  : string
Normalize a cache key.
create()  : CRM_Utils_Cache_Interface
Create a new, named, limited-use cache.
getCacheDriver()  : string
getCacheSettings()  : array<string|int, mixed>
Get cache relevant settings.
nack()  : string
Generate a unique negative-acknowledgement token (NACK).
singleton()  : CRM_Utils_Cache_Interface
Singleton function used to manage this object.

Constants

DELIMITER

public mixed DELIMITER = '/'

Properties

$_singleton

(Quasi-Private) Treat this as private. It is marked public to facilitate testing.

public static object $_singleton = \NULL

We only need one instance of this object. So we use the singleton pattern and cache the instance in this variable

Methods

assertValidKey()

Assert that a key is well-formed.

public static assertValidKey(string $key) : string
Parameters
$key : string
Tags
throws
CRM_Utils_Cache_InvalidArgumentException
Return values
string —

Same $key, if it's valid.

cleanKey()

Normalize a cache key.

public static cleanKey(string $key) : string

This bridges an impedance mismatch between our traditional caching and PSR-16 -- PSR-16 accepts a narrower range of cache keys.

Parameters
$key : string

Ex: 'ab/cd:ef'

Return values
string —

Ex: '_abcd1234abcd1234' or 'ab_xx/cd_xxef'. A similar key, but suitable for use with PSR-16-compliant cache providers.

create()

Create a new, named, limited-use cache.

public static create([array<string|int, mixed> $params = [] ]) : CRM_Utils_Cache_Interface

This is a factory function. Generally, you should use Civi::cache($name) to locate managed cached instance.

Parameters
$params : array<string|int, mixed> = []

Array with keys:

  • name: string, unique symbolic name. For a naming convention, use snake_case or CamelCase to maximize portability/cleanliness. Any other punctuation or whitespace should function correctly, but it can be harder to inspect/debug.
  • type: array|string, list of acceptable cache types, in order of preference.
  • prefetch: bool, whether to prefetch all data in cache (if possible).
  • withArray: bool|null|'fast', whether to setup a thread-local array-cache in front of the cache driver. Note that cache-values may be passed to the underlying driver with extra metadata, so this will slightly change/enlarge the on-disk format. Support varies by driver:
    • For most memory backed caches, this option is meaningful.
    • For SqlGroup, this option is ignored. SqlGroup has equivalent behavior built-in.
    • For ArrayCache, this option is ignored. It's redundant. If this is a short-lived process in which TTL's don't matter, you might use 'fast' mode. It sacrifices some PSR-16 compliance and cache-coherency protections to improve performance.
Tags
throws
CRM_Core_Exception
see
Civi::cache()
Return values
CRM_Utils_Cache_Interface

getCacheDriver()

public static getCacheDriver() : string
Return values
string —

Ex: 'ArrayCache', 'Memcache', 'Redis'.

getCacheSettings()

Get cache relevant settings.

public static getCacheSettings(string $cachePlugin) : array<string|int, mixed>
Parameters
$cachePlugin : string
Return values
array<string|int, mixed> —

associative array of settings for the cache

nack()

Generate a unique negative-acknowledgement token (NACK).

public static nack() : string

When using PSR-16 to read a value, the $cahce->get() will a return a default value on cache-miss, so it's hard to know if you've gotten a geniune value from the cache or just a default. If you're in an edge-case where it matters (and you want to do has()+get() in a single roundtrip), use the nack() as the default:

$nack = CRM_Utils_Cache::nack(); $value = $cache->get('foo', $nack); echo ($value === $nack) ? "Cache has a value, and we got it" : "Cache has no value".

The value should be unique to avoid accidental matches.

Return values
string —

Unique nonce value indicating a "negative acknowledgement" (failed read). If we need to accurately perform has($key)+get($key), we can use get($key,$nack).


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results