Merge pull request #296 from FriendsOfSymfony/update-from-1.4

Update from 1.4

.styleci.yml

@@ -0,0 +1 @@
+preset: symfony

doc/user-context.rst

@@ -11,6 +11,10 @@ The FOSHttpCache library includes a solution to cache responses per user
 context (whether the user is authenticated, groups the user is in, or other
 information), rather than individually.
 
+If every user has their own hash, you probably don't want to cache at all. Or
+if you found out its worth it, vary on the credentials and don't use the
+context hash mechanism.
+
 .. caution::
 
     Whenever you share caches, make sure to **not output any individual content**
@@ -65,8 +69,22 @@ Currently, user context caching is only supported by Varnish and by the Symfony
 HttpCache. See the :ref:`Varnish Configuration <varnish user context>` or
 :ref:`Symfony HttpCache Configuration <symfony-cache user context>`.
 
+User Context Hash from Your Application
+---------------------------------------
+
+It is your application's responsibility to determine the hash for a user. Only
+your application can know what is relevant for the hash. You can use the path
+or the accept header to detect that a hash was requested.
+
+.. warning::
+
+    Treat the hash lookup path like the login path so that anonymous users also
+    can get a hash. That means that your cache can access the hash lookup even
+    with no user provided credential and that the hash lookup never redirects
+    to a login page.
+
 Calculating the User Context Hash
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The user context hash calculation (step 3 above) is managed by the HashGenerator.
 Because the calculation itself will be different per application, you need to
@@ -83,7 +101,7 @@ Once all providers are registered, call ``generateHash()`` to get the hash for
 the current user context.
 
 Context Providers
------------------
+~~~~~~~~~~~~~~~~~
 
 Each provider is passed the :source:`UserContext <src/UserContext/UserContext.php>`
 and updates that with parameters which influence the varied response.
@@ -111,7 +129,7 @@ A provider that looks at whether the user is authenticated could look like this:
 .. _return context hash:
 
 Returning the User Context Hash
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is up to you to return the user context hash in response to the hash request
 (``/_fos_user_context_hash`` in step 3 above)::

src/CacheInvalidator.php

@@ -64,7 +64,7 @@ class CacheInvalidator
     private $eventDispatcher;
 
     /**
-     * Constructor
+     * Constructor.
      *
      * @param ProxyClientInterface $cache HTTP cache
      */
@@ -99,12 +99,12 @@ public function supports($operation)
             case self::TAGS:
                 return $this->cache instanceof TagsInterface;
             default:
-                throw new InvalidArgumentException('Unknown operation ' . $operation);
+                throw new InvalidArgumentException('Unknown operation '.$operation);
         }
     }
 
     /**
-     * Set event dispatcher
+     * Set event dispatcher.
      *
      * @param EventDispatcherInterface $eventDispatcher
      *
@@ -123,7 +123,7 @@ public function setEventDispatcher(EventDispatcherInterface $eventDispatcher)
     }
 
     /**
-     * Get event dispatcher
+     * Get event dispatcher.
      *
      * @return EventDispatcherInterface
      */
@@ -137,7 +137,7 @@ public function getEventDispatcher()
     }
 
     /**
-     * Invalidate a path or URL
+     * Invalidate a path or URL.
      *
      * @param string $path    Path or URL
      * @param array  $headers HTTP headers (optional)
@@ -158,7 +158,7 @@ public function invalidatePath($path, array $headers = [])
     }
 
     /**
-     * Refresh a path or URL
+     * Refresh a path or URL.
      *
      * @param string $path    Path or URL
      * @param array  $headers HTTP headers (optional)
@@ -206,7 +206,7 @@ public function invalidate(array $headers)
     }
 
     /**
-     * Remove/Expire cache objects based on cache tags
+     * Remove/Expire cache objects based on cache tags.
      *
      * @see TagsInterface::tags()
      *

src/Event.php

@@ -18,7 +18,7 @@ class Event extends BaseEvent
     private $exception;
 
     /**
-     * Set exception
+     * Set exception.
      *
      * @param \Exception $exception
      */
@@ -28,7 +28,7 @@ public function setException(\Exception $exception)
     }
 
     /**
-     * Get exception
+     * Get exception.
      *
      * @return \Exception
      */

src/EventListener/LogSubscriber.php

@@ -36,7 +36,7 @@ public static function getSubscribedEvents()
     {
         return [
             Events::PROXY_UNREACHABLE_ERROR => 'onProxyUnreachableError',
-            Events::PROXY_RESPONSE_ERROR    => 'onProxyResponseError',
+            Events::PROXY_RESPONSE_ERROR => 'onProxyResponseError',
         ];
     }
 

src/Events.php

@@ -12,10 +12,10 @@
 namespace FOS\HttpCache;
 
 /**
- * Events thrown by the FOSHttpCache library
+ * Events thrown by the FOSHttpCache library.
  */
 final class Events
 {
     const PROXY_UNREACHABLE_ERROR = 'fos_http_cache.error.proxy_unreachable';
-    const PROXY_RESPONSE_ERROR    = 'fos_http_cache.error.response';
+    const PROXY_RESPONSE_ERROR = 'fos_http_cache.error.response';
 }

src/Exception/ExceptionCollection.php

@@ -13,7 +13,7 @@
 
 /**
  * A collection of exceptions that might occur during the flush operation of a
- * ProxyClientInterface implementation
+ * ProxyClientInterface implementation.
  */
 class ExceptionCollection extends \Exception implements \IteratorAggregate, \Countable, HttpCacheExceptionInterface
 {
@@ -27,7 +27,7 @@ public function __construct(array $exceptions = [])
     }
 
     /**
-     * Add an exception to the collection
+     * Add an exception to the collection.
      *
      * @param \Exception $e
      *
@@ -55,11 +55,11 @@ public function getFirst()
             return $this->exceptions[0];
         }
 
-        return null;
+        return;
     }
 
     /**
-     * Get exception iterator
+     * Get exception iterator.
      *
      * @return \ArrayIterator
      */
@@ -69,7 +69,7 @@ public function getIterator()
     }
 
     /**
-     * Get number of exceptions in collection
+     * Get number of exceptions in collection.
      *
      * @return int
      */

src/Exception/HttpCacheExceptionInterface.php

@@ -15,4 +15,5 @@
  * Common interface for all exceptions thrown by this library.
  */
 interface HttpCacheExceptionInterface
-{}
+{
+}

src/Exception/MissingHostException.php

@@ -26,11 +26,11 @@ public static function missingHost($path)
     {
         $msg = sprintf(
             'Path "%s" cannot be invalidated without a host. '
-            . 'Either invalidate full URLs containing hostnames instead of paths '
-            . 'or configure the caching proxy class with a hostname in the base path.',
+            .'Either invalidate full URLs containing hostnames instead of paths '
+            .'or configure the caching proxy class with a hostname in the base path.',
             $path
         );
 
-        return new MissingHostException($msg);
+        return new self($msg);
     }
 }

src/Exception/ProxyResponseException.php

@@ -31,6 +31,6 @@ public static function proxyResponse(ResponseInterface $response)
             $response->getReasonPhrase()
         );
 
-        return new ProxyResponseException($message, 0);
+        return new self($message, 0);
     }
 }

src/Exception/ProxyUnreachableException.php

@@ -32,7 +32,7 @@ public static function proxyUnreachable(RequestException $adapterException)
             $adapterException->getMessage()
         );
 
-        return new ProxyUnreachableException(
+        return new self(
             $message,
             0,
             $adapterException

src/ProxyClient/AbstractProxyClient.php

@@ -48,7 +48,7 @@ abstract class AbstractProxyClient implements ProxyClientInterface
     protected $options;
 
     /**
-     * Constructor
+     * Constructor.
      *
      * Supported options:
      *

src/ProxyClient/Http/HttpAdapter.php

@@ -1,13 +1,21 @@
 <?php
 
+/*
+ * This file is part of the FOSHttpCache package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 namespace FOS\HttpCache\ProxyClient\Http;
 
 use FOS\HttpCache\Exception\ExceptionCollection;
 use FOS\HttpCache\Exception\InvalidArgumentException;
 use FOS\HttpCache\Exception\InvalidUrlException;
 use FOS\HttpCache\Exception\ProxyResponseException;
 use FOS\HttpCache\Exception\ProxyUnreachableException;
-use Http\Client\Exception;
 use Http\Client\Exception\HttpException;
 use Http\Client\Exception\RequestException;
 use Http\Client\HttpAsyncClient;
@@ -34,7 +42,7 @@ class HttpAdapter
     private $uriFactory;
 
     /**
-     * Queued requests
+     * Queued requests.
      *
      * @var RequestInterface[]
      */
@@ -55,14 +63,14 @@ class HttpAdapter
     private $baseUri;
 
     /**
-     * @param string[] $servers Caching proxy server hostnames or IP
-     *                          addresses, including port if not port 80.
-     *                          E.g. ['127.0.0.1:6081']
-     * @param string   $baseUri Default application hostname, optionally
-     *                          including base URL, for purge and refresh
-     *                          requests (optional). This is required if
-     *                          you purge and refresh paths instead of
-     *                          absolute URLs.
+     * @param string[]        $servers    Caching proxy server hostnames or IP
+     *                                    addresses, including port if not port 80.
+     *                                    E.g. ['127.0.0.1:6081']
+     * @param string          $baseUri    Default application hostname, optionally
+     *                                    including base URL, for purge and refresh
+     *                                    requests (optional). This is required if
+     *                                    you purge and refresh paths instead of
+     *                                    absolute URLs.
      * @param HttpAsyncClient $httpClient
      * @param UriFactory      $uriFactory
      */
@@ -124,8 +132,8 @@ public function flush()
                 $exceptions->add(ProxyResponseException::proxyResponse($exception->getResponse()));
             } catch (RequestException $exception) {
                 $exceptions->add(ProxyUnreachableException::proxyUnreachable($exception));
-            } catch (\Exception $exception)  {
-                    $exceptions->add(new InvalidArgumentException($exception));
+            } catch (\Exception $exception) {
+                $exceptions->add(new InvalidArgumentException($exception));
             }
         }
 
@@ -137,7 +145,7 @@ public function flush()
     }
 
     /**
-     * Duplicate a request for each caching server
+     * Duplicate a request for each caching server.
      *
      * @param RequestInterface $request The request to duplicate for each configured server
      *
@@ -169,7 +177,7 @@ private function fanOut(RequestInterface $request)
 
                 // Base path
                 if ($this->baseUri->getPath() !== '') {
-                    $path = $this->baseUri->getPath() . '/' . ltrim($uri->getPath(), '/');
+                    $path = $this->baseUri->getPath().'/'.ltrim($uri->getPath(), '/');
                     $uri = $uri->withPath($path);
                 }
             }
@@ -185,8 +193,7 @@ private function fanOut(RequestInterface $request)
                 $uri
                     ->withScheme($server->getScheme())
                     ->withHost($server->getHost())
-                    ->withPort($server->getPort())
-                ,
+                    ->withPort($server->getPort()),
                 true    // Preserve application Host header
             );
         }
@@ -232,13 +239,13 @@ private function setBaseUri($uriString = null)
     }
 
     /**
-     * Filter a URL
+     * Filter a URL.
      *
      * Prefix the URL with "http://" if it has no scheme, then check the URL
      * for validity. You can specify what parts of the URL are allowed.
      *
-     * @param string       $uriString
-     * @param string[]     $allowedParts Array of allowed URL parts (optional)
+     * @param string   $uriString
+     * @param string[] $allowedParts Array of allowed URL parts (optional)
      *
      * @return UriInterface Filtered URI (with default scheme if there was no scheme)
      *
@@ -290,6 +297,6 @@ private function getRequestSignature(RequestInterface $request)
         $headers = $request->getHeaders();
         ksort($headers);
 
-        return md5($request->getMethod(). "\n" . $request->getUri(). "\n" . var_export($headers, true));
+        return md5($request->getMethod()."\n".$request->getUri()."\n".var_export($headers, true));
     }
 }

src/ProxyClient/Invalidation/BanInterface.php

@@ -15,15 +15,15 @@
 
 /**
  * An HTTP cache that supports invalidation by banning, that is, removing
- * objects from the cache that match a regular expression
+ * objects from the cache that match a regular expression.
  */
 interface BanInterface extends ProxyClientInterface
 {
     const REGEX_MATCH_ALL = '.*';
     const CONTENT_TYPE_ALL = self::REGEX_MATCH_ALL;
 
     /**
-     * Ban cached objects matching HTTP headers
+     * Ban cached objects matching HTTP headers.
      *
      * Each header is either a:
      * - regular string ('X-Host' => 'example.com')

src/ProxyClient/Invalidation/PurgeInterface.php

@@ -23,7 +23,7 @@
 interface PurgeInterface extends ProxyClientInterface
 {
     /**
-     * Purge a URL
+     * Purge a URL.
      *
      * Purging a URL will remove the cache for the URL (including the query string)
      *