PhoenixKit.Cache (phoenix_kit v1.5.1)

View Source

Generic caching system for PhoenixKit with ETS-backed storage.

This module provides a flexible caching foundation that can be used for:

  • Settings caching
  • User roles and permissions
  • Module configurations
  • Any frequently accessed data

Features

  • ETS-backed storage for high-performance lookups
  • Automatic cache warming
  • TTL support for expiring data
  • Statistics tracking
  • Robust fallback mechanisms
  • Multiple cache instances via registry

Usage

# Start a cache instance
{:ok, pid} = PhoenixKit.Cache.start_link(name: :my_cache, warmer: &MyApp.load_data/0)

# Basic operations
PhoenixKit.Cache.put(:my_cache, "key", "value")
PhoenixKit.Cache.get(:my_cache, "key", "default")
PhoenixKit.Cache.invalidate(:my_cache, "key")

# Batch operations
PhoenixKit.Cache.get_multiple(:my_cache, ["key1", "key2"], %{"key1" => "default1"})
PhoenixKit.Cache.invalidate_multiple(:my_cache, ["key1", "key2"])

Configuration

Cache instances can be configured with:

  • :name - Unique name for the cache instance
  • :warmer - Function to warm the cache on startup
  • :ttl - Time-to-live for cache entries (optional)
  • :max_size - Maximum number of entries (optional)

Summary

Types

cache_key()
cache_name()
cache_value()
default_value()
options()
warmer_fun()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear(cache_name)

Clears all entries from the cache.

get(cache_name, key, default \\ nil)

Gets a value from the cache.

get_multiple(cache_name, keys, defaults \\ %{})

Gets multiple values from the cache.

invalidate(cache_name, key)

Invalidates a key in the cache.

invalidate_multiple(cache_name, keys)

Invalidates multiple keys in the cache.

put(cache_name, key, value)

Puts a value in the cache.

put_multiple(cache_name, key_values)

Puts multiple values in the cache.

start_link(opts)

Starts a new cache instance.

stats(cache_name)

Gets cache statistics.

warm(cache_name)

Warms the cache using the configured warmer function.

Types

cache_key()

@type cache_key() :: any()

cache_name()

@type cache_name() :: atom()

cache_value()

@type cache_value() :: any()

default_value()

@type default_value() :: any()

options()

@type options() :: [
  name: cache_name(),
  warmer: warmer_fun(),
  ttl: pos_integer() | nil,
  max_size: pos_integer() | nil
]

warmer_fun()

@type warmer_fun() :: (-> map() | nil)

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear(cache_name)

@spec clear(cache_name()) :: :ok

Clears all entries from the cache.

Examples

PhoenixKit.Cache.clear(:settings)

get(cache_name, key, default \\ nil)

@spec get(cache_name(), cache_key(), default_value()) :: cache_value()

Gets a value from the cache.

Returns the default value if the key is not found or the cache is unavailable.

Examples

PhoenixKit.Cache.get(:settings, "date_format", "Y-m-d")
PhoenixKit.Cache.get(:user_roles, user_id, [])

get_multiple(cache_name, keys, defaults \\ %{})

@spec get_multiple(cache_name(), [cache_key()], map()) :: map()

Gets multiple values from the cache.

Returns a map with the requested keys and their values, using defaults for missing keys.

Examples

defaults = %{"date_format" => "Y-m-d", "time_format" => "H:i"}
PhoenixKit.Cache.get_multiple(:settings, ["date_format", "time_format"], defaults)

invalidate(cache_name, key)

@spec invalidate(cache_name(), cache_key()) :: :ok

Invalidates a key in the cache.

Examples

PhoenixKit.Cache.invalidate(:settings, "date_format")

invalidate_multiple(cache_name, keys)

@spec invalidate_multiple(cache_name(), [cache_key()]) :: :ok

Invalidates multiple keys in the cache.

Examples

PhoenixKit.Cache.invalidate_multiple(:settings, ["date_format", "time_format"])

put(cache_name, key, value)

@spec put(cache_name(), cache_key(), cache_value()) :: :ok

Puts a value in the cache.

Examples

PhoenixKit.Cache.put(:settings, "date_format", "m/d/Y")
PhoenixKit.Cache.put(:user_roles, user_id, ["admin", "user"])

put_multiple(cache_name, key_values)

@spec put_multiple(cache_name(), map()) :: :ok

Puts multiple values in the cache.

Examples

PhoenixKit.Cache.put_multiple(:settings, %{"date_format" => "m/d/Y", "time_format" => "h:i A"})

start_link(opts)

@spec start_link(options()) :: GenServer.on_start()

Starts a new cache instance.

Options

  • :name - Required. Unique name for the cache instance
  • :warmer - Optional. Function to warm the cache on startup
  • :ttl - Optional. Time-to-live for cache entries in milliseconds
  • :max_size - Optional. Maximum number of entries before eviction

Examples

{:ok, pid} = PhoenixKit.Cache.start_link(name: :settings)
{:ok, pid} = PhoenixKit.Cache.start_link(name: :user_roles, warmer: &MyApp.load_user_roles/0)

stats(cache_name)

@spec stats(cache_name()) :: map()

Gets cache statistics.

Examples

PhoenixKit.Cache.stats(:settings)
# => %{hits: 150, misses: 5, puts: 20, invalidations: 3, hit_rate: 0.97}

warm(cache_name)

@spec warm(cache_name()) :: :ok

Warms the cache using the configured warmer function.

Examples

PhoenixKit.Cache.warm(:settings)