{"id":28955519,"url":"https://github.com/kodedphp/cache-simple","last_synced_at":"2025-08-23T09:05:40.074Z","repository":{"id":52249271,"uuid":"86818027","full_name":"kodedphp/cache-simple","owner":"kodedphp","description":"A PSR-16 caching library.","archived":false,"fork":false,"pushed_at":"2025-06-23T14:53:45.000Z","size":330,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-23T15:53:45.015Z","etag":null,"topics":["cache","caching","file-cache","json","json-data","json-serialization","memcached","psr-16","redis","shmop"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kodedphp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-03-31T12:42:14.000Z","updated_at":"2025-06-23T14:49:02.000Z","dependencies_parsed_at":"2022-08-21T14:31:10.332Z","dependency_job_id":null,"html_url":"https://github.com/kodedphp/cache-simple","commit_stats":{"total_commits":177,"total_committers":2,"mean_commits":88.5,"dds":0.05084745762711862,"last_synced_commit":"a72beeaef80f34a4200745430bda0d88258997c7"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/kodedphp/cache-simple","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodedphp%2Fcache-simple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodedphp%2Fcache-simple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodedphp%2Fcache-simple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodedphp%2Fcache-simple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kodedphp","download_url":"https://codeload.github.com/kodedphp/cache-simple/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kodedphp%2Fcache-simple/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261548735,"owners_count":23175495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","caching","file-cache","json","json-data","json-serialization","memcached","psr-16","redis","shmop"],"created_at":"2025-06-23T20:07:38.756Z","updated_at":"2025-06-23T20:07:39.605Z","avatar_url":"https://github.com/kodedphp.png","language":"PHP","readme":"Koded - Simple Caching Library\n==============================\n\n[![Latest Stable Version](https://img.shields.io/packagist/v/koded/cache-simple.svg)](https://packagist.org/packages/koded/cache-simple)\n[![Build Status](https://travis-ci.org/kodedphp/cache-simple.svg?branch=master)](https://travis-ci.org/kodedphp/cache-simple)\n[![Code Coverage](https://scrutinizer-ci.com/g/kodedphp/cache-simple/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/kodedphp/cache-simple/?branch=master)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/kodedphp/cache-simple/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/kodedphp/cache-simple/?branch=master)\n[![Packagist Downloads](https://img.shields.io/packagist/dt/koded/cache-simple.svg)](https://packagist.org/packages/koded/cache-simple)\n[![Minimum PHP Version](https://img.shields.io/badge/php-%3E%3D%208.1-8892BF.svg)](https://php.net/)\n\nA [PSR-16][10] caching library for PHP 8 using several caching technologies.\nIt supports JSON caching for Redis.\n\n\nRequirements\n------------\n\n\u003e The library is not tested on any Windows OS and may not work as expected there.\n\nThe recommended installation method is via [Composer][3]\n```shell script\ncomposer require koded/cache-simple\n```\n\n### Redis\n\nThere are two client flavors for Redis by using the\n\n  - [Redis extension][2]\n  - [Predis library][5]\n\nand they are not mutually exclusive.\n\nThese clients supports JSON serialization for the cache, useful for handling\nthe cached data in other programming languages.\n\nSince there is no Redis native support for JSON serialization,\nit's done in userland and that always introduces some overhead. **Be aware that the native\nPHP and Igbinary functions are superior.**\n\n  - the `RedisClient` is preferred if Redis extension is installed\n  - the `PredisClient` can be used otherwise\n\n```php\n// with Redis extension\nsimple_cache_factory('redis');\n\n// with Predis library\nsimple_cache_factory('predis');\n```\n\n### Memcached\n\nPlease install the [Memcached extension][1].\n\nUsage\n-----\n\nThe factory function always creates a new instance of specific \n`SimpleCacheInterface` client implementation.\n\n```php\n/*\n * Creates a simple cache instance\n * with MemcachedClient and default configuration\n */\n\n$cache = simple_cache_factory('memcached');\n```\n\n```php\n/*\n * Some configuration directives for the cache client\n * are passed in the second argument as array\n */\n\n$cache = simple_cache_factory('redis', [\n    'host'       =\u003e '127.0.0.1',\n    'serializer' =\u003e 'json',\n    'prefix'     =\u003e 'test:',\n    'ttl'        =\u003e 3600 // 1 hour global TTL\n]);\n```\n\nA bit verbose construction for the same instance is\n\n```php\n$config = new ConfigFactory(['serializer' =\u003e 'json', 'prefix' =\u003e 'test:', 'ttl' =\u003e 3000]);\n$cache = (new ClientFactory($config))-\u003enew('redis');\n```\n\nConfiguration directives\n------------------------\n\nCurrent available configuration classes\n\n  - [RedisConfiguration](#redisconfiguration)\n  - [MemcachedConfiguration](#memcachedconfiguration)\n  - [FileConfiguration](#fileconfiguration)\n  - [PredisConfiguration](#predisconfiguration)\n\n\n\n### RedisConfiguration\n\nPlease refer to [Redis extension connect][7] method.\n\n| Parameter | Value          |\n|-----------|----------------|\n| host      | 127.0.0.1      |\n| port      | 6379           |\n| timeout   | 0.0            |\n| reserved  | null           |\n| retry     | 0              |\n\n```php\n// Without defining the parameters the above directives are used as default\n$cache = simple_cache_factory('redis');\n```\n\n#### Serializers\n\n  - `php` (default)\n  - `json`\n\n\u003e The special config directive is `binary(string)` for setting the internal serializer\n  functions to either PHP native `un/serialize()`, `igbinary_un/serialize()` or `msgpack_un/pack()`.\n\n```php\n$cache = simple_cache_factory('redis', [\n    'binary' =\u003e \\Koded\\Stdlib\\Serializer::MSGPACK\n]);\n```\n\nThe `binary` directive is effective if `igbinary` and/or `msgpack` extensions are installed and loaded.\nOtherwise it defaults to PHP `un/serialize()` functions.\n\n\u003e You can change the binary flag on already cached data, but you should invalidate the\n  previously cached items, since they are already serialized and stored in the cache.\n\n##### JSON serializer options\n\nThe **default** options for [json_encode()][9] function are:\n  - JSON_PRESERVE_ZERO_FRACTION\n  - JSON_UNESCAPED_SLASHES\n  - JSON_THROW_ON_ERROR\n\nTo set the desired options, use the `options` configuration directive:\n\n```php\n$cache = simple_cache_factory('redis', [\n    'serializer' =\u003e 'json',\n    'options' =\u003e JSON_UNESCAPED_SLASHES | JSON_FORCE_OBJECT\n]);\n```\nJSON options are applied with bitmask operators. The above example will\n- remove `JSON_UNESCAPED_SLASHES` (because it's already set)\n- add `JSON_FORCE_OBJECT`\n\n### MemcachedConfiguration\n\n| Memcached arguments         | Type     | Required | Description |\n|:----------------------------|:---------|----------|:------------|\n| id                          | string   | no       | Memcached persistent_id value |\n| servers                     | array    | no       | A list of nested array with \\[server, port\\] values |\n| options                     | array    | no       | A list of Memcached options |\n| ttl                         | int      | no       | Global TTL (in seconds) |\n\nThe following options are set **by default** when an instance of `MemcachedConfiguration` is created,\nexcept for `OPT_PREFIX_KEY` which is there as a reminder that it may be set.\n\n| Memcached option            | Default value                  |\n|:----------------------------|:-------------------------------|\n| OPT_DISTRIBUTION            | DISTRIBUTION_CONSISTENT        |\n| OPT_SERVER_FAILURE_LIMIT    | 2                              |\n| OPT_REMOVE_FAILED_SERVERS   | true                           |\n| OPT_RETRY_TIMEOUT           | 1                              |\n| OPT_LIBKETAMA_COMPATIBLE    | true                           |\n| OPT_PREFIX_KEY              | null                           |\n\n\n\u003e Options with `NULL` value will be removed.\n\nThere are many [Memcached options][4] that may suit the specific needs for the caching scenarios\nand this is something the developer/s needs to figure it out.\n\nExamples:\n\n```php\n[\n    // Memcached client `persistent_id`\n    'id' =\u003e 'items',\n\n    // your Memcached servers list\n    'servers' =\u003e [\n        ['127.0.0.1', 11211],\n        ['127.0.0.2', 11211],\n        ['127.0.0.2', 11212],\n    ],\n\n    // Memcached client options\n    'options' =\u003e [\n        \\Memcached::OPT_PREFIX_KEY            =\u003e 'i:',  // cache item prefix\n        \\Memcached::OPT_REMOVE_FAILED_SERVERS =\u003e false, // changes the default value\n        \\Memcached::OPT_DISTRIBUTION          =\u003e null   // remove this directive with NULL\n    ],\n\n    // the global expiration time (for ALL cached items)\n    'ttl' =\u003e 120,\n]\n```\n\n\n### PredisConfiguration\n\nBy default the parameters are:\n\n| Parameter | Value          |\n|-----------|----------------|\n| scheme    | tcp            |\n| host      | 127.0.0.1      |\n| port      | 6379           |\n\nExamples:\n\n```php\n$cache = simple_cache_factory('predis');\n```\n\n```php\n$cache = simple_cache_factory('predis', [\n    'scheme' =\u003e 'unix',\n    'path' =\u003e '/path/to/redis.sock',\n    'options' =\u003e [\n        'prefix' =\u003e 'i:',\n        'exceptions' =\u003e true,\n        'parameters' =\u003e [\n            'password' =\u003e getenv('REDIS_PASSWORD'),\n            'database' =\u003e 1\n        ]\n    ]\n]);\n```\n\nThere are many configuration options for this package.\nPlease refer to [Predis configuration page][6].\n\n\n### Shared Memory (shmop)\n\nRequires a [PHP shmop extension][11].\n\n```php\n$cache = simple_cache_factory('shmop', [\n    'dir' =\u003e '/path/to/app/cache', // optional\n    'ttl' =\u003e null,                 // global TTL\n]);\n```\n\n\n### FileConfiguration\n\nPlease avoid it on production environments, or use it as a last option.\n\nIf cache directory is not provided in the configuration, the PHP\nfunction [sys_get_temp_dir()][8] is used to store the cached files\nin the OS \"temporary\" directory.\n\n```php\n$cache = simple_cache_factory('file', ['dir' =\u003e '/tmp']);\n```\n\n\n### MemoryClient\n\nThis client will store the cached items in the memory for the duration of the script's lifetime.\nIt is useful for development, but not for production.\n\n\u003e `MemoryClient` is also the default client if you do not \n  require a specific client in `cache_simple_factory()`\n\n```php\n$cache = simple_cache_factory('memory');\n$cache = simple_cache_factory();  // also creates a MemoryClient\n```\n\nCode quality\n------------\n\n```shell script\nvendor/bin/phpunit\n```\n\n```shell script\nvendor/bin/phpbench run --report=default --group=factory\nvendor/bin/phpbench run --report=default --group=read-write\n```\nor\n```shell script\nvendor/bin/phpbench run --report=benchmark --group=read-write\n```\n\n### Benchmarks\n\nThe benchmarks are flaky and dependant on the environment. This table gives \na non-accurate insight how client performs at write-read-delete operations,\nand should have an informative comparison.\n\nTo find out what may be the fastest choice for your environment, run\n```\nvendor/bin/phpbench run --report=default --group=read-write\n\n+-----------------+-----------+-----------+-----------+--------+\n| subject         | best      | mean      | worst     | rstdev |\n+-----------------+-----------+-----------+-----------+--------+\n| bench_predis    | 1.354ms   | 1.403ms   | 1.431ms   | ±2.49% |\n| bench_redis     | 581.000μs | 592.667μs | 609.000μs | ±2.01% |\n| bench_memcached | 581.000μs | 593.333μs | 606.000μs | ±1.72% |\n| bench_file      | 355.000μs | 367.667μs | 385.000μs | ±3.45% |\n| bench_shmop     | 349.000μs | 364.000μs | 374.000μs | ±2.97% |\n| bench_memory    | 77.000μs  | 79.667μs  | 82.000μs  | ±2.58% |\n+-----------------+-----------+-----------+-----------+--------+\n```\n\nLicense\n-------\n[![Software license](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE)\n\nThe code is distributed under the terms of [The 3-Clause BSD license](LICENSE).\n\n\n[1]: https://memcached.org\n[2]: https://redis.io\n[3]: https://getcomposer.org\n[4]: http://php.net/manual/en/memcached.constants.php\n[5]: https://github.com/nrk/predis\n[6]: https://github.com/nrk/predis#client-configuration\n[7]: https://github.com/phpredis/phpredis#connect-open\n[8]: http://php.net/sys_get_temp_dir\n[9]: http://php.net/json_encode\n[10]: https://www.php-fig.org/psr/psr-16/\n[11]: https://www.php.net/manual/en/book.shmop.php\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkodedphp%2Fcache-simple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkodedphp%2Fcache-simple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkodedphp%2Fcache-simple/lists"}