Download the PHP package iprodev/php-easycache without Composer

PHP EasyCache v3 — PSR‑16 Multi‑Backend Cache with SWR

EasyCache is a pragmatic, batteries‑included cache library that implements the PSR‑16 Simple Cache interface and adds production‑grade features on top:

• 🚀 Multi‑tier storage: APCu, Redis, File, and PDO (MySQL/PostgreSQL/SQLite)
• 🔒 Atomic writes and read locks for file storage
• ⚡ Full SWR (stale‑while‑revalidate + stale‑if‑error), with non‑blocking per‑key locks
• 🔧 Pluggable Serializer & Compressor (PHP/JSON + None/Gzip/Zstd)
• 🔄 Automatic backfill between tiers (e.g., a Redis hit is written back to APCu)
• 🎯 First‑class Laravel integration via a Service Provider & Facade
• ✅ Comprehensive test coverage with PHPUnit
• 🛡️ Improved error handling with detailed logging support

Version: v3.0.1 — Requires PHP 8.1+ and psr/simple-cache:^3.

📖 Documentation in other languages:

• فارسی (Persian)
• کوردی (Kurdish Sorani)

📦 Installation

Optional dependencies

• ext-apcu for the APCu tier
• ext-redis or predis/predis:^2.0 for the Redis tier
• ext-zlib for Gzip compression
• ext-zstd for Zstd compression

🚀 Quick Start (PSR‑16)

🎯 Core Features

1. Multi-Tier Caching

Organize your cache in tiers from fastest to slowest. The library automatically:

• Reads from the fastest available tier
• Writes to all tiers
• Backfills faster tiers when data is found in slower tiers

2. Stale-While-Revalidate (SWR)

When data expires but is still inside the SWR window, stale data is served instantly while a refresh happens in the background. This prevents cache stampedes and ensures fast response times.

How it works:

1. If data is fresh, it's returned immediately
2. If data is expired but within SWR window:
   • Stale data is returned instantly
   • Background refresh is triggered (non-blocking)
3. If refresh fails, stale data continues to be served (within staleIfError window)

3. Pluggable Serialization

Choose the serializer that fits your needs:

4. Pluggable Compression

Save memory and disk space:

💾 Storage Backends

APCu Storage

Fast in-memory cache, perfect as the first tier.

Features:

• Lightning-fast memory access
• Shared between PHP-FPM workers
• Automatic expiration
• Safe clear() that only deletes prefixed keys

Redis Storage

Network-based cache with persistence options.

Features:

• Works with phpredis or predis
• TTL support with SETEX
• Safe clear() with prefix scanning
• Automatic expiration

File Storage

Reliable disk-based cache with sharding.

Features:

• Atomic writes (temp file + rename)
• Read locks with flock()
• Directory sharding for performance
• Configurable file extension

Directory Sharding Example:

PDO Storage

SQL database cache for shared environments.

Supported databases:

• SQLite: sqlite:/path/to/cache.db
• MySQL: mysql:host=localhost;dbname=cache
• PostgreSQL: pgsql:host=localhost;dbname=cache

Features:

• TTL support with expiration check
• Prune expired items with prune()
• UPSERT support (INSERT ... ON CONFLICT)
• Indexed queries for performance

🎨 Complete Examples

Example 1: Simple File Cache

Example 2: Multi-Tier with Backfill

Example 3: SWR for API Responses

Example 4: Batch Operations

Example 5: DateInterval TTL

Example 6: Custom Logger Integration

Example 7: Scheduled Cleanup

🎭 Laravel Integration

Setup

1. Install the package:

2. Publish configuration:

3. Configure in config/easycache.php:

Using the Facade

Artisan Commands

The package includes a prune command:

🔑 Key Rules (PSR‑16)

• Allowed characters: [A-Za-z0-9_.]
• Max length: 64 characters
• Reserved characters (not allowed): { } ( ) / \ @ :

🧪 Testing & Quality Assurance

Running Tests

Static Analysis

Test Coverage

The library includes comprehensive tests for:

• ✅ All storage backends (File, APCu, Redis, PDO)
• ✅ Multi-tier caching with backfill
• ✅ SWR functionality
• ✅ Serializers (Native, JSON)
• ✅ Compressors (Null, Gzip, Zstd)
• ✅ Key validation
• ✅ Lock mechanism
• ✅ Edge cases and error handling

🔧 Advanced Configuration

Custom Lock Path

File Storage Sharding Levels

Environment Variables (Laravel)

🚨 Error Handling

All storage operations are wrapped with proper error handling. Failures are logged (if logger is provided) and don't crash your application:

Logged Events:

• Storage read/write failures
• Compression/decompression errors
• Lock acquisition failures
• SWR refresh errors
• Serialization errors

🔄 Backwards Compatibility

For projects upgrading from v2, use the BC wrapper:

📝 Best Practices

1. Use multi-tier wisely: APCu → Redis → File/PDO
2. Set appropriate TTLs: Balance freshness vs. performance
3. Use SWR for expensive operations: Prevent cache stampedes
4. Monitor cache hit rates: Use logging to track performance
5. Schedule pruning: For PDO storage, prune regularly
6. Use compression for large data: GzipCompressor or ZstdCompressor
7. Namespace your keys: Use prefixes to avoid collisions
8. Test error scenarios: Ensure your app handles cache failures gracefully

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Development Setup

📄 License

MIT © iprodev

🔗 Links

• Documentation
• API Reference - English
• API Reference - فارسی
• API Reference - کوردی
• Examples - English
• Examples - فارسی
• Examples - کوردی
• Changelog
• Security Policy
• Code of Conduct

💬 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💡 Discussions: GitHub Discussions