diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..449cae8 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,15 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 4 +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false + +[*.{yml,yaml,json,xml}] +indent_size = 2 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..d4ea1c3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,32 @@ +--- +name: Bug report +about: Create a report to help us improve SmartCache +title: '[BUG] ' +labels: bug +assignees: '' +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Cache Driver used: (e.g. Redis, File, Memcached) +2. Value being cached: (e.g. array, collection, model, string) +3. Code snippet: +```php +// Your caching code here +``` +4. The error or unexpected behavior encountered. + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Environment details:** +- PHP Version: [e.g. 8.1] +- Laravel Version: [e.g. 10.x] +- SmartCache Version: [e.g. 1.0.0] +- Cache Driver used: [e.g. Redis] + +**Additional context** +Add any other context about the problem here (e.g. is `ext-zlib` installed? Are you using adaptive compression?). diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..2f44ce3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,19 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '[FEATURE] ' +labels: enhancement +assignees: '' +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/workflows/code-analysis.yml b/.github/workflows/code-analysis.yml index 957c6d1..338c21a 100644 --- a/.github/workflows/code-analysis.yml +++ b/.github/workflows/code-analysis.yml @@ -19,7 +19,7 @@ jobs: uses: shivammathur/setup-php@v2 with: php-version: 8.3 - extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo + extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo, zlib coverage: xdebug - name: Install dependencies diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a1d807e..0c3d0df 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -54,7 +54,7 @@ jobs: uses: shivammathur/setup-php@v2 with: php-version: ${{ matrix.php }} - extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo + extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo, zlib coverage: none - name: Setup problem matchers diff --git a/.gitignore b/.gitignore index c3a5c60..dc0547e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ vendor/ +composer.lock .phpunit.cache/ coverage/ .DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..91f2e74 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,160 @@ +# Changelog + +All notable changes to the `iazaran/smart-cache` package will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.9.3] - 2026-04-14 +### Added +- Added `SECURITY.md` for standardized enterprise vulnerability disclosures. +- Added `CHANGELOG.md` following the Keep a Changelog standard. +- Added `.editorconfig` to enforce formatting consistency across contributors. +- Issue and Pull Request GitHub templates added to standardize bug tracking. +### Changed +- Enriched `config/smart-cache.php` inline documentation for advanced strategies like `adaptive mode` and `circuit_breaker`. +- Appended `ext-zlib` and `ext-json` extension suggestions to `composer.json`. +- Enhanced `CONTRIBUTING.md` with test commands, PSR-12 standards, and security disclosure references. +- Added `zlib` extension to CI workflows for explicit compression test coverage. +- Updated documentation and `README.md` with deep-dive troubleshooting and "Best Practices" examples. +- Added `composer.lock` to `.gitignore` (library best practice). +### Fixed +- Fixed dashboard route documentation (`/stats` → `/statistics`) in README and `docs/index.html`. + +## [1.9.2] - 2026-03-17 +### Added +- Feature: Added official support for Laravel 13 framework requirements. +- Implemented `touch()` method functionality and boot-safe event registration to comply with Laravel 13 architectures. +### Fixed +- Fixed tests for Symfony Console compatibility allowing both `add()` and `addCommand()`. + +## [1.9.1] - 2026-03-04 +### Changed +- Improved current features functionality. +- Enhanced and updated the `README.md` and documentation files for a better Developer Experience (DX). + +## [1.9.0] - 2026-02-20 +### Added +- Added Write Deduplication (Cache DNA) optimization to save unnecessary I/O writes. +- Self-Healing Cache feature and Conditional Caching functionality implemented. +- Significant SEO improvements in `composer.json` and meta-tags. +### Fixed +- Addressed assorted bug fixes reported by the community. + +## [1.8.0] - 2026-02-08 +### Added +- Introduced Cost-Aware caching to prioritize memory eviction efficiently. +- Various under-the-hood fixes and optimization refinements. + +## [1.7.0] - 2026-01-19 +### Added +- Feature Request #31: Implemented `store()` method support directly on the SmartCache facade. + +## [1.6.0] - 2025-12-06 +### Added +- General core improvements and new minor features for package robustness. + +## [1.5.0] - 2025-10-19 +### Added +- New core features and expanded cache optimization solutions for large objects. + +## [1.4.3] - 2025-09-27 +### Changed +- Extended documentation coverage in `docs/index.html` and `README.md`. + +## [1.4.2] - 2025-09-26 +### Changed +- Improved the internal mechanism for managing keys for mass invalidation dynamically. + +## [1.4.1] - 2025-09-26 +### Changed +- Optimization applied to the `flexible` macro implementation. + +## [1.4.0] - 2025-09-26 +### Added +- Comprehensive dependency tracking mechanism. +- Full Cache Tag support implementations. +- Powerful cache invalidation strategies and helpers. + +## [1.3.7] - 2025-09-25 +### Added +- Robust test coverage established ensuring compatibility with PHP 8.1+ and Laravel 8+. + +## [1.3.6] - 2025-09-08 +### Fixed +- Bugfix: Resolves Issue #18 where cache `flexible` logic was not operating as expected under certain payloads. + +## [1.3.5] - 2025-09-02 +### Fixed +- Resolved PHP parameter type warnings related to strict nullable types. + +## [1.3.4] - 2025-09-02 +### Fixed +- Bugfix: Issue #14 regarding keys stored but not registering properly on status checks. + +## [1.3.3] - 2025-09-01 +### Fixed +- Bugfix: Addressed Issue #12 covering data cleared by a specifically defined key. + +## [1.3.2] - 2025-08-31 +### Fixed +- Continued stabilization for manual key data clearance mechanics (Issue #12). + +## [1.3.1] - 2025-08-31 +### Fixed +- Bugfix: Resolved Issue #8 concerning multiple conflicting strategies applying to single cache allocations. + +## [1.3.0] - 2025-08-31 +### Added +- Feature Request #7: Implemented dedicated support for cache `flexible` macros. + +## [1.2.2] - 2025-08-30 +### Added +- Deployed structured unit testing cases asserting early system stability. + +## [1.2.1] - 2025-06-03 +### Added +- Added Google site verification file for better SEO visibility compliance. + +## [1.2.0] - 2025-06-03 +### Changed +- Various repository refinements tailored towards improving SEO and discoverability. + +## [1.1.0] - 2025-04-22 +### Added +- Introduced the `smart_cache` global helper function to provide a drop-in analogue for Laravel's `cache` helper. + +## [1.0.1] - 2025-04-21 +### Changed +- Package-wide code refactoring, structural cleanup, and PSR standard reformatting. + +## [1.0.0] - 2025-04-21 +### Added +- Initial package scaffolding and base logic commit. + +[1.9.3]: https://github.com/iazaran/smart-cache/compare/1.9.2...1.9.3 +[1.9.2]: https://github.com/iazaran/smart-cache/compare/1.9.1...1.9.2 +[1.9.1]: https://github.com/iazaran/smart-cache/compare/1.9.0...1.9.1 +[1.9.0]: https://github.com/iazaran/smart-cache/compare/1.8.0...1.9.0 +[1.8.0]: https://github.com/iazaran/smart-cache/compare/1.7.0...1.8.0 +[1.7.0]: https://github.com/iazaran/smart-cache/compare/1.6.0...1.7.0 +[1.6.0]: https://github.com/iazaran/smart-cache/compare/1.5.0...1.6.0 +[1.5.0]: https://github.com/iazaran/smart-cache/compare/1.4.3...1.5.0 +[1.4.3]: https://github.com/iazaran/smart-cache/compare/1.4.2...1.4.3 +[1.4.2]: https://github.com/iazaran/smart-cache/compare/1.4.1...1.4.2 +[1.4.1]: https://github.com/iazaran/smart-cache/compare/1.4.0...1.4.1 +[1.4.0]: https://github.com/iazaran/smart-cache/compare/1.3.7...1.4.0 +[1.3.7]: https://github.com/iazaran/smart-cache/compare/1.3.6...1.3.7 +[1.3.6]: https://github.com/iazaran/smart-cache/compare/1.3.5...1.3.6 +[1.3.5]: https://github.com/iazaran/smart-cache/compare/1.3.4...1.3.5 +[1.3.4]: https://github.com/iazaran/smart-cache/compare/1.3.3...1.3.4 +[1.3.3]: https://github.com/iazaran/smart-cache/compare/1.3.2...1.3.3 +[1.3.2]: https://github.com/iazaran/smart-cache/compare/1.3.1...1.3.2 +[1.3.1]: https://github.com/iazaran/smart-cache/compare/1.3.0...1.3.1 +[1.3.0]: https://github.com/iazaran/smart-cache/compare/1.2.2...1.3.0 +[1.2.2]: https://github.com/iazaran/smart-cache/compare/1.2.1...1.2.2 +[1.2.1]: https://github.com/iazaran/smart-cache/compare/1.2.0...1.2.1 +[1.2.0]: https://github.com/iazaran/smart-cache/compare/1.1.0...1.2.0 +[1.1.0]: https://github.com/iazaran/smart-cache/compare/1.0.1...1.1.0 +[1.0.1]: https://github.com/iazaran/smart-cache/compare/1.0.0...1.0.1 +[1.0.0]: https://github.com/iazaran/smart-cache/releases/tag/1.0.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c9a16d..407cb44 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,5 @@ # Contributing + I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's: - Reporting a bug @@ -7,17 +8,48 @@ I love your input! I want to make contributing to this project as easy and trans - Proposing new features - Becoming a maintainer +## Security Vulnerabilities + +If you discover a security vulnerability, please review our [Security Policy](SECURITY.md) for responsible disclosure instructions. **Do not** open a public GitHub issue for security concerns. + ## All Code Changes Happen Through Pull Requests + Pull requests are the best way to propose changes to the codebase. I actively welcome your pull requests: 1. Fork the repo and create your branch from `main`. 2. If you've added code that should be tested, add tests. 3. If you've changed APIs or functions, update the documentation. -4. Make sure your code lints. -5. Issue that pull request! +4. Ensure your code follows the **PSR-12** coding standard. +5. Make sure your code lints and all tests pass. +6. Document notable changes in your PR description for the [CHANGELOG](CHANGELOG.md). +7. Issue that pull request! + +## Running Tests + +```bash +# Run the full test suite +composer test + +# Run with code coverage +composer test-coverage +``` + +All pull requests must pass the existing test suite (425+ tests) before merging. If you add a new feature, include corresponding test cases. + +## Coding Style + +This project follows the **PSR-12** coding standard. Key points: + +- Use 4 spaces for indentation (enforced by `.editorconfig`) +- Opening braces on the same line for control structures +- Opening braces on the next line for classes and methods +- One `use` declaration per line +- Type declarations and return types where applicable ## Any contributions you make will be under the MIT Software License + In short, when you submit code changes, your submissions are understood to be under the same. ## License + By contributing, you agree that your contributions will be licensed under its MIT License. \ No newline at end of file diff --git a/README.md b/README.md index 6fb3a54..fea6dbf 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,13 @@ Implements `Illuminate\Contracts\Cache\Repository` and PSR-16 `SimpleCache`. You ## Installation +**Prerequisites:** PHP extensions `ext-zlib` (for data compression) and `ext-json` (for optimal object serialization) are strongly recommended to enable all performance optimization strategies. + ```bash composer require iazaran/smart-cache ``` -That's it. No configuration required — works immediately with your existing cache driver. +That's it. No further configuration is required — works immediately with your existing cache driver. ## Quick Start @@ -264,7 +266,7 @@ SmartCache::analyzePerformance(); // health score + recommendations ```php // Enable web dashboard 'dashboard' => ['enabled' => true, 'prefix' => 'smart-cache', 'middleware' => ['web', 'auth']], -// GET /smart-cache/dashboard | /smart-cache/stats | /smart-cache/health +// GET /smart-cache/dashboard | /smart-cache/statistics | /smart-cache/health ``` ```bash @@ -274,6 +276,13 @@ php artisan smart-cache:warm --warmer=products --warmer=categories php artisan smart-cache:cleanup-chunks ``` +## Best Practices & Troubleshooting + +- **Binary Data:** If caching already compressed objects like images, video, or encrypted data, disable `compression` for those specific cache keys as they waste CPU cycles without yielding size reductions. +- **Memory Limits with Chunking:** Large multi-megabyte datasets automatically trigger the 'chunking' strategy. For arrays over 100,000 items, verify `memory_limit` in `php.ini` or enable `lazy_loading` via config to avoid server crashes. +- **Provider Not Found:** Laravel aggressively caches service providers and aliases. Always run `php artisan optimize:clear` after upgrading or installing this package if encountering *"Class 'SmartCache' not found"*. +- **IDE Autocomplete:** Modern IDEs (PhpStorm, VSCode) completely resolve `SmartCache::` magical methods automatically via our included Facade PHPDocs without needing `ide-helper` generated files. + ## Configuration Publish the config file (optional — sensible defaults are applied automatically): diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f28b17d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,23 @@ +# Security Policy + +## Supported Versions + +Currently, the following versions are actively receiving security updates. We always recommend upgrading to the latest minor version (`^1.9.0`) with your Laravel installation to ensure optimal performance, structural compliance, and security. + +| Version | Maintained? | PHP Requirements | Laravel Framework | +| ------- | ------------------ | ---------------- | ----------------- | +| >= 1.9.0| :white_check_mark: | PHP 8.1+ | 8.x – 13.x | +| >= 1.3.7| :warning: | PHP 8.1+ | 8.x – 12.x | +| < 1.3.7 | :x: | - | - | + +## Reporting a Vulnerability + +If you discover a security vulnerability within the **SmartCache** package, please send an e-mail to **Ismael Azaran** at **eazaran@gmail.com**. We assess all incoming reports within 48 hours to determine the scope and risk of the disclosure. + +Please **do not** publicly disclose the issue on GitHub until we have had an opportunity to address it and publish a fix. When reporting a defect, please include: + +- The Cache Driver and Database you are using (e.g. Redis, File, Memcached, MySQL) +- Whether the issue pertains to data leakage, cache poisoning, deserialization exploits, or denial of service +- Precise steps to reproduce the issue locally + +Once verified, we will work closely with you on a patch and coordinate a security advisory release on GitHub to ensure all developers using the package can update seamlessly and safely. diff --git a/composer.json b/composer.json index ddd5e92..21007b7 100644 --- a/composer.json +++ b/composer.json @@ -53,6 +53,12 @@ "mockery/mockery": "^1.5", "symfony/var-dumper": "^5.4|^6.0|^7.0|^8.0" }, + "suggest": { + "ext-zlib": "Required for compressing cached data using gzip (strongly recommended)", + "ext-json": "Required for optimal auto-serialization of complex arrays", + "ext-redis": "Recommended when utilizing the Redis cache driver for better performance", + "ext-memcached": "Recommended when using the Memcached cache driver for distributed caching" + }, "autoload": { "psr-4": { "SmartCache\\": "src/" diff --git a/config/smart-cache.php b/config/smart-cache.php index 6d0cfa6..1c92163 100644 --- a/config/smart-cache.php +++ b/config/smart-cache.php @@ -30,6 +30,10 @@ | | Configure which optimization strategies are enabled and their options. | + | Note on Adaptive Compression: Adaptive mode will sample chunks of + | your data to determine if they are compressible. It uses more CPU + | but saves time if data is incompressible (like pre-compressed images). + | */ 'strategies' => [ 'compression' => [ @@ -69,6 +73,10 @@ |-------------------------------------------------------------------------- | | Configure the circuit breaker for cache backend failures. + | This is especially useful for distributed caches (like Redis) that + | may go offline temporarily. If the threshold is reached, SmartCache + | will immediately run closures without hitting the broken cache + | and gracefully recover later. | */ 'circuit_breaker' => [ diff --git a/docs/index.html b/docs/index.html index 3d221b3..572fdad 100644 --- a/docs/index.html +++ b/docs/index.html @@ -643,9 +643,10 @@

📦 Installation

Requirements

@@ -657,7 +658,10 @@

Installation Steps

1 Install via Composer: - 
composer require iazaran/smart-cache
+ 
composer require iazaran/smart-cache
+
+# Clear application configuration cache to register the provider
+php artisan optimize:clear
@@ -1414,6 +1418,14 @@

Custom Optimization Strategies

// Register your custom strategy SmartCache::addStrategy(new JsonCompressionStrategy()); +

🛡️ Best Practices & Troubleshooting

+ +
@@ -1599,7 +1611,7 @@

📊 Cache Statistics Dashboard

// GET /smart-cache/dashboard // JSON API endpoints: -// GET /smart-cache/stats - Performance metrics +// GET /smart-cache/statistics - Performance metrics // GET /smart-cache/health - Health check // GET /smart-cache/keys - Managed keys list