CacheStore — Context-Aware Cache for Laravel

CacheStore is a powerful, context-aware cache abstraction layer for Laravel applications. It goes beyond simple key-value storage by introducing multi-tenant, multi-school, and custom context scoping — making it ideal for SaaS platforms, school management systems, and any application that needs isolated cache namespaces.

Features

• 🏢 Context-Aware Caching — Automatically scope cache keys by tenant, school, or custom context
• 🚀 Multiple Drivers — Array, File, Database, Redis, and Laravel Cache drivers included
• 🔌 Pluggable Architecture — Implement your own drivers via the CacheDriver contract
• 🔄 Serialization — Automatic PHP serialization for complex types (arrays, objects)
• ⚡ Atomic Operations — Increment/decrement bypass serialization for raw numeric operations
• 🧪 Test-Ready — Array driver for testing, trait-based test helpers
• 📦 Auto-Discovery — Laravel package auto-discovery for service provider and facade

Quick Start

Table of Contents

• Installation
• Configuration
• Usage
• Drivers
• Context-Aware Caching
• Testing
• Driver Contract
• Requirements
• Changelog
• Contributing
• Security
• License

Installation

You can install the package via Composer:

Service Provider Discovery

Laravel will auto-discover the CacheStoreServiceProvider. If you have disabled package discovery, register it manually in config/app.php:

Facade

The CacheStore facade is also auto-discovered. If needed, register it manually:

Publishing Configuration

Configuration

The package configuration file config/cache-store.php is automatically merged with your application's config.

Configuration Options

Usage

Basic Cache Operations

Complex Data Types

Remember Pattern

Drivers

CacheStore ships with five built-in drivers, each optimized for different use cases:

Using a Specific Driver

Writing a Custom Driver

Implement the CacheDriver contract to create your own driver:

Context-Aware Caching

The standout feature of CacheStore is context-aware caching — automatically scoping cache keys by tenant, school, or any custom context.

How It Works

When you use a context, CacheStore prefixes your cache keys with context identifiers:

This ensures that the same key name in different contexts never collides.

Usage

Configuring Context

You can enable/disable context segments in the config:

When disabled, the corresponding context segment is omitted from the cache key.

Key Building Logic

The cache key is built using the following pattern:

Where:

• {prefix} — Global prefix from config (schoolpalm)
• {tenant} — Tenant identifier (if context.tenant is enabled)
• {school} — School identifier (if context.school is enabled)
• {key} — Your cache key
• Segments are joined using the configured key_separator

Testing

CacheStore makes testing a breeze with its Array driver and shared test traits.

Running Tests

Test Traits

Use the CacheDriverBehaviour trait to run a comprehensive test suite against any driver:

This automatically tests:

• Store & retrieve values
• Store & retrieve integer values
• Return default value for missing keys
• Key existence checks
• Overwrite existing values
• Forget operations
• Array storage
• Object storage
• Boolean storage
• Forever storage
• Add (unique key) operations
• Pull operations
• Pull returns default for missing keys
• Increment / Decrement
• Many operations
• Many returns null for missing keys
• Flush operations

Creating a Custom Driver Test

Note: Include tests/Support/cacheDriverTests.php in your test file to execute the shared test suite.

Driver Contract

All cache drivers must implement the SchoolPalm\CacheStore\Contracts\CacheDriver interface:

Serialization Behavior

Drivers handle serialization automatically via CacheSerializer:

Note: increment() and decrement() bypass serialization for raw numeric operations at the storage layer.

Requirements

• PHP: ^8.2
• Laravel: ^12.0 (Illuminate\Support and Illuminate\Cache)
• Database Driver: Requires a database connection when using the database cache driver
• Redis Driver: Requires predis/predis or phpredis extension when using the redis cache driver

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Development Setup

1. Clone the repository
2. Run composer install
3. Run composer build to set up the testbench workbench
4. Run composer test to execute tests

Code Style

This package follows the PSR-12 coding standard.

Security

Please see SECURITY for our security policy.

Credits

• SchoolPalm
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

_{Built with ❤️ by SchoolPalm for the Laravel community}