Merge pull request #7 from php-cache/docs

Updated docs to reflect the changes to the bundle

Author: cryptiklemur

README.md

@@ -1,60 +1,97 @@
-PHP-Cache cache-bundle [![Build Status](https://travis-ci.org/php-cache/cache-bundle.png?branch=master)](https://travis-ci.org/php-cache/cache-bundle)
-====================
+# PHP-Cache cache-bundle 
+[![Build Status](https://travis-ci.org/php-cache/cache-bundle.png?branch=master)](https://travis-ci.org/php-cache/cache-bundle)
 
-#### Cache Bundle for Symfony 2
+#### Cache Bundle for Symfony 2.6 and above
 
-Symfony 2 library providing PSR-6 compliant cache services for the user. 
-It also lets you cache your sessions and routes.
+This is a Symfony bundle that lets you you integrate your PSR-6 compliant cache service with the framework. 
+It lets you cache your sessions, routes and Doctrine results and metadata. It also provides an integration with the 
+debug toolbar. 
 
-The respective cache extensions will be required for your project.
-
-Redis uses the php redis extension.
 
 #### Requirements
 
-- PHP >= 5.6, < 7.1
-- Symfony >= 2.7, < 4.0 
+- PHP >= 5.5, < 7.1
+- Symfony >= 2.6, ^3.0 
 - [Composer](http://getcomposer.org)
 
-#### To Install
+### To Install
+
+You need to install and enable this bundle and also a PSR-6 cache implementation. In the example below we use the
+[DoctrineAdapterBundle].
 
 Run the following in your project root, assuming you have composer set up for your project
 ```sh
-composer.phar require cache/cache-bundle
+composer require cache/cache-bundle cache/doctrine-adapter-bundle
 ```
 
-Add the bundle to app/AppKernel.php
+Add the bundles to app/AppKernel.php
 
 ```php
 $bundles(
-    ...
-       new Cache\CacheBundle\CacheBundle(),
-    ...
+    // ...
+    new Cache\CacheBundle\CacheBundle(),
+    new Cache\Adapter\DoctrineAdapterBundle\DoctrineAdapterBundle(),
+    // ...
 );
+```
 
 To see all the config options, run `php app/console config:dump-reference cache` to view the config settings
 
 
+#### A word on the cache implementation
+
+This bundle does not register any cache services for you. This is done by [DoctrineAdapterBundle] you should look 
+at its documentation to see how you configure that bundle. Below in an example configuration:
+
+```yml
+cache_adapter_doctrine:
+  providers:
+    acme_redis_cache:
+      type: redis
+      database: 'foo'
+    acme_apc_cache:
+      type: apc
+      namespace: my_ns
+```
+
+### Configuration
+
 #### Doctrine
 
-This bundle allows you to use its services for Doctrine's caching methods of metadata, result, and query.
+This bundle allows you to use its services for Doctrine's caching methods of metadata, result, and query. To use this 
+feature you need to install the [DoctrineBridge]. 
+
+```sh
+composer require cache/psr-6-doctrine-bridge
+```
+
 
-If you want doctrine to use this as the result and query cache, add this
+If you want Doctrine to use this as the result and query cache, you need this configuration: 
 
 ```yml
 cache:
-    doctrine:
-        enabled: true
-        metadata:
-            instance: default
-            entity_managers:   [ default ]       # the name of your entity_manager connection
-            document_managers: [ default ]       # the name of your document_manager connection
-        result:
-            instance: default
-            entity_managers:   [ default, read ] # you may specify multiple entity_managers
-        query:
-            instance: default
-            entity_managers: [ default ]
+  doctrine:
+    enabled: true
+    metadata:
+      service_id: cache.provider.acme_redis_cache
+      entity_managers:   [ default ]       # the name of your entity_manager connection
+      document_managers: [ default ]       # the name of your document_manager connection
+    result:
+      service_id: cache.provider.acme_redis_cache
+      entity_managers:   [ default, read ] # you may specify multiple entity_managers
+    query:
+      service_id: cache.provider.acme_redis_cache
+      entity_managers: [ default ]
+```
+
+To use this with Doctrine's entity manager, just make sure you have `useResultCache` and/or `useQueryCache` set to true. 
+
+```php
+$em = $this->get('doctrine.orm.entity_manager');
+$q = $em->('SELECT u.* FROM Acme\User u');
+$q->useResultCache(true, 3600); 
+$result = $q->getResult();
+
 ```
 
 #### Session
@@ -63,11 +100,10 @@ This bundle even allows you to store your session data in one of your cache clus
 
 ```yml
 cache:
-    session:
-        enabled: true
-        instance: default
-        prefix: "session_"
-        ttl: 7200
+  session:
+    enabled: true
+    service_id: cache.provider.acme_redis_cache
+    ttl: 7200
 ```
 
 #### Router
@@ -76,39 +112,33 @@ This bundle also provides router caching, to help speed that section up. To enab
 
 ```yml
 cache:
-    router:
-        enabled: true
-        instance: default
+  router:
+    enabled: true
+    service_id: cache.provider.acme_redis_cache
 ```
 
-If you change any of your routes, you will need to clear all of the route_* keys in your cache.
-
+If you change any of your routes, you will need to clear the cache. If you use a cache implementation that supports 
+tagging (implements [TaggablePoolTrait](https://github.com/php-cache/taggable-cache/blob/master/src/TaggablePoolInterface.php))
+you can clear the cache tagged with `routing`.
 
-#### To Use
 
-To use this with doctrine's entity manager, just make sure you have `useResultCache` and/or `useQueryCache` set to true. If you want to use the user cache, just grab the service out of the container like so:
+### Clearing the cache
 
-```php
-// Change default to the name of your instance
-$cache = $container->get( 'cache.instance.default' );
-// Or
-$cache = $container->get( 'cache.default' );
-```
+If you want to clear the cache you can run the following commands.
 
-Here is an example usage of the service:
+```sh
+php app/console cache:flush session
+php app/console cache:flush routing
+php app/console cache:flush doctrine
 
-```php
-$cache = $this->get( 'cache.instance.default' );
-$item = $cache->getItem('test');
-if ($item->isHit()) {
-	var_dump($item->get());
-	
-	return;
-}
-
-$cache->saveItem('test', $em->find('AcmeDemoBundle:User', 1), 3600);
+echo "Or you could run: "
+php app/console cache:flush all
 ```
 
 ### Need Help?
 
-Create an issue if you've found a bug, or ping one of us on twitter: @aequasi or @TobiasNyholm
+Create an issue if you've found a bug, or ping one of us on twitter: @aequasi or @TobiasNyholm
+
+
+[DoctrineAdapterBundle]:https://github.com/php-cache/doctrine-adapter-bundle
+[DoctrineBridge]:https://github.com/php-cache/doctrine-bridge

composer.json

@@ -1,7 +1,7 @@
 {
     "name":         "cache/cache-bundle",
     "type":         "library",
-    "description":  "Symfony 2 bundle providing PSR-6 compliant cache services for the user. Many other features.",
+    "description":  "Symfony 2 bundle providing integration between PSR-6 compliant cache services and the framework. It supports cache for sessions, routing and Doctrine",
     "keywords":     [
         "cache",
         "psr6",

src/DependencyInjection/Compiler/DoctrineSupportCompilerPass.php

@@ -66,13 +66,14 @@ protected function enableDoctrineSupport(array $config)
                     continue;
                 }
 
+                // Doctrine can't talk to a PSR-6 cache, so we need a bridge
                 $bridgeServiceId = sprintf('cache.provider.doctrine.%s.bridge', $cacheType);
                 $bridgeDef = $this->container->register($bridgeServiceId, DoctrineCacheBridge::class);
                 $bridgeDef->addArgument(0, new Reference($cacheData['service_id']))
                     ->setPublic(false);
 
                 foreach ($cacheData[$type] as $manager) {
-                    $doctrineDefinitionName =
+                    $doctrineDefinitionId =
                         sprintf(
                             "doctrine.%s.%s_%s_cache",
                             ($type == 'entity_managers' ? 'orm' : 'odm'),
@@ -81,7 +82,7 @@ protected function enableDoctrineSupport(array $config)
                         );
 
                     // Replace the doctrine entity manager cache with our bridge
-                    $this->container->setAlias($doctrineDefinitionName, $bridgeServiceId);
+                    $this->container->setAlias($doctrineDefinitionId, $bridgeServiceId);
                 }
             }
         }