Class: Smart.Framework Abstract Persistent Cache.
The backends used for Persistent Cache must be very fast, must support large keys and must supply key expiration by time.
If the key expiration is not supported natively, then a custom function must be created to delete expired keys.
It must contain ONLY public functions to avoid late state binding (self:: vs static::)
Language: PHP
Located at: lib/framework/lib_caching.php
Package: development:Application
Namespace: \
Class Name: SmartAbstractPersistentCache
Version: v.20221220
Depends: classes: Smart
Internal-Private: YES
class Methods
public staticfunctiongetVersionInfo (
) {} :: STRING
@return: {STRING}
Get the version info about the Persistent Cache
public staticfunctionisActive (
) {} :: BOOLEAN
@return: {BOOLEAN} TRUE if is Active or FALSE if not
Check if the persistent Cache is Active
public staticfunctionisMemoryBased (
) {} :: BOOLEAN
@return: {BOOLEAN} TRUE if is Memory Based (Ex: Redis / Memcached / ...) or FALSE if not
Check if the persistent Cache is Memory Based.
This function must ALWAYS be used in conjunction with isActive() as it will return TRUE just if the backend is a Memory Based one and will not check if Backed is Active or not ...
This function should be used in some caching scenarios to check if make sense to cache things in Persistent Cache or not (Ex: if something make sense to be stored in a Memory based Cache)
public staticfunctionisFileSystemBased (
) {} :: BOOLEAN
@return: {BOOLEAN} TRUE if is FileSystem Based (Ex: SQLite / DBA / ...) or FALSE if not
Check if the persistent Cache is FileSystem Based.
Notice: DBA or SQLite are both FileSystem + Database based, this may return true to both - this function but aso isDbBased()
This function must ALWAYS be used in conjunction with isActive() as it will return TRUE just if the backend is a FileSystem Based one and will not check if Backed is Active or not ...
This function should be used in some caching scenarios to check if make sense to cache things in Persistent Cache or not (Ex: if something make sense to be stored in a FileSystem based Cache)
public staticfunctionisDbBased (
) {} :: BOOLEAN
@return: {BOOLEAN} TRUE if is Database Based (Ex: PostgreSQL / MySQL / MongoDB / SQLite / DBA / ...) or FALSE if not
Check if the persistent Cache is Database Based.
Notice: DBA or SQLite are both FileSystem + Database based, this may return true to both - this function but aso isFileSystemBased()
Notice: PostgreSQL / MySQL / MongoDB are real DB servers so must return TRUE to this function but must return FALSE to isFileSystemBased() because they have advanced storage systems not a typical prefixed folder storage on Disk
This function must ALWAYS be used in conjunction with isActive() as it will return TRUE just if the backend is a FileSystem Based one and will not check if Backed is Active or not ...
This function should be used in some caching scenarios to check if make sense to cache things in Persistent Cache or not (Ex: if something make sense to be stored in a Database based Cache)
public staticfunctionclearData (
) {} :: BOOLEAN
@return: {BOOLEAN} TRUE if is success or FALSE if fail
Empty the persistent Cache by deleting all existing keys.
public staticfunctionkeyExists (
string$y_realm,
string$y_key
) {} :: BOOLEAN
@return: {BOOLEAN} TRUE if Key Exists or FALSE if not
@param: {STRING} $y_realm: The Cache Realm
@param: {STRING} $y_key: The Cache Key
Check if a Key exists in the persistent Cache
public staticfunctiongetTtl (
string$y_realm,
string$y_key
) {} :: INTEGER
@return: {INTEGER} number of seconds the key will expire ; -1 if the key does not expire (is persistent) ; -2 if the key does not exists ; -3 if N/A or ERR
@param: {STRING} $y_realm: The Cache Realm
@param: {STRING} $y_key: The Cache Key
get the TTL in seconds for a key from the persistent Cache or Error code
public staticfunctiongetKey (
string$y_realm,
string$y_key
) {} :: MIXED
@return: {MIXED} The value of the stored key or NULL if key not found in cache
@param: {STRING} $y_realm: The Cache Realm
@param: {STRING} $y_key: The Cache Key
@return: {BOOLEAN} Returns True if the key was set or false if not
@param: {STRING} $y_realm: The Cache Realm
@param: {STRING} $y_key: The Cache Key
@param: {MIXED} $y_value: The value to be stored
@param: {INTEGER+} $y_expiration: Key Expiration in seconds (zero if key does not expire)
Set a Key into the persistent Cache
public staticfunctionunsetKey (
string$y_realm,
string$y_key
) {} :: BOOLEAN
@return: {BOOLEAN} Returns True if the key(s) was/were unset or false if not
@param: {STRING} $y_realm: The Cache Realm
@param: {STRING} $y_key: The Cache Key ; Use * for All Keys in that Realm
Unset a Key into the persistent Cache
final public staticfunctioncachePathPrefix (
int$y_len,
string$y_realm,
string$y_key = ""
) {} :: STRING
@return: {STRING} The 2..4 letters cache path prefix (contains: 0..9 a..z) expanded to a path ; Ex: `x/y` or `x/y/9` or `x/y/9/z`
@param: {INTEGER+} $y_len: The Cache Prefix length (how many dirs in the expanded path) ; can be between 2..4 depending how will scale the cache structure
@param: {STRING} $y_realm: The Cache Realm
@param: {STRING} $y_key: *Optional* The Cache Key
Create a (safe path) Persistent Cache Path prefix for a given realm
This is mainly designed to be used by the FileSystem based persistent cache implementations, but can be used also for other purposes
final public staticfunctionvalidateRealm (
string$y_realm
) {} :: BOOLEAN
@return: {BOOLEAN} Returns TRUE if the realm is valid or FALSE if not
@param: {STRING} $y_realm: The Cache Realm that must be previous prepared with PersistentCache::safeKey() if non-empty
Validate persistent Cache Realm
Can be empty or must comply with PersistentCache::safeKey() restricted charset: _ a-z A-Z 0-9 - . @ # /
Must be between 0 (min) and 255 (max) characters long
final public staticfunctionvalidateKey (
string$y_key
) {} :: BOOLEAN
@return: {BOOLEAN} Returns TRUE if the key is valid or FALSE if not
@param: {STRING} $y_key: The Cache Key that must be previous prepared with PersistentCache::safeKey()
Validate persistent Cache Key
Cannot be empty and must comply with self::safeKey() restricted charset: _ a-z A-Z 0-9 - . @ # /
final public staticfunctionvalidateValue (
string$y_value
) {} :: BOOLEAN
@hints: If the value is oversized try to archive it before SET using SmartPersistentCache::varCompress() and after GET use SmartPersistentCache::varUncompress()
@return: {BOOLEAN} Returns TRUE if the value is valid or FALSE if not
@param: {STRING} $y_value: The Cache Value to be tested
Validate persistent Cache Value
Should not be not empty and not oversized (max ~16MB minus 65KB reserved for metainfo)
final public staticfunctionsafeKey (
string$y_key_or_realm
) {} :: STRING
@return: {STRING} Returns the safe prepared Key or Realm
@param: {STRING} $y_key_or_realm: The Cache Key or Realm
Prepare a persistent Cache SAFE Key or Realm
Works only for Keys (that can not be empty) and for non-empty Realms
Will return a prepared string with a restricted charset: _ a-z A-Z 0-9 - . @ # /
final public staticfunctionvarEncode (
MIXED$y_var
) {} :: STRING
@return: {STRING} Returns the safe serialized variable content
@param: {MIXED} $y_var: The Variable to be encoded
Encode a MIXED variable (array / string / number) to be stored in Persistent Cache
To reverse encoding use varDecode()
By default only numbers and strings can be stored as flat values.
To store complex variables like Arrays, use this function before setKey() which will serialize the var as Json standard.
final public staticfunctionvarDecode (
string$y_encoded_var
) {} :: MIXED
@return: {MIXED} Returns the original restored type and value of that variable
@param: {STRING} $y_encoded_var: The encoded variable
Decode a previous encoded MIXED variable (array / string / number) that was stored in Persistent Cache
To be used for variables previous encoded using varEncode()
By default only numbers and strings can be stored as flat values.
To retrieve complex variables like Arrays, use this function after getKey() which will unserialize the var from Json standard.
final public staticfunctionvarCompress (
MIXED$y_var
) {} :: STRING
@return: {STRING} Returns the safe serialized + compressed variable content
@param: {MIXED} $y_var: The Variable to be encoded + compressed
Compress + Encode a MIXED variable (array / string / number) to be stored in Persistent Cache
To reverse the compressing + encoding use varUncompress()
Use this function to store any type of variables: numbers, strings or arrays in a safe encoded + compressed format.
By default the variable will be: encoded (serialized as Json), compressed (gzencode/6/gzip) and finally B64-Encoded.
final public staticfunctionvarUncompress (
string$y_cache_arch_var
) {} :: MIXED
@return: {MIXED} Returns the original restored type and value of that variable
@param: {STRING} $y_cache_arch_var: The compressed + encoded variable
Uncompress + Decode a MIXED variable (array / string / number) to be stored in Persistent Cache
Use this function to retrieve any type of variables: numbers, strings or arrays that were previous safe encoded + compressed.
By default the variable will be: B64-Decoded, uncompressed (gzdecode) and finally decoded (unserialized from Json).
class Properties
class Constants
documentation generated on: 2023-10-19 23:15:44 +0000
The backends used for Persistent Cache must be very fast, must support large keys and must supply key expiration by time.
If the key expiration is not supported natively, then a custom function must be created to delete expired keys.
It must contain ONLY public functions to avoid late state binding (self:: vs static::)