v1.2.1

async-cache-php v1.2.1

This maintenance release focuses on resolving race conditions in asynchronous persistence, improving compatibility with PSR-16 adapters (specifically Symfony Cache), and achieving full PHPStan type safety.

Bug Fixes

• Async Persistence Race Condition: Fixed a critical issue in SourceFetchMiddleware where the middleware would return data before it was actually persisted to the cache. The pipeline now correctly waits for CacheStorage::set() to complete, ensuring data consistency for subsequent requests.
• Symfony Cache Compatibility: Fixed an issue in PsrToAsyncAdapter::getMultiple() where internal "wrapped" objects from Symfony's PSR-16 implementation were being returned instead of their actual values. This ensures tag versioning and multi-get operations work correctly across all adapters.
• Storage Consistency: CacheStorage::set() now returns the created CachedItem instead of a boolean, providing consistent metadata throughout the internal pipeline.
• Tag Invalidation TTL: Added a default 30-day TTL for tag version keys to prevent them from expiring prematurely and causing accidental cache invalidation.

Improvements & Refactorings

• PHPStan Type Safety: Resolved complex generic type issues in SourceFetchMiddleware and CacheStorage. The library now passes PHPStan analysis with 100% confidence, specifically regarding PromiseInterface<T> handling.
• Decompression Handling: Refactored CacheStorage::processDecompression to be asynchronous, ensuring that CPU-intensive decompression doesn't block the initial item retrieval flow and providing better error logging.
• Code Style & Licensing: Applied consistent license headers to all source files and standardized internal method signatures for better readability.

Security & Maintenance

• Security Policy: Added SECURITY.md with official guidelines for reporting vulnerabilities and verifying distribution channels.
• GitHub Templates: Introduced structured templates for Bug Reports and Feature Requests to improve the quality of community feedback.
• Dependabot: Enabled weekly automated dependency updates for Composer packages.

Documentation

• Tasklist Support: Enabled Markdown tasklist extension in MkDocs for better progress tracking in documentation guides.

Testing

• New Coverage: Added unit tests for StrategyMiddleware to verify error logging during background refresh failures.
• Test Stability: Updated CacheStorageTest to align with the new return type signatures.
• Verification: All 159 tests passed successfully.

Installation

You can install or update this library via Composer:

composer require fyennyi/async-cache-php

License

This library remains licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2).

v1.2.0

async-cache-php v1.2.0

This release introduces a major refactoring of the middleware architecture, providing better flow control, centralized strategy management, and a fully functional rate limiting implementation.

Breaking Changes

• Rate Limiting: AsyncCacheConfigBuilder::withRateLimiter() now requires a Symfony\Component\RateLimiter\RateLimiterFactoryInterface. This allows the library to support dynamic rate limit buckets based on keys.
• Method Removal: The obsolete clearRateLimiter() method has been removed from AsyncCacheManager. Use resetRateLimit(string $key) for granular control.
• Middleware Flow: Internal middleware execution order has been changed to ensure that stale data is always available for fallback mechanisms.

Features

• StrategyMiddleware: Introduced a single source of truth for caching strategies. It now orchestrates all decisions regarding Strict (waiting), Background (stale-while-revalidate), and cache hits.
• RateLimitMiddleware: A new dedicated middleware that enforces rate limits using the Symfony Rate Limiter component. It supports the serve_stale_if_limited option to return cached data when limits are reached.
• Enhanced Locking: AsyncLockMiddleware now implements a "Double-Check" mechanism. After acquiring a lock, it checks the cache one more time to see if another process has already populated it, preventing redundant source fetches.
• Granular Reset: Added AsyncCacheManager::resetRateLimit(string $key) to allow resetting specific rate limit buckets without affecting others.

Refactorings & Improvements

• Standardized Logging: All internal logs now follow a consistent format: AsyncCache [PREFIX]: message, making debugging of complex async flows much easier.
• Middleware Responsibility: Refactored CacheLookupMiddleware and AsyncLockMiddleware to remove overlapping logic, adhering strictly to the Single Responsibility Principle.
• Stale-On-Error Placement: Moved StaleOnErrorMiddleware to the correct position in the pipeline (after lookup and lock), ensuring it can effectively serve stale data during source failures.
• PHPStan Compliance: Resolved all static analysis issues related to Promise generic types, ensuring 100% type safety in the pipeline.

Testing

• Unit Tests: Added new test suites for StrategyMiddleware and RateLimitMiddleware.
• Pipeline Compliance: Created a comprehensive integration example (examples/pipeline_compliance.php) that verifies all 8 major pipeline scenarios, from cache misses to concurrent lock acquisition.
• Verification: All 159 unit tests are passing with 100% success rate.

Installation

You can install or update this library via Composer:

composer require fyennyi/async-cache-php

License

This library remains licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2).

v1.1.1

async-cache-php v1.1.1

This release focuses on bug fixes, documentation refinements, and incremental improvements to the demo and developer experience.

Bug Fixes

• ChainCacheAdapter: Improved resilience and resolved PHPStan type inconsistencies.
• Demo API Stats: Fixed hits/misses tracking in the /api/stats endpoint.
• Symfony Lock: Added sysvsem extension requirement to ensure compatibility with Symfony Lock.

Documentation

• API References: Fixed outdated references to AsyncCacheBuilder, aligning all examples with AsyncCacheManager::configure().
• Missing Coverage: Added documentation for CacheOptionsBuilder, additional middleware, and CacheStatus::Bypass.

Improvements

• Demo Site: Simplified the interactive cache testing UI with inline response previews.
• CacheOptionsBuilder: Removed redundant shortcut methods withBackgroundRefresh and withForceRefresh.
• Code Quality: Applied minor code style fixes and small internal cleanups.

Installation

You can install or update this library via Composer:

composer require fyennyi/async-cache-php

License

This library remains licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2).

v1.1.0

async-cache-php v1.1.0

This major release introduces a comprehensive architectural overhaul with a new configuration system, middleware-first pipeline, native integrations, and enhanced storage capabilities.

Breaking Changes

• Configuration System: AsyncCacheManager now requires AsyncCacheConfig via configure()->build() instead of the legacy constructor pattern.
• Framework Bridges: Symfony Bundle, Laravel ServiceProvider, and framework-specific configurations have been removed from the core repository to maintain a cleaner separation of concerns.

Features

• New Configuration Architecture: Introduced AsyncCacheConfig and AsyncCacheConfigBuilder for a fluent, type-safe configuration experience with AsyncCacheManager::configure().
• Middleware Pipeline: Comprehensive middleware-first processing pipeline featuring coalescing, stale-on-error handling, async locks, tag validation, and source fetch orchestration.
• Native Rate Limiting: Integration with Symfony Rate Limiter component, replacing the custom rate limiter implementation for better performance and ecosystem compatibility.
• PSR-20 Clock Support: Full PSR-20 Clock interface support across all core components for improved testability and time handling.
• Enhanced Storage: Introduced tag-based cache invalidation for selective cache purging, built-in compression to reduce storage footprint, X-Fetch metadata tracking for cache diagnostics, and flexible storage strategies designed to work consistently across the React/Promise-based async architecture.

Documentation

• Documentation Overhaul: Complete rewrite of the documentation with updated guides, tutorials, and practical examples reflecting the new architecture.
• Structure & Navigation: Reorganized MkDocs-based documentation site for clearer structure and improved discoverability.

Testing & Quality

• Test Coverage: Significantly expanded unit test coverage across all core components and middleware.
• Static Analysis & Style: Updated PHPStan and PHP-CS-Fixer configurations to enforce stricter type safety and consistent code style.

Installation

You can install or update this library via Composer:

composer require fyennyi/async-cache-php

License

This library remains licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2).

v1.0.2

async-cache-php v1.0.2

This maintenance release improves rate limiter flexibility and significantly expands documentation.

Improvements

• Rate Limiting: Added getRateLimiter() getter to AsyncCacheManager and allowed disabling limits by setting interval to 0.
• Documentation: Launched a comprehensive MkDocs-based documentation portal with guides on stale-while-limited, grace periods, and API reference.
• CI/CD: Streamlined workflows by removing Codacy integration and improving branch coverage for tests.
• Style: Standardized code formatting and spacing across the library.

Installation

You can install or update this library via Composer:

composer require fyennyi/async-cache-php

License

This library remains licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2).

v1.0.1

async-cache-php v1.0.1

This release adds manual cache management methods and improves test suite formatting.

Features

• Cache Management: Added clear() and delete($key) methods to AsyncCacheManager to provide direct control over the cache state.
• Formatting: Standardized return type hint formatting across the test suite for better consistency.

Installation

You can install or update this library via Composer:

composer require fyennyi/async-cache-php

License

This library remains licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2).

v1.0.0

async-cache-php v1.0.0

This is the initial public release of the Async Cache PHP library.

Features

• Asynchronous Caching Manager: A robust abstraction layer that wraps promise-based operations (PromiseInterface) to handle caching transparently without blocking execution flow.
• Smart Rate Limiting: Built-in InMemoryRateLimiter and extensible RateLimiterInterface to throttle requests based on configurable keys and intervals.
• Stale-While-Rate-Limited Strategy: A unique "soft TTL" mechanism where expired (stale) data is returned instead of failing (or waiting) if the rate limit for an external API has been reached.
• Flexible Configuration: The CacheOptions DTO allows configuring TTL, rate limit keys, tags, and force-refresh behavior on a per-request basis.
• PSR-16 Compliance: Designed to work seamlessly with any PSR-16 Simple Cache adapter.

Installation

You can install this library via Composer:

composer require fyennyi/async-cache-php

License

This library is licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2).