Query Caching

Cache query results to reduce API calls and improve response times. Caching is applied at the Builder level, similar to Laravel's DB::table()->remember().

INFO

Caching is skipped for async queries (async()->cache() will not cache).

Basic Usage

use Rollogi\LaravelHubspot\Crm\Contact;

// Cache for 60 seconds
$contacts = Contact::query()
    ->where('email', 'like', 'example.com')
    ->cache(60)
    ->get();

// String TTL (parsed via CarbonInterval)
$contacts = Contact::query()->cache('2 hours')->get();

// Explicit cache key for easy invalidation
$contacts = Contact::query()->cache(60, key: 'active-contacts')->get();

// Use a specific cache store
$contacts = Contact::query()->cache(60, store: 'redis')->get();

Caching works with all read methods -- get(), first(), count(), paginate(), cursor(), find(), and findMany().

Model-Level Defaults

Set a $cacheTtl on your model to cache all queries using cache() by default:

use Rollogi\LaravelHubspot\Api\Model;

class Contact extends Model
{
    protected string $type = 'contacts';

    // All cache() calls will use this TTL unless overridden
    protected int|string|null $cacheTtl = '5 minutes';
}

// Uses the model's default TTL
$contacts = Contact::query()->cache()->get();

// Override with explicit TTL
$contacts = Contact::query()->cache(30)->get();

Refresh and Invalidation

use Rollogi\LaravelHubspot\Crm\Contact;

// Bypass cache and re-store fresh result
$contacts = Contact::query()->cache(60)->refresh()->get();

// Disable caching (overrides model default)
$contacts = Contact::query()->noCache()->get();

// Invalidate a specific cache key
Contact::query()->cache(key: 'active-contacts')->invalidate();

Auto-Invalidation

Write operations (create(), update(), delete(), createMany(), updateMany(), upsertMany(), deleteMany()) automatically invalidate cached queries for the same object type when the cache driver supports tags (Redis, Memcached, array). This is enabled by default and can be disabled via config.

Configuration

# Enable query caching globally (queries still need ->cache() call)
HUBSPOT_CACHE_ENABLED=false

# Cache store (null = default store)
HUBSPOT_CACHE_STORE=

# Key prefix for all cache entries
HUBSPOT_CACHE_PREFIX=hubspot

# Default TTL in seconds
HUBSPOT_CACHE_TTL=3600

# Auto-invalidate on writes (requires tagged cache driver)
HUBSPOT_CACHE_AUTO_INVALIDATE=true

When HUBSPOT_CACHE_ENABLED is false (default), queries are only cached when cache() is called with an explicit TTL or the model has a $cacheTtl property.