Recommend this page to a friend! |
Classes of Caleb | PHP Common Class Library | _docs/Cache.md | Download |
|
DownloadDocumentation for the "Cache" class.A simple, unified cache handler used by CIDRAM and phpMussel for their caching needs. Currently, it supports APCu, Memcached, Redis, PDO, and flatfile caching. How to use:Let's start with an example. CIDRAM leverages the Cache class via the
The above example can be broken down into four main parts: 1. Instantiation.Before we can do anything else with the Cache class, an instance of it must be created.
Note: If you want the instance to store and fetch cache items internally, within itself only, instead of storing and fetching cache items using any of the various supported caching mechanisms (i.e., instead of using APCu, Memcached, Redis, PDO, flatfile caching, etc), you can supply an array of cache items as the sole parameter of the constructor during instantiation. Otherwise (and in most cases generally), no parameters should be supplied to the constructor during instantiation. 2. Configuration.After creating an instance of Cache, before leveraging any of its methods, we should configure it. The excerpt below is provided as an example (the actual values used in the excerpt are the default values for the instance members the values are being assigned to, and therefore have no effect in this particular example; they're optional too, and so, any that aren't likely to ever be needed by the implementation can effectively be omitted and ignored).
The correct values to use, and the best way to configure the instance, depends on which caching mechanisms you want to use, whether those caching mechanisms are available in your environment, and how those caching mechanisms themselves are configured (e.g., the correct host and port number to use might be different than the default for your particular environment, and if so, you'll need to determine that information for yourself). I would, in most cases, recommend defining Beyond that, I would recommend defining values only for the members that relate to caching mechanisms that you already know are available, and that you could foreseeably utilise for your implementation, omitting definitions for the members that relate to anything that you know to be unavailable or otherwise unsuitable for your implementation. If all of the supported caching mechanisms are available in your environment, and you're having difficulty deciding which to use, I would generally recommend APCu above the others, due to its simplicity: The only member you would need to define is 3. Connection.After creating an instance of Cache and configuring it, before leveraging any of its methods, we need to connect to our chosen caching mechanism. We do this using the
The
4. Handling failures.In most cases, if an implementation implements a caching solution, it does so because doing so is necessary for correct functionality of the implementation, and it therefore won't be desirable in most cases for the implementation to continue execution when its implemented caching solution fails. In the case of implementing this particular class, the need to handle failure arises when the In the earlier above example, CIDRAM does this by printing the message to the end-user, "unable to write to the cache" ( What next?Now that you've configured and connected to an instance of Cache, you can create new cache items using Note that the destructor is responsible for closing any connections opened by All public methods provided by Cache, along with relevant instructions, are listed below.
__construct method.The class constructor.
__destruct method.The class destructor.
connect method.Connects the instance to a caching mechanism per the instance configuration (examples provided earlier in the documentation). Doesn't accept any parameters.
getEntry method.Returns an entry from the cache, or false on failure. Accepts the name of the cache entry as its sole parameter.
setEntry method.Writes an entry to the cache, returning true on success, or false on failure.
deleteEntry method.Deletes an entry from the cache, returning true on success, or false on failure (this could be either a hard failure, caused by some unknown problem with the cache mechanism being used, or could simply be that the cache entry doesn't exist, because it was already deleted earlier, or never existed at all).
clearCache method.Deletes all entries from the cache, returning true on success, or false on failure. Doesn't accept any parameters.
getAllEntries method.Returns an associative array containing all entries from the cache (the array will be empty when no entries can be retrieved). Doesn't accept any parameters.
clearExpired method.Deletes all expired cache entries from an array of cache entries, supplied by reference as the method's sole parameter. Returns true when one or more entries are deleted (meaning that the size of the referenced array should be reduced as a result of using the method), or false when nothing is deleted (meaning that the referenced array should remain unchanged as a result of using the method). There are some other methods that rely on this method, but note that this method itself doesn't rely on any other methods, and also isn't directly tied to your choice of caching mechanism, nor requires that you connect to anything. Note that this method is also called by the destructor (and thus will be called when the instance is destroyed anyway). In most cases, you won't need to call it specifically from your implementation, but it is exposed as public nonetheless, just in case you need to call it specifically from your implementation for whatever reason (e.g., to forcibly delete expired cache entries prior to destroying the instance).
clearExpiredPDO method.Deletes all expired cache entries stored using PDO. Doesn't accept any parameters. Returns true when one or more entries are deleted, or false when nothing is deleted (false could also be returned when calling Note that this method won't be useful unless you're using PDO. Note that this method is also called by the destructor (and thus will be called when the instance is destroyed anyway). In most cases, you won't need to call it specifically from your implementation, but it is exposed as public nonetheless, just in case you need to call it specifically from your implementation for whatever reason (e.g., to forcibly delete expired cache entries prior to destroying the instance).
unserializeEntry method.Used by various other methods to unserialize a returned cache entry. Accepts a serialized cache entry as its sole parameter. In most cases, you won't need to call it specifically from your implementation, but it is exposed as public nonetheless, just in case you need to call it specifically from your implementation for whatever reason (e.g., for testing purposes).
serializeEntry method.Used by various other methods to serialize a cache entry prior to committing it. Accepts the value of the cache entry as its sole parameter. In most cases, you won't need to call it specifically from your implementation, but it is exposed as public nonetheless, just in case you need to call it specifically from your implementation for whatever reason (e.g., for testing purposes).
stripObjects method.Attempts to strip objects from a data set (could be useful as a security precaution to be used prior to writing cache entries, if an implementation is forced to accept data from untrusted sources for whatever reason). The data set can be of any data type, and the data set (sans objects) will be returned by the method. The method isn't used by any other methods in the class, and in most cases, will most likely never be needed, but is provided nonetheless, in case the implementation needs such a thing (it is thus the responsibility of the implementation to call the method if and when it becomes necessary). However, accepting data from untrusted sources is extremely inadvisable, and every reasonable measure should be taken to avoid it.
The reason that you might want to strip objects from a data set prior to caching it (and by extension, the reason that you shouldn't be caching data from untrusted sources), is that cache entries are serialized when committed, unserialized when fetched, and magic methods (e.g., exposeWorkingDataArray method.Used to expose the instance's working data array. This can be useful when integrating the instance with external caching mechanisms that the class doesn't natively support. The method is also used internally by the
Last Updated: 22 May 2019 (2019.05.22). |