Merge pull request #852 from driehle/docs

Updated docs for caching

docs/en/caching.rst

@@ -1,27 +1,99 @@
 Caching
 =======
 
-DoctrineModule provides bridging between
-`Laminas\Cache <https://github.com/laminas/laminas-cache>`__ and
-`Doctrine\Common\Cache <https://github.com/doctrine/common/tree/master/lib/Doctrine/Common/Cache>`__.
-This may be useful in case you want to share configured cache instances
-across doctrine, symfony and laminas projects.
+DoctrineModule provides some pre-configured caches using
+`Laminas\Cache <https://github.com/laminas/laminas-cache>`__, which can be utilized
+by either Doctrine ORM or Doctrine ODM.
 
-You may use ``Laminas\Cache`` within your doctrine-related projects as
-following:
+The following caches are available by default:
+
+In-Memory
+~~~~~~~~~
+
+Provided by ``laminas/laminas-cache-storage-adapter-memory``, you can pull this cache from
+the container under the key ``doctrine.cache.array``. It does not really do any caching and
+suits merely as a proof of concept or for cases, where you do not want to have caching.
+
+Filesystem
+~~~~~~~~~~
+
+Provided by ``laminas/laminas-cache-storage-adapter-filesystem``, you can pull this cache from
+the container under the key ``doctrine.cache.filesystem``. To override the location for the
+cache storage folder, use the following configuration:
+
+.. code:: php
+    return [
+        'caches' => [
+            'doctrinemodule.cache.filesystem' => [
+                'options' => [
+                    'cache_dir' => './data/cache/',
+                ],
+            ],
+        ],
+    ];
+
+APCu
+~~~~
+
+This cache requires the additional package ``laminas/laminas-cache-storage-adapter-apcu``, which
+is not installed by default.
+
+You can pull the cache from the container using the key ``doctrine.cache.apcu``. To pass additional
+arguments for configuration, use the following config:
 
 .. code:: php
+    return [
+        'caches' => [
+            'doctrinemodule.cache.apcu' => [
+                'options' => [
+
+                ],
+            ],
+        ],
+    ];
 
-   $laminasCache = new \Laminas\Cache\Storage\Adapter\Memory(); // any storage adapter is OK here
-   $doctrineCache = new \DoctrineModule\Cache\LaminasStorageCache($laminasCache);
-   // now use $doctrineCache as a normal Doctrine\Common\Cache\Cache instance
+Memcached
+~~~~~~~~~
 
-You may use ``Doctrine\Common\Cache`` within your Laminas projects as
-following:
+This cache requires the additional package ``laminas/laminas-cache-storage-adapter-memcached``, which
+is not installed by default.
+
+You can pull the cache from the container using the key ``doctrine.cache.memcached``. To pass additional
+arguments for configuration, use the following config:
 
 .. code:: php
+    return [
+        'caches' => [
+            'doctrinemodule.cache.memcached' => [
+                'options' => [
+                    'servers' => [
+
+                    ],
+                ],
+            ],
+        ],
+    ];
 
-   $doctrineCache = new \Doctrine\Common\Cache\ArrayCache(); // any doctrine cache is OK here
-   $adapterOptions = new \Laminas\Cache\Storage\Adapter\AdapterOptions();
-   $laminasCacheStorage = new \DoctrineModule\Cache\DoctrineCacheStorage($adapterOptions, $doctrineCache);
-   // now use $laminasCacheStorage as a normal Laminas\Cache\Storage\StorageInterface instance.
+Redis
+~~~~~~~~~
+
+This cache requires the additional package ``laminas/laminas-cache-storage-adapter-redis``, which
+is not installed by default.
+
+You can pull the cache from the container using the key ``doctrine.cache.redis``. The default config
+will access a Redis server at localhost, port 6379. To pass additional arguments for configuration,
+or to change the default config, use the following config:
+
+.. code:: php
+    return [
+        'caches' => [
+            'doctrinemodule.cache.redis' => [
+                'options' => [
+                    'server' => [
+                        'host' => 'localhost',
+                        'post' => 6379,
+                    ],
+                ],
+            ],
+        ],
+    ];

tests/Authentication/Adapter/ObjectRepositoryTest.php

@@ -110,13 +110,13 @@ public function testAuthentication(): void
             ->expects($this->exactly(2))
             ->method('findOneBy')
             ->with($this->equalTo(['username' => 'a username']))
-            ->will($this->returnValue($entity));
+            ->willReturn($entity);
 
         $objectManager = $this->createMock(ObjectManager::class);
         $objectManager->expects($this->exactly(2))
                       ->method('getRepository')
                       ->with($this->equalTo(IdentityObject::class))
-                      ->will($this->returnValue($objectRepository));
+                      ->willReturn($objectRepository);
 
         $adapter = new ObjectRepositoryAdapter();
         $adapter->setOptions([
@@ -138,7 +138,7 @@ public function testAuthentication(): void
             $result->getIdentity(),
         );
 
-        $method->will($this->returnValue(null));
+        $method->willReturn(null);
 
         $result = $adapter->authenticate();
 
@@ -156,7 +156,7 @@ public function testAuthenticationWithPublicProperties(): void
             ->expects($this->exactly(2))
             ->method('findOneBy')
             ->with($this->equalTo(['username' => 'a username']))
-            ->will($this->returnValue($entity));
+            ->willReturn($entity);
 
         $adapter = new ObjectRepositoryAdapter();
         $adapter->setOptions([
@@ -173,7 +173,7 @@ public function testAuthenticationWithPublicProperties(): void
 
         $this->assertTrue($result->isValid());
 
-        $method->will($this->returnValue(null));
+        $method->willReturn(null);
 
         $result = $adapter->authenticate();
 
@@ -189,7 +189,7 @@ public function testWillRefuseToAuthenticateWithoutGettersOrPublicMethods(): voi
             ->expects($this->once())
             ->method('findOneBy')
             ->with($this->equalTo(['username' => 'a username']))
-            ->will($this->returnValue(new stdClass()));
+            ->willReturn(new stdClass());
 
         $adapter = new ObjectRepositoryAdapter();
         $adapter->setOptions([
@@ -216,7 +216,7 @@ public function testCanValidateWithSpecialCrypt(): void
             ->expects($this->exactly(2))
             ->method('findOneBy')
             ->with($this->equalTo(['username' => 'username']))
-            ->will($this->returnValue($entity));
+            ->willReturn($entity);
 
         $adapter = new ObjectRepositoryAdapter();
         $adapter->setOptions([
@@ -249,7 +249,7 @@ public function testWillRefuseToAuthenticateWhenInvalidInstanceIsFound(): void
             ->expects($this->once())
             ->method('findOneBy')
             ->with($this->equalTo(['username' => 'a username']))
-            ->will($this->returnValue(new stdClass()));
+            ->willReturn(new stdClass());
 
         $adapter = new ObjectRepositoryAdapter();
         $adapter->setOptions([
@@ -283,7 +283,7 @@ public function testWillNotCastAuthCredentialValue(): void
             ->expects($this->once())
             ->method('findOneBy')
             ->with($this->equalTo(['username' => 'a username']))
-            ->will($this->returnValue($entity));
+            ->willReturn($entity);
 
         $this->assertFalse($adapter->authenticate()->isValid());
     }

tests/Authentication/Storage/ObjectRepositoryTest.php

@@ -27,13 +27,13 @@ public function testCanRetrieveEntityFromObjectRepositoryStorage(): void
         $objectRepository->expects($this->exactly(1))
                          ->method('find')
                          ->with($this->equalTo('a username'))
-                         ->will($this->returnValue($entity));
+                         ->willReturn($entity);
 
         $metadata = $this->createMock(ClassMetadata::class);
         $metadata->expects($this->exactly(1))
                  ->method('getIdentifierValues')
                  ->with($this->equalTo($entity))
-                 ->will($this->returnValue($entity->getUsername()));
+                 ->willReturn($entity->getUsername());
 
         $storage = new ObjectRepositoryStorage([
             'objectRepository' => $objectRepository,

tests/Form/Element/ObjectMultiCheckboxTest.php

@@ -63,7 +63,7 @@ public function testGetValueOptionsDoesntCauseInfiniteLoopIfProxyReturnsEmptyArr
         $proxy = $this->createMock(Proxy::class);
         $proxy->expects($this->exactly(2))
             ->method('getValueOptions')
-            ->will($this->returnValue($options));
+            ->willReturn($options);
 
         $element->expects($this->never())
             ->method('setValueOptions');
@@ -80,7 +80,7 @@ public function testGetValueOptionsDoesntInvokeProxyIfOptionsNotEmpty(): void
         $proxy = $this->createMock(Proxy::class);
         $proxy->expects($this->once())
             ->method('getValueOptions')
-            ->will($this->returnValue($options));
+            ->willReturn($options);
 
         $this->setProxyViaReflection($proxy);
 

tests/Form/Element/ObjectRadioTest.php

@@ -37,7 +37,7 @@ public function testGetValueOptionsDoesntCauseInfiniteLoopIfProxyReturnsEmptyArr
         $proxy = $this->createMock(Proxy::class);
         $proxy->expects($this->exactly(2))
             ->method('getValueOptions')
-            ->will($this->returnValue($options));
+            ->willReturn($options);
 
         $element->expects($this->never())
             ->method('setValueOptions');
@@ -54,7 +54,7 @@ public function testGetValueOptionsDoesntInvokeProxyIfOptionsNotEmpty(): void
         $proxy = $this->createMock(Proxy::class);
         $proxy->expects($this->once())
             ->method('getValueOptions')
-            ->will($this->returnValue($options));
+            ->willReturn($options);
 
         $this->setProxyViaReflection($proxy);
 

tests/Form/Element/ObjectSelectTest.php

@@ -81,7 +81,7 @@ public function testGetValueOptionsDoesntCauseInfiniteLoopIfProxyReturnsEmptyArr
         $proxy = $this->createMock(Proxy::class);
         $proxy->expects($this->exactly(2))
               ->method('getValueOptions')
-              ->will($this->returnValue($options));
+              ->willReturn($options);
 
         $element->expects($this->never())
                 ->method('setValueOptions');
@@ -98,7 +98,7 @@ public function testGetValueOptionsDoesntInvokeProxyIfOptionsNotEmpty(): void
         $proxy = $this->createMock(Proxy::class);
         $proxy->expects($this->once())
               ->method('getValueOptions')
-              ->will($this->returnValue($options));
+              ->willReturn($options);
 
         $this->setProxyViaReflection($proxy);
 

tests/Form/Element/ProxyAwareElementTestCase.php

@@ -76,19 +76,19 @@ static function () use ($objectOne, $objectTwo) {
         $objectRepository = $this->createMock(ObjectRepository::class);
         $objectRepository->expects($this->any())
             ->method('findAll')
-            ->will($this->returnValue($result));
+            ->willReturn($result);
 
         $objectManager = $this->createMock(ObjectManager::class);
         $objectManager->expects($this->any())
             ->method('getClassMetadata')
             ->with($this->equalTo($objectClass))
-            ->will($this->returnValue($metadata));
+            ->willReturn($metadata);
 
         $objectManager
             ->expects($this->any())
             ->method('getRepository')
             ->with($this->equalTo($objectClass))
-            ->will($this->returnValue($objectRepository));
+            ->willReturn($objectRepository);
 
         if (! method_exists($this->element, 'getProxy')) {
             throw new RuntimeException('Element must implement getProxy().');