Download the PHP package aol/offload without Composer
On this page you can find all versions of the php package aol/offload. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package offload
Short Description Simplify cached PHP tasks: background refresh, last-known-good, and single writer.
License BSD-3-Clause
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package offload
Offload
Simplify cached PHP tasks: background refresh, last-known-good, and single writer.
Example:
This will run a task in the background and cache the returned $data under the task-key.
If the data is requested again, it will be returned immediately if in cache and a repopulation will be offload if the cache is stale.
How's This Work?
Offload caches data with two timeframes, fresh and stale. These TTLs can be controlled using options, see Offload Options.
- Fresh (cache hit): Data is immediately returned with no repopulation.
- Stale (cache hit, stale): Data is immediately returned and a repopulation is queued.
- No Data (cache miss): Forces the repopulation to run immediately and that data is then cached and returned.
Offload uses a task queue to keep track of stale cache hits that need to be repopulated. When
$offload->drain() is called, all tasks are run and the cache is repopulated. This is best to do once the
request is completed so that the overhead of repopulating cache does not interfere with returning a response
to the client quickly. See Draining the Offload Queue.
The OffloadManager can take any cache store implementing OffloadCacheInterface.
Exclusive Tasks
Tasks are run as exclusive by default. This behavior can be changed using options, see Offload Options.
Exclusive task repopulation means there will ever only be a single concurrent stale repopulation for a given key. This avoids the rush to repopulate cache that happens when a cached item expires.
The OffloadManager uses a lock implementation to provide this capability and can take any lock
implementing OffloadLockInterface.
Initialization
Here is an example of using a memcached instance for caching and a redis instance for locking:
Draining the Offload Queue
To drain the offload queue properly, it is best to setup a PHP shutdown handler. This ensures the offload tasks will always be run at the end of the request. Example:
Deferreds
Offload supports returning deferred tasks from the repopulate callable. This allows several tasks to run in parallel when the offload queue is drained.
For example, using Guzzle Async Requests:
The OffloadDeferred class takes a single callable that will wait for the result.
In the above example, $promise->wait() waits for the HTTP request to complete and returns the result.
The repopulate callable can return any class that implements the OffloadDeferredInterface, so you can
make adapters for custom async handling.
API
The OffloadManager implements OffloadManagerInterface and exposes the following methods:
OffloadManager |
|
|---|---|
fetch(...) |
Fetch data from cache and repopulate if necessary. |
fetchCached(...) |
Same as fetch(...) with a specific fresh cache TTL. |
queue(...) |
Queue a task to run. |
queueCached(...) |
Same as queue(...) with a specific fresh cache TTL. |
hasWork() |
Whether the offload manager has work. |
drain() |
Drain the offload manager task queue. |
getCache() |
An object for interacting with the cache manually. |
See below for more details on the above methods.
See Offload Options for more information on the $options that can be provided.
See Offload Result for more information on what OffloadResult details are returned.
Fetching Data
fetch
fetch($key, callable $repopulate, array $options = []): OffloadResult
Check cache for data for the given $key.
If the data is in cache, return it immediately.
If the data is stale, schedule a repopulate to run when the offload manager is drained.
fetchCached
fetchCached($key, $ttl_fresh, callable $repopulate, array $options = []): OffloadResult
Same as fetch. The following are equivalent:
Queuing Tasks
queue
queue($key, callable $repopulate, array $options = []): void
Queue a repopuate task to be run. Do not check cache. Takes similar options as fetch.
queueCached
queueCached($key, $ttl_fresh, callable $repopulate, array $options = []): void
Same as queue. The following are equivalent:
Fetch/Queue Arguments
| Option | Type | |
|---|---|---|
$key |
string |
The key of the data to store. |
$ttl_fresh |
float |
The fresh TTL in seconds for cached data. This is only provided to fetchCached and queueCached. |
$repopulate |
callable |
A callable that returns data to repopulate cache. |
$options |
array |
Options for the offload (see Offload Options). |
Marking a Result as "Bad"
Sometimes results returned from a repopulate are not in a good state and should not be cached.
The offload manager provides a OffloadRun instance to the repopulate callable that can be used to mark the result as bad, for example:
Offload Options
Offload options are provided as an array, for example:
| Option | |
|---|---|
ttl_fresh |
How long to cache data regarded as fresh in seconds. Fresh data is not repopulated. Defaults to 0. |
ttl_stale |
How long to cache data regarded as stale in seconds. Stale data is repopulated when fetched. This value is added to the ttl_fresh to get a total cache time. Defaults to 5. |
exclusive |
Whether to run the task exclusively (no other tasks for the same key can run concurrently). Defaults to true. |
background |
Whether to run the task in the background. This means it will wait until the offload manager is drained instead of repopulating immediately. Defaults to true. |
background_timeout |
How long to timeout exclusive background tasks in seconds. Defaults to 5. |
background_release_lock |
Whether to release the repopulate lock as soon as the offloaded task is complete. Defaults to true. If set to false, offload will wait until the background timeout completes before allowing new repopulates. |
Offload Result
The OffloadResult class provides the following methods:
OffloadResult |
|
|---|---|
getData() |
The data returned from the repopulate callable. |
isFromCache() |
Whether the data came from cache. |
getExpireTime() |
When the data from cache expires (unix time seconds). |
getStaleTime() |
How long the data has been stale in seconds. If the value is less than zero, that's how far it is from becoming stale. |
isStale() |
Whether the result is from cache, but is stale. |
Encoders
By default, offload will use OffloadEncoderStandard (which does simple PHP serialization) to encode and decode data stored in cache. You can change this by implementing OffloadEncoderInterface and setting the encoder on the OffloadManagerCache instance.
By default offload will use the encoder you set to decode as well. You can change the decoding to use a separate instance by calling setDecoder:
Encryption
Offload ships with an encryption encoder that leverages AES-256 encryption. It wraps any other encoder implementing OffloadEncoderInterface To use it simply set it as the encoder on the offload cache:
Custom Encryption
You can implement custom encryption by simply extending the abstract class OffloadEncoderEncrypted.
License
BSD-3-Clause
