Merge pull request #17 from byjg/6.0

PHP Cache Engine v6.0

Author: byjg

.github/workflows/phpunit.yml

@@ -12,14 +12,21 @@ on:
 jobs:
   Build:
     runs-on: 'ubuntu-latest'
-    container: 'byjg/php:${{ matrix.php-version }}-cli'
+    container:
+      image: 'byjg/php:${{ matrix.php-version }}-cli'
+      options: --user root --privileged
     strategy:
       matrix:
         php-version:
+          - "8.4"
           - "8.3"
           - "8.2"
           - "8.1"
 
+    env:
+      MEMCACHED_SERVER: "memcached:11211"
+      REDIS_SERVER: "redis:6379"
+
     # Service containers to run 
     services:
       memcached:
@@ -37,10 +44,10 @@ jobs:
           --health-retries 5
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - run: composer install
-      - run: ./vendor/bin/phpunit --stderr
       - run: ./vendor/bin/psalm
+      - run: ./vendor/bin/phpunit
 
   Documentation:
     if: github.ref == 'refs/heads/master'

.gitignore

@@ -5,3 +5,5 @@ vendor
 config/cacheconfig.php
 .idea
 .phpunit.result.cache
+/phpunit.xml.dist.bak
+/.claude/settings.local.json

.gitpod.yml

@@ -0,0 +1,28 @@
+tasks:  
+  - name: Run Composer  
+    command: |  
+      composer install  
+  
+image: byjg/gitpod-image:latest  
+  
+jetbrains:  
+  phpstorm:  
+    vmoptions: '-Xmx4g'  
+  plugins:  
+    - com.github.copilot  
+    - com.intellij.kubernetes  
+    - com.intellij.mermaid  
+    - ru.adelf.idea.dotenv  
+    - org.toml.lang  
+  
+vscode:  
+  extensions:  
+    - ikappas.composer  
+    - hbenl.test-adapter-converter  
+    - hbenl.vscode-test-explorer  
+    - felixfbecker.php-debug  
+    - neilbrayfield.php-docblocker  
+    - bmewburn.vscode-intelephense-client  
+    - getpsalm.psalm-vscode-plugin  
+    - SonarSource.sonarlint-vscode  
+    - recca0120.vscode-phpunit 

.run/PSalm.run.xml

@@ -0,0 +1,8 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="psalm" type="ComposerRunConfigurationType" factoryName="Composer Script">
+    <option name="commandLineParameters" value="" />
+    <option name="pathToComposerJson" value="$PROJECT_DIR$/composer.json" />
+    <option name="script" value="psalm" />
+    <method v="2" />
+  </configuration>
+</component>

.run/psalm.run.xml

@@ -0,0 +1,35 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {  
+            "name": "Debug current Script in Console",  
+            "type": "php",  
+            "request": "launch",  
+            "program": "${file}",  
+            "cwd": "${fileDirname}",  
+            "port": 9003,  
+            "runtimeArgs": [  
+                "-dxdebug.start_with_request=yes"  
+            ],  
+            "env": {  
+                "XDEBUG_MODE": "debug,develop",  
+                "XDEBUG_CONFIG": "client_port=${port}"  
+            }  
+        },
+        {
+            "name": "PHPUnit Debug",
+            "type": "php",
+            "request": "launch",
+            "program": "${workspaceFolder}/vendor/bin/phpunit",
+            "cwd": "${workspaceFolder}",
+            "port": 9003,
+            "runtimeArgs": [
+                "-dxdebug.start_with_request=yes"
+            ],
+            "env": {
+                "XDEBUG_MODE": "debug,develop",
+                "XDEBUG_CONFIG": "client_port=${port}"
+            }
+        }
+    ]
+} 

.vscode/launch.json

@@ -1,84 +1,78 @@
-# Cache Engine
-
 [![Build Status](https://github.com/byjg/php-cache-engine/actions/workflows/phpunit.yml/badge.svg?branch=master)](https://github.com/byjg/php-cache-engine/actions/workflows/phpunit.yml)
 [![Opensource ByJG](https://img.shields.io/badge/opensource-byjg-success.svg)](http://opensource.byjg.com)
 [![GitHub source](https://img.shields.io/badge/Github-source-informational?logo=github)](https://github.com/byjg/php-cache-engine/)
 [![GitHub license](https://img.shields.io/github/license/byjg/php-cache-engine.svg)](https://opensource.byjg.com/opensource/licensing.html)
 [![GitHub release](https://img.shields.io/github/release/byjg/php-cache-engine.svg)](https://github.com/byjg/php-cache-engine/releases/)
 
+# PHP Cache Engine
 
-A multipurpose cache engine PSR-6 and PSR-16 implementation with several drivers.
-
-## PSR-16
- 
-PSR-16 defines a Simple Cache interface with less verbosity than PSR-6. Below a list
-of engines available in this library that is PSR-16 compliant:
-
-PSR-16 Getting Started: [here](docs/basic-usage-psr16-simplecache.md)
-
-## PSR-6
-
-The PSR-6 implementation use the engines defined above. PSR-6 is more verbosity and
-have an extra layer do get and set the cache values.
-
-You can use one of the factory methods to create a instance of the CachePool implementation:
-
-PSR-6 Getting Started: [here](docs/basic-usage-psr6-cachepool.md)
-
-## List of Cache Engines
-
-| Class                                                                                            | Description                                                            |
-|:-------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------|
-| [\ByJG\Cache\Psr16\NoCacheEngine](docs/class-no-cache-engine.md)                                 | Do nothing. Use it for disable the cache without change your code      |
-| [\ByJG\Cache\Psr16\ArrayCacheEngine](docs/class-array-cache-engine.md)                           | Local cache only using array. It does not persists between requests    |
-| [\ByJG\AnyDataset\NoSql\Cache\KeyValueCacheEngine](https://github.com/byjg/php-anydataset-nosql) | Use S3-Like or ClouflareKV as a store for the cache (other repository) |
-| [\ByJG\Cache\Psr16\FileSystemCacheEngine](docs/class-filesystem-cache-engine.md)                 | Save the cache result in the local file system                         |
-| [\ByJG\Cache\Psr16\MemcachedEngine](docs/class-memcached-engine.md)                              | Uses the Memcached as the cache engine                                 |
-| [\ByJG\Cache\Psr16\TmpfsCacheEngine](docs/class-tmpfs-cache-engine.md)                           | Uses the Tmpfs as the cache engine                                     |
-| [\ByJG\Cache\Psr16\RedisCachedEngine](docs/class-redis-cache-engine.md)                          | uses the Redis as cache                                                |
-| [\ByJG\Cache\Psr16\SessionCachedEngine](docs/class-session-cache-engine.md)                      | uses the PHP session as cache                                          |
-| [\ByJG\Cache\Psr16\ShmopCacheEngine](docs/class-shmop-cache-engine.md) (deprecated)              | uses the shared memory area for cache. Use TmpfsCacheEngine.           |
-
-
-## Logging cache commands
- 
-You can add a PSR Log compatible to the constructor in order to get Log of the operations
-
-See log examples [here](docs/setup-log-handler.md)
+A powerful, versatile cache implementation providing both PSR-6 and PSR-16 interfaces with support for multiple storage drivers.
 
-## Use a PSR-11 container to retrieve the cache keys
+## Key Features
 
-You can use a PSR-11 compatible to retrieve the cache keys. 
+- **PSR-16 Simple Cache interface** - Simple, straightforward caching API
+- **PSR-6 Cache Pool interface** - More verbose caching with fine-grained control
+- **Multiple storage backends** - Choose from memory, file system, Redis, Memcached and more
+- **Atomic operations** - Support for increment, decrement and add operations in compatible engines
+- **Garbage collection** - Automatic cleanup of expired items 
+- **PSR-11 container support** - Retrieve cache keys via dependency container
+- **Logging capabilities** - PSR-3 compatible logging of cache operations
 
-See more [here](docs/psr11-usage.md)
+## Quick Start
 
-## Beyond the PSR protocol
-
-The PSR protocol is a good way to standardize the cache access, 
-but sometimes you need to go beyond the protocol.
+```bash
+composer require "byjg/cache-engine"
+```
 
-Some cache engines have additional features that are not covered by the PSR protocol.
+```php
+// PSR-16 Simple Cache
+$cache = new \ByJG\Cache\Psr16\FileSystemCacheEngine();
+$cache->set('key', 'value', 3600); // Cache for 1 hour
+$value = $cache->get('key');
+
+// PSR-6 Cache Pool
+$pool = \ByJG\Cache\Factory::createFilePool();
+$item = $pool->getItem('key');
+if (!$item->isHit()) {
+    $item->set('value');
+    $item->expiresAfter(3600);
+    $pool->save($item);
+}
+$value = $item->get();
+```
 
-Some examples are:
+## Documentation
+
+### Getting Started
+- [PSR-16 Simple Cache Usage](docs/basic-usage-psr16-simplecache.md)
+- [PSR-6 Cache Pool Usage](docs/basic-usage-psr6-cachepool.md)
+
+### Available Cache Engines
+| Engine                                                              | Description                                             |
+|:--------------------------------------------------------------------|:--------------------------------------------------------|
+| [NoCacheEngine](docs/class-no-cache-engine.md)                      | No-op engine for disabling cache without code changes   |
+| [ArrayCacheEngine](docs/class-array-cache-engine.md)                | In-memory array cache (non-persistent between requests) |
+| [FileSystemCacheEngine](docs/class-filesystem-cache-engine.md)      | File system based caching                               |
+| [MemcachedEngine](docs/class-memcached-engine.md)                   | Memcached distributed caching                           |
+| [RedisCacheEngine](docs/class-redis-cache-engine.md)                | Redis-based caching                                     |
+| [SessionCacheEngine](docs/class-session-cache-engine.md)            | PHP session-based caching                               |
+| [TmpfsCacheEngine](docs/class-tmpfs-cache-engine.md)                | Tmpfs-based caching                                     |
+| [ShmopCacheEngine](docs/class-shmop-cache-engine.md)                | Shared memory caching (deprecated)                      |
+| [KeyValueCacheEngine](https://github.com/byjg/php-anydataset-nosql) | S3-Like or CloudflareKV storage (separate package)      |
+
+### Advanced Features
 - [Atomic Operations](docs/atomic-operations.md)
 - [Garbage Collection](docs/garbage-collection.md)
+- [Logging](docs/setup-log-handler.md)
+- [PSR-11 Container Usage](docs/psr11-usage.md)
 
-## Install
-
-Just type: 
-
-```
-composer require "byjg/cache-engine"
-```
-
-
-## Running Unit Testes
+## Running Unit Tests
 
 ```
 vendor/bin/phpunit --stderr
 ```
 
-**Note:** the parameter `--stderr` after `phpunit` is to permit run the tests on SessionCacheEngine.  
+**Note:** The `--stderr` parameter is required for SessionCacheEngine tests to run properly.
 
 ## Dependencies
 
@@ -89,5 +83,6 @@ flowchart TD
     byjg/cache-engine --> psr/simple-cache
     byjg/cache-engine --> psr/container
 ```
+
 ----
 [Open source ByJG](http://opensource.byjg.com)

README.md

@@ -12,15 +12,15 @@
     }
   },
   "require": {
-    "php": ">=8.1 <8.4",
+    "php": ">=8.1 <8.5",
     "psr/cache": "^1.0|^2.0|^3.0",
-    "psr/log": "^1.0|^1.1|^2.0",
+    "psr/log": "^1.0|^2.0|^3.0",
     "psr/simple-cache": "^1.0|^2.0",
     "psr/container": "^1.0|^1.1|^2.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "^9.6",
-    "vimeo/psalm": "^5.9"
+    "phpunit/phpunit": "^10.5|^11.5",
+    "vimeo/psalm": "^5.9|^6.2"
   },
   "suggest": {
     "ext-memcached": "*",
@@ -31,5 +31,9 @@
     "psr/cache-implementation": "1.0",
     "psr/simple-cache-implementation": "1.0"
   },
+  "scripts": {
+    "test": "vendor/bin/phpunit",
+    "psalm": "vendor/bin/psalm"
+  },
   "license": "MIT"
 }

composer.json

@@ -1,24 +1,28 @@
+---
+sidebar_position: 11
+---
+
 # Atomic Operations
 
 Some cache engines allow you to do atomic operations such as incrementing or decrementing a value.
 
-Besides this is not cache operation, it is a common operation in cache engines.
+Although this is not a traditional cache operation, it is a common operation in cache engines.
 
-The advantage of using atomic operations is that you can avoid race conditions when multiple processes 
+The advantage of using atomic operations is that you can avoid race conditions when multiple processes
 are trying to update the same value.
 
-The atomic operations are:
-- Increment: Increment a value by a given number
-- Decrement: Decrement a value by a given number
-- Add: Add a value to a list in the cache
+**Available atomic operations:**
+- **Increment**: Increment a value by a given number
+- **Decrement**: Decrement a value by a given number
+- **Add**: Add a value to a list in the cache
 
-The engines that support atomic operations have to implement the `AtomicOperationInterface`.
+The engines that support atomic operations implement the `AtomicOperationInterface`.
 
-Some engines that support atomic operations are:
-- RedisCachedEngine
+**Engines that support atomic operations:**
+- RedisCacheEngine
 - MemcachedEngine
-- TmpfsCacheEngine
 - FileSystemCacheEngine
+- TmpfsCacheEngine (inherits from FileSystemCacheEngine)
 
 ## Increment
 

docs/atomic-operations.md

@@ -1,6 +1,10 @@
-# Basic Usage - Psr16 Simple Cache
+---
+sidebar_position: 1
+---
 
-Psr16 is a standard for cache in PHP with less verbosity than Psr6.
+# Basic Usage - PSR-16 Simple Cache
+
+PSR-16 is a standard for cache in PHP with less verbosity than PSR-6.
 
 You can just instantiate the cache engine and use it as you can see below. 
 
@@ -11,14 +15,13 @@ You can just instantiate the cache engine and use it as you can see below.
 $cacheEngine = new \ByJG\Cache\Psr16\FileSystemCacheEngine();
 
 $result = $cacheEngine->get($key);
-if (empty($result))
-{
-    // Do the operations will be cached
+if (empty($result)) {
+    // Do the operations that will be cached
     // ....
     // And set variable result
     $result = "...";
 
-    // Set the cache:
+    // Set the cache with 60 seconds TTL:
     $cacheEngine->set($key, $result, 60);
 }
 return $result;