{eac}ObjectCache – a persistent object cache using SQLite & APCu to cache WordPress objects.

The {eac}ObjectCache is a light-weight and very efficient drop-in persistent object cache that uses a fast SQLite database and even faster APCu shared memory to cache WordPress objects.

See The WordPress Object Cache

The WordPress Object Cache is used to save on trips to the database. The Object Cache stores all of the cache data to memory and makes the cache contents available by using a key, which is used to name and later retrieve the cache contents.

By default, the object cache is non-persistent. This means that data stored in the cache resides in memory only and only for the duration of the request. Cached data will not be stored persistently across page loads unless you install a persistent caching plugin.

Here, an object is any piece of data – a number, text, a set of database records, an API response, etc. – that can be referenced by a name or key. Objects are categorized by a group name. Groups help identify what an object is and how it is used.

{eac}ObjectCache replaces the default WordPress object cache to not only store data in process memory but to also store data persistently, across requests, in APCu shared memory and/or in a SQLite database, increasing the likelihood of cache hits and decreasing the need for costly computations, complex MySQL database queries, and remote API requests.

SQLite is a fast, small, single-file relational database engine. By using SQLite to store objects, {eac}ObjectCache is able to manage a relatively large amount of data (groups, keys, and values) in a very efficient and fast data-store.

APCu is a shared, in-memory, persistent cache available only when the APCu PECL Extension is installed. {eac}ObjectCache uses APCu as an intermediate cache between the L1 memory cache and the L2 SQLite database cache providing extremely fast object retrieval,

{eac}ObjectCache always uses per-request, in-memory caching and may operate with either APCu memory caching or SQLite database caching – or both. APCu memory caching uses a single block of memory shared by all PHP requests and is persistent until and unless the cache is cleared or the server is rebooted (or PHP restarted). SQLite database caching is persistent until and unless the cache is deliberately cleared.

Features

• Lightweight, efficient, and fast!
• L1 (in-process memory) and L2 (APCu & SQLite) caching.
• Supports Write-Back (delayed transactions) or Write-Through SQL caching.
• Caching by object group name.
  • Preserves uniqueness of keys.
  • Manage keys by group name.
  • Supports group name attributes (:sitewide, :nocaching, :permanent, :prefetch)
• Pre-fetch object groups from L2 to L1 cache.
• Caches and pre-fetches L2 misses (known to not exist in L2 cache).
  • Prevents repeated, unnecessary L2 cache reads across requests.
• Multisite / Network support:
  • Cache/flush/switch by blog id.
• Caching statistics:
  • Cache hits (typically above 90%).
  • Overall and L1/L2 hits, misses, & ratio.
  • Cache hits by object groups.
  • Number of APCu and SQLite keys stored.
  • SQLite select/update/delete/commit counts.
• Supports an enhanced superset of WP Object Cache functions.
• Easily enabled or disabled from {eac}Doojigger administrator page.
  • Imports existing MySQL transients.
  • Exports cached transients to MySQL when disabled.
• Automatically cleans and optimizes SQLite database.
• Optionally schedule periodic cache invalidation and rebuild.
• Uses the PHP Data Objects (PDO) extension included with PHP.

While {eac}ObjectCache does support multiple WordPress installations on a single server it does not support multiple servers per installation. SQLite and APCu work only on a single server, not in a clustered or load-balanced environment.

Configuration Alternatives

Assuming you have SQLite and APCu installed, what are your best options?

1. Fastest Caching – Uses in-process memory and APCu shared memory.

   • Disable SQLite. *
     • define( 'EAC_OBJECT_CACHE_USE_DB', false );
   • Advantage
     • Fast memory-only access.
     • Handles concurrent updates through APCu cache.
   • Disadvantage
     • APCu may invalidate data under memory constraint.
     • APCu cache is not shared with CLI.
     • APCu cache is lost on system or PHP restart.

2. Less memory (almost as fast) – Uses in-process memory and APCu shared memory.

   • Disable SQLite. *
     • define( 'EAC_OBJECT_CACHE_USE_DB', false );
   • Optimize memory use. *
     • define( 'EAC_OBJECT_CACHE_OPTIMIZE_MEMORY', true );
   • Advantage
     • Fast memory-only access.
     • Handles concurrent updates through APCu cache.
     • Conserves per-request memory by not pushing APCu hits to in-process memory.
   • Disadvantage
     • Slightly slower to access APCu memory over in-process memory.
     • APCu may invalidate data under memory constraint.
     • APCu cache is not shared with CLI.
     • APCu cache is lost on system or PHP restart.

3. Most resilient (and still fast) – Uses in-process memory, APCu shared memory, and SQLite database.

   • Do nothing, this is the default.
   • Advantage
     • Most cache hits will come from in-process and APCu memory.
     • SQLite retains cache data after restart.
   • Disadvantage
     • Must keep SQLite database (on disk) updated.
     • Potential concurrency issues on high-volume site.

4. Resilient, efficient, and fast (recommended) – Uses in-process memory, APCu shared memory, and SQLite database.

   • Optimize memory use. *
     • define( 'EAC_OBJECT_CACHE_OPTIMIZE_MEMORY', true );
   • Advantage
     • Most cache hits will come from in-process and APCu memory.
     • Handles concurrent updates better through APCu cache.
     • Conserves per-request memory by not pushing APCu hits to in-process memory.
     • SQLite retains cache data after restart.
   • Disadvantage
     • Slightly slower to access APCu memory over in-process memory.
     • Must keep SQLite database (on disk) updated.

5. Least efficient (default when APCu is not installed) – Uses in-process memory and SQLite database.

   • Disable APCu. *
     • define( 'EAC_OBJECT_CACHE_USE_APCU', false );
   • Advantage
     • Saves resources by not taking up APCu reserves.
     • More secure by not using shared memory.
     • SQLite retains cache data after restart.
   • Disadvantage
     • All cached data initially read from disk.
     • Must keep SQLite database (on disk) updated.
     • Potential concurrency issues on high-volume site.

6. For high-volume sites – reduces or eliminates potential race conditions

   • Optimize memory use. *
     • define( 'EAC_OBJECT_CACHE_OPTIMIZE_MEMORY', true );
   • Disable delayed writes. *
     • define( 'EAC_OBJECT_CACHE_DELAYED_WRITES', false );
   • Disable use of alloptions array.
     • define( 'EAC_OBJECT_CACHE_DISABLE_ALLOPTIONS', true );
   • Advantage
     • Most cache hits will come from in-process and APCu memory.
     • Conserves per-request memory by not pushing APCu hits to in-process memory.
     • Updates SQLite data immediately.
     • Conserves per-request memory by elimination large alloptions array(s).
   • Disadvantage
     • Slightly slower to access APCu memory over in-process memory.
     • Multiple single-row SQLite update transactions.
     • Slightly slower to access individual options from cache rather than alloptions array.

* These options may be set from the {eac}Doojigger administration screen.

When using SQLite, delayed writes (see below) dramatically improves efficiency by only writing updates at the end of the script process.

When using APCu shared memory, data is accessable by other PHP processes that may run on the server.

Inside The Numbers

Label        
Value

cache hits
The total number of requests that returned a cached value.

cache misses
The total number of requests that did not return a cached value. This number includes L1 cache (-), L2 non-persistent, L2 APCu (-), and L2 SQL misses.

L1 cache hits
The number of requests that were found in the L1 memory cache.

L1 cache (+)
Request found in the L1 memory cache with data (positive hits).

L1 cache (-)
Request found in the L1 memory cache with no data (negative hits).

L1 cache misses
The number of requests not found in the L1 memory cache.

L2 non-persistent
L1 cache misses in a non-persistent group (not in L2 cache).

L2 APCu hits
The number of L1 cache misses (minus L2 non-persistent) that were found in the L2 APCu cache.

L2 APCu (+)
Request found in the L2 APCu cache with data (positive hits).

L2 APCu (-)
Request found in the L2 APCu cache with no data (negative hits).

L2 APCu misses
The number of requests not found in the L2 APCu cache.

L2 SQL hits
The number of L2 APCu misses (or L1 cache misses) that were found in the L2 SQLite cache.

L2 SQL misses
The number of requests not found in the L2 SQLite cache.

L2 APCu updates
The number of APCu keys updated.

L2 APCu deletes
The number of APCu keys deleted.

L2 SQL selects
The number of SQLite select statements executed.

L2 SQL updates
The number of SQLite records updated.

L2 SQL deletes
The number of SQLite records deleted.

L2 SQL commits
The number of SQLite transactions executed to update and delete records.

• When a request results in a L2 SQL miss, the key is added to the L1 memory or L2 APCu cache as a miss so that additional requests for the same key do not result in additional SQL selects. This is known as a negative hit and still counted as a cache miss making the cache hit ratio (93.10%) understated.

Object cache statistics may be found:

• In the WP Object Cache dashboard panel.
  • Uses $wp_object_cache->showDashboardStats()
• In the Debug Bar > Object Cache panel.
  • Uses $wp_object_cache->stats()
• In the Query Monitor > Logs > Info panel.
  • Uses $wp_object_cache->getCurrentStats()
• In a wp_admin_notice block when display_stats is set for sampling.
  • Uses $wp_object_cache->htmlStats()

Settings

Several cache settings can be modified by adding defined constants to the wp-config.php file. The default settings are recommended and optimal in most cases but individual settings may need to be adjusted based on traffic volume, specific requirements, or unique circumstances. Most of these settings can be adjusted in the {eac}Doojigger administrator screen.

• To disable use of the SQLite Database (default: true):

  define( 'EAC_OBJECT_CACHE_USE_DB', false );

{eac}ObjectCache will still operate as an in-memory cache without the persistent database. If using APCu memory caching, persistence is maintained as long as the cache is not flushed, manually or by restarting PHP.

• To disable use of the APCu memory cache (default: true if APCu is enabled):

  define( 'EAC_OBJECT_CACHE_USE_APCU', false );

APCu memory caching is used, by default, only if the APCu PECL extension is installed.

• To optimize memory use when using APCu (default: false):

  define( 'EAC_OBJECT_CACHE_OPTIMIZE_MEMORY', true );

When using APCu memory caching, optimize internal memory by not storing APCu data in the L1 memory cache. This may slightly (negligibly) increase processing time as cache hits will come through APCu but will reduce the per-process memory usage. This may also be advantageous on high-volume sites where a single object may be updated by simultaneous processes.

• To disable use of the alloptions array in WordPress (default: false):

  define( 'EAC_OBJECT_CACHE_DISABLE_ALLOPTIONS', true );

By default, WordPress pre-fetches many of the option values from the wp-options table on startup. This facilitates faster access to oft-used options. However, this also creates 1) a potential race condition on high-volume sites, and 2) a sometimes very large array of data in memory that may also be duplicated in the L1 and L2 caches. Disabling this forces WordPress to get individual options from the cache rather than from the array, eliminates the race condition, eliminates the large array(s), and reduces much of the logic used to maintain the array(s). This may be particularly advantageous when using APCu since the option values should already be in shared memory.

* Once enabled, the caches should be cleared to eliminate previously cached alloptions arrays.
* Uses filters pre_wp_load_alloptions (introduced in WP 6.2.0) and wp_autoload_values_to_autoload (introduced in WP 6.6.0).

• To set the location of the SQLite database (default: ../wp-content/cache):

  define( 'EAC_OBJECT_CACHE_DIR', '/full/path/to/folder' );

This folder can be outside of the web-accessable folders of your site – i.e. above the document root (htdocs, www, etc.) – provided that PHP can access (read/write) the folder (see the PHP open_basedir directive).

This folder should not be on a network share or other remote media. We’re caching data for quick access, the cache folder should be on fast, local media.

• To set the name of the SQLite database (default: ‘.eac_object_cache.sqlite’):

  define( 'EAC_OBJECT_CACHE_FILE', 'filename.sqlite' );

In addition to the database file, SQLite may also create temporary files using the same file name with a ‘-shm’ and ‘-wal’ suffix.

• To set SQLite journal mode (default: ‘WAL’):

  define( 'EAC_OBJECT_CACHE_JOURNAL_MODE', journal_mode )

journal_mode can be one of ‘DELETE’, ‘TRUNCATE’, ‘PERSIST’, ‘MEMORY’, ‘WAL’, or ‘OFF’.
See SQLite journal mode

• To set SQLite Mapped Memory I/O (default: 0):

  define( 'EAC_OBJECT_CACHE_MMAP_SIZE', int );

Sets the maximum number of bytes that are set aside for memory-mapped I/O.
See SQLite memory-mapped I/O

• To set SQLite Page Size (default: 4096):

  define( 'EAC_OBJECT_CACHE_PAGE_SIZE', int );

Sets the SQLite page size for the database.
See SQLite page size

• To set SQLite Cache Size (default: -2000 [2,048,000]):

  define( 'EAC_OBJECT_CACHE_CACHE_SIZE', int );

Sets the maximum number of database disk pages that SQLite will hold in memory or the maximum amount of memory to use for page caching.
See SQLite cache size

• To set SQLite timeout (default: 3):

  define( 'EAC_OBJECT_CACHE_TIMEOUT', int );

Sets the number of seconds before a SQLite transaction may timeout in error.

• To set SQLite retries (default: 3):

  define( 'EAC_OBJECT_CACHE_MAX_RETRIES', int );

Sets the maximum number of retries to attempt on critical actions.

• To set delayed writes (default: 32):

  define( 'EAC_OBJECT_CACHE_DELAYED_WRITES', true|false|int );

{eac}ObjectCache caches all objects in memory and writes new, updated, or deleted objects to the L2 (SQLite) cache. delayed writes simply holds objects in memory until the number of objects reaches a specified threshold, then writes them, in a single transaction, to the L2 cache (a.k.a. write-back caching). Setting delayed writes to false turns this functionality off (a.k.a. write-through caching). Setting to true writes all records only at the end of the script process/page request. Setting this to a number sets the object pending threshold to that number of objects.

• To set the default expiration time (in seconds) (default: 0 [never]):

  define( 'EAC_OBJECT_CACHE_DEFAULT_EXPIRE', -1|0|int );

When using the default WordPress object cache, object expiration isn’t very important because the entire cache expires at the end of the script process/page request. With a persistent cache, this isn’t the case. When an object is cached, the developer has the option of specifying an expiration time for that object. Since we don’t know …