From fe268d4da6ef1bc44ec33e7d848236ac3aec44d3 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Fri, 19 Aug 2016 10:27:05 +0200 Subject: [PATCH 1/2] Added an introduction page --- docs/index.md | 2 ++ docs/introduction.md | 77 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 docs/introduction.md diff --git a/docs/index.md b/docs/index.md index 331b96e..afd3bae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,6 +7,8 @@ The PHP Cache organization is dedicated to providing solid, powerful, flexible, Below you will find information about what features our libraries offer, and what adapters we have. You can also find out framework integration libraries. +If you are new to PSR-6 caching you may want to have a look at our [introduction](introduction.md). + ## Cache pool implementations There are plenty of adapters in this organisaion. Each of them lives in a different repository. Splitting them up in multiple packages complies with the *Common reuse principle* and makes it easier for the developer to follow the changes of a specific adapter. diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..838369c --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,77 @@ +# PSR-6 Cache Introduction + +In the late fall 2015 the [PHP-FIG](http://www.php-fig.org/) released a specification +for caching. It is called the [PSR-6](http://www.php-fig.org/psr/psr-6/). Like all the +PSRs it is just a recommendation for improve interoperability. + +## Basic concepts + +The PSR-6 defines two interfaces; a CachePool and a CacheItem. You interact with the +pool to get an item. You will never create an item yourself. + +```php +// Create a pool +$pool = new ApcuCachePool(); + +// Get an item (existing or new) +$item = $pool->getItem('cache_key'); + +// Set some values and store +$item->set('value'); +$item->expiresAfter(60); +$pool->save($item); + +// Verify existence +$pool->hasItem('cache_key'); // True +$item->isHit(); // True + +// Delete +$pool->deleteItem('cache_key'); +$pool->hasItem('cache_key'); // False +``` + + +*Note: A cache item can not be transferred from one pool to another.* + +## Cache keys + +According to the PSR-6 the following characters could be used in a valid cache key; +`A-Z`, `a-z`, `0-9`, `_`, and `.`. Some characters are forbidden like: `{}()/\@:`. If +you use any of the forbidden characters you will get an exception. Other characters +(like `-`) are not forbidden nor valid. It is up to the implementation if they support +that character or not. + +**We recommend to always use valid characters in the cache key.** + +To make sure you do not use an invalid character by mistake, you should hash your keys. + +```php +$cacheKey = sha1($_SERVER['REQUEST_URI']); +``` + +## Choosing a pool + +What cache pool you want to use is up to you. As you can in the +[table on the startpage](index.md#cache-pool-implementations), different pools have +different features. Commonly used poos are: +* Apcu +* Array +* Memcached +* Redis + +The steps to create a pool varies from pool to pool. Look at the pool's repository +to see how to create it. Generally you create an connection to a cache implementation +and then give it to the pool. See a Memcached example: + +```php +$client = new \Memcached(); +$client->addServer('localhost', 11211); +$pool = new MemcachedCachePool($client); +``` + + +## Features + +The PHP-Cache organization has build some more features on top of PSR-6. Look at our +documentation for [tagging](tagging.md), [hierarchy](hierachy.md) or +[namespace](namespace.md) for more information. \ No newline at end of file From 50eae96440153450012807d8271fc32b921f5d09 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Sat, 20 Aug 2016 00:07:23 +0200 Subject: [PATCH 2/2] Typos --- docs/introduction.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/introduction.md b/docs/introduction.md index 838369c..f0dae08 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,8 +1,8 @@ # PSR-6 Cache Introduction In the late fall 2015 the [PHP-FIG](http://www.php-fig.org/) released a specification -for caching. It is called the [PSR-6](http://www.php-fig.org/psr/psr-6/). Like all the -PSRs it is just a recommendation for improve interoperability. +for caching. It is called [PSR-6](http://www.php-fig.org/psr/psr-6/). Like all the +PSRs, it is just a recommendation for improve interoperability. ## Basic concepts @@ -35,7 +35,7 @@ $pool->hasItem('cache_key'); // False ## Cache keys -According to the PSR-6 the following characters could be used in a valid cache key; +According to PSR-6 the following characters could be used in a valid cache key; `A-Z`, `a-z`, `0-9`, `_`, and `.`. Some characters are forbidden like: `{}()/\@:`. If you use any of the forbidden characters you will get an exception. Other characters (like `-`) are not forbidden nor valid. It is up to the implementation if they support @@ -51,7 +51,7 @@ $cacheKey = sha1($_SERVER['REQUEST_URI']); ## Choosing a pool -What cache pool you want to use is up to you. As you can in the +What cache pool you want to use is up to you. As you can see in the [table on the startpage](index.md#cache-pool-implementations), different pools have different features. Commonly used poos are: * Apcu @@ -72,6 +72,6 @@ $pool = new MemcachedCachePool($client); ## Features -The PHP-Cache organization has build some more features on top of PSR-6. Look at our +The PHP-Cache organization has built some more features on top of PSR-6. Look at our documentation for [tagging](tagging.md), [hierarchy](hierachy.md) or -[namespace](namespace.md) for more information. \ No newline at end of file +[namespace](namespace.md) for more information.