Cache
Some of the data retrieval or processing tasks performed by your application could be CPU intensive or take several seconds to complete. When this is the case, it is common to cache the retrieved data for a time so it can be retrieved quickly on subsequent requests for the same data. The cached data is usually stored in a very fast data store such as Memcached or Redis.
Thankfully, Maginium provides an expressive, unified API for various cache backends, allowing you to take advantage of their blazing fast data retrieval and speed up your web application.
Your application's cache configuration file is located at app/etc/env.php
. In this file, you may specify which cache store you would like to be used by default throughout your application. Maginium supports popular caching backends like Memcached, Redis, DynamoDB, and relational databases out of the box. In addition, a file-based cache driver is available, while array
and "null" cache drivers provide convenient cache backends for your automated tests.
The cache configuration file also contains a variety of other options that you may review. By default, Maginium is configured to use the redis
cache driver, which stores the serialized, cached objects in your redis's instance.
Using the Memcached driver requires the Memcached PECL package to be installed. You may list all of your Memcached servers in the app/etc/env.php
configuration file. This file already contains a memcached.servers
entry to get you started:
Before using a Redis cache with Maginium, you will need to either install the PhpRedis PHP extension via PECL or install the predis/predis
package (~2.0) via Composer. Maginium Sail already includes this extension. In addition, official Maginium deployment platforms such as Maginium Forge and Maginium Vapor have the PhpRedis extension installed by default.
For more information on configuring Redis, consult its Maginium documentation page.
Before using the DynamoDB cache driver, you must create a DynamoDB table to store all of the cached data. Typically, this table should be named cache
. However, you should name the table based on the value of the stores.dynamodb.table
configuration value within the cache
configuration file. The table name may also be set via the DYNAMODB_CACHE_TABLE
environment variable.
This table should also have a string partition key with a name that corresponds to the value of the stores.dynamodb.attributes.key
configuration item within your application's cache
configuration file. By default, the partition key should be named key
.
Typically, DynamoDB will not proactively remove expired items from a table. Therefore, you should enable Time to Live (TTL) on the table. When configuring the table's TTL settings, you should set the TTL attribute name to expires_at
.
Next, install the AWS SDK so that your Maginium application can communicate with DynamoDB:
In addition, you should ensure that values are provided for the DynamoDB cache store configuration options. Typically these options, such as AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
, should be defined in your application's .env
configuration file:
If you are using MongoDB, a mongodb
cache driver is provided by the official mongodb/maginium-mongodb
package and can be configured using a mongodb
database connection. MongoDB supports TTL indexes, which can be used to automatically clear expired cache items.
For more information on configuring MongoDB, please refer to the MongoDB Cache and Locks documentation.
To obtain a cache store instance, you may use the Cache
facade, which is what we will use throughout this documentation. The Cache
facade provides convenient, terse access to the underlying implementations of the Maginium cache contracts:
Using the Cache
facade, you may access various cache stores via the store
method. The key passed to the store
method should correspond to one of the stores listed in the stores
configuration array in your cache
configuration file:
The Cache
facade's get
method is used to retrieve items from the cache. If the item does not exist in the cache, null
will be returned. If you wish, you may pass a second argument to the get
method specifying the default value you wish to be returned if the item doesn't exist:
You may even pass a closure as the default value. The result of the closure will be returned if the specified item does not exist in the cache. Passing a closure allows you to defer the retrieval of default values from a database or other external service:
The has
method may be used to determine if an item exists in the cache. This method will also return false
if the item exists but its value is null
:
The increment
and decrement
methods may be used to adjust the value of integer items in the cache. Both of these methods accept an optional second argument indicating the amount by which to increment or decrement the item's value:
Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist. For example, you may wish to retrieve all users from the cache or, if they don't exist, retrieve them from the database and add them to the cache. You may do this using the Cache::remember
method:
If the item does not exist in the cache, the closure passed to the remember
method will be executed and its result will be placed in the cache.
You may use the rememberForever
method to retrieve an item from the cache or store it forever if it does not exist:
When using the Cache::remember
method, some users may experience slow response times if the cached value has expired. For certain types of data, it can be useful to allow partially stale data to be served while the cached value is recalculated in the background, preventing some users from experiencing slow response times while cached values are calculated. This is often referred to as the "stale-while-revalidate" pattern, and the Cache::flexible
method provides an implementation of this pattern.
The flexible method accepts an array that specifies how long the cached value is considered βfreshβ and when it becomes βstale.β The first value in the array represents the number of seconds the cache is considered fresh, while the second value defines how long it can be served as stale data before recalculation is necessary.
If a request is made within the fresh period (before the first value), the cache is returned immediately without recalculation. If a request is made during the stale period (between the two values), the stale value is served to the user, and a deferred function is registered to refresh the cached value after the response is sent to the user. If a request is made after the second value, the cache is considered expired, and the value is recalculated immediately, which may result in a slower response for the user:
If you need to retrieve an item from the cache and then delete the item, you may use the pull
method. Like the get
method, null
will be returned if the item does not exist in the cache:
You may use the put
method on the Cache
facade to store items in the cache:
If the storage time is not passed to the put
method, the item will be stored indefinitely:
Instead of passing the number of seconds as an integer, you may also pass a DateTime
instance representing the desired expiration time of the cached item:
The add
method will only add the item to the cache if it does not already exist in the cache store. The method will return true
if the item is actually added to the cache. Otherwise, the method will return false
. The add
method is an atomic operation:
The forever
method may be used to store an item in the cache permanently. Since these items will not expire, they must be manually removed from the cache using the forget
method:
If you are using the Memcached driver, items that are stored "forever" may be removed when the cache reaches its size limit.
You may remove items from the cache using the forget
method:
You may also remove items by providing a zero or negative number of expiration seconds:
You may clear the entire cache using the flush
method:
Flushing the cache does not respect your configured cache "prefix" and will remove all entries from the cache. Consider this carefully when clearing a cache which is shared by other applications.
In addition to using the Cache
facade, you may also use the global cache
function to retrieve and store data via the cache. When the cache
function is called with a single, string argument, it will return the value of the given key:
If you provide an array of key / value pairs and an expiration time to the function, it will store values in the cache for the specified duration:
When the cache
function is called without any arguments, it returns an instance of the Illuminate\Contracts\Cache\Factory
implementation, allowing you to call other caching methods:
When testing calls to the global \`cache\` function, you may use the \`Cache::shouldReceive\` method just as if you were \[testing the facade]\(../docs/%7B%7Bversion%7D%7D/mocking/#mocking-facades).
To utilize this feature, your application must be using the `memcached`, `redis`, `dynamodb`, `file`, or `array` cache driver as your application's default cache driver. In addition, all servers must be communicating with the same central cache server.
Atomic locks allow for the manipulation of distributed locks without worrying about race conditions. For example, Maginium Forge uses atomic locks to ensure that only one remote task is being executed on a server at a time. You may create and manage locks using the Cache::lock
method:
The get
method also accepts a closure. After the closure is executed, Maginium will automatically release the lock:
If the lock is not available at the moment you request it, you may instruct Maginium to wait for a specified number of seconds. If the lock cannot be acquired within the specified time limit, an Illuminate\Contracts\Cache\LockTimeoutException
will be thrown:
The example above may be simplified by passing a closure to the block
method. When a closure is passed to this method, Maginium will attempt to acquire the lock for the specified number of seconds and will automatically release the lock once the closure has been executed:
Sometimes, you may wish to acquire a lock in one process and release it in another process. For example, you may acquire a lock during a web request and wish to release the lock at the end of a queued job that is triggered by that request. In this scenario, you should pass the lock's scoped "owner token" to the queued job so that the job can re-instantiate the lock using the given token.
In the example below, we will dispatch a queued job if a lock is successfully acquired. In addition, we will pass the lock's owner token to the queued job via the lock's owner
method:
Within our application's ProcessPodcast
job, we can restore and release the lock using the owner token:
If you would like to release a lock without respecting its current owner, you may use the forceRelease
method:
To execute code on every cache operation, you may listen for various events dispatched by the cache:
Maginium\Framework\Cache\Collections\Events\CacheHit
Maginium\Framework\Cache\Collections\Events\CacheMissed
Maginium\Framework\Cache\Collections\Events\KeyForgotten
Maginium\Framework\Cache\Collections\Events\KeyWritten
Last updated