Download the PHP package phillarmonic/staccache-bundle without Composer

Staccache Bundle Documentation

A Symfony bundle for efficient Doctrine entity caching with locking support

Overview

The Staccache Bundle provides an easy way to implement entity caching in Symfony applications using Redis. It improves application performance by reducing database queries for frequently accessed entities. Key features include:

• Entity-level caching with automatic cache invalidation
• Collection and query result caching
• Distributed locking to prevent race conditions
• Integration with Symfony's form system for automatic cache updates
• Support for controller argument resolution with cached entities
• Compatible with multiple Redis client libraries (phpredis, predis, SNC Redis Bundle)

Installation

1. Install the bundle with Composer

2. Register the bundle in your application

For Symfony Flex applications, the bundle will be automatically registered. For manual registration, add it to your config/bundles.php:

3. Configure Redis connection

Create a configuration file at config/packages/staccache.yaml:

Basic Usage

Marking Entities as Cacheable

Add the #[Staccacheable] attribute to entity classes you want to cache:

Configuration Options

The #[Staccacheable] attribute accepts the following parameters:

• ttl: Time-to-live in seconds for the entity cache (-1 uses the default from configuration)
• lockOnWrite: Whether to acquire a lock when updating or deleting the entity (defaults to true)

Advanced Usage

Using Repository Methods

The bundle provides a CachedServiceEntityRepository base class that adds caching capabilities to your repositories:

Controller Argument Resolution

The bundle automatically resolves entity arguments in controllers, using the cache when possible:

Cache Bypass Methods

When using the CachedServiceEntityRepository, you can bypass the cache for specific operations:

Manual Cache Management

You can directly use the EntityCacheManager and QueryCacheManager services:

Cache Purging

The bundle provides a command to purge the cache:

Configuration Reference

Here's the complete configuration reference:

Integrations

SNC Redis Bundle Integration

If you're using the SNC Redis Bundle, you can configure Staccache to use an existing Redis client:

Form Integration

The bundle automatically updates cached entities on form submission:

Performance Considerations

When to Use Caching

Entity caching is most effective for:

• Entities that are frequently read but rarely updated
• Entities that are expensive to load (complex relationships, calculations)
• High-traffic pages that repeatedly access the same entities

When to Avoid Caching

• Entities that change frequently
• Entities with very large serialized size
• Entities with sensitive data that shouldn't be stored in Redis

Memory Usage

Monitor your Redis memory usage, especially when caching large collections or entities with many relationships.

Troubleshooting

Cache Not Being Used

1. Verify that your entity has the #[Staccacheable] attribute
2. Check Redis connection and configuration
3. Use the command bin/console staccache:purge --all --dry-run to see if any cache entries exist

Entity Changes Not Reflected

1. Entity might be cached for longer than expected (check TTL configuration)

2. Cache invalidation might be failing (check logs for errors)

3. Try manually invalidating the cache:

Redis Connection Issues

1. Verify Redis connection parameters
2. Check if Redis server is running and accessible
3. Ensure proper authentication if Redis requires password

Best Practices

1. Set appropriate TTL values based on how frequently entities change
2. Use fine-grained cache keys for queries
3. Implement cache warmup for critical entities
4. Monitor Redis memory usage
5. Consider cache versioning for major data structure changes

Additional Resources

Logging

The bundle uses a dedicated logging channel staccache. Configure it in your Monolog configuration:

Then, configure the logger in your Staccache configuration:

Performance Monitoring

To monitor cache hit rates and performance, consider implementing metrics collection: