Merge pull request #41 from ddeboer/simplify-exceptions

use factory methods for exceptions

Author: ddeboer

src/CacheInvalidator.php

@@ -3,6 +3,7 @@
 namespace FOS\HttpCache;
 
 use FOS\HttpCache\Exception\ExceptionCollection;
+use FOS\HttpCache\Exception\InvalidArgumentException;
 use FOS\HttpCache\Exception\ProxyResponseException;
 use FOS\HttpCache\Exception\ProxyUnreachableException;
 use FOS\HttpCache\Exception\UnsupportedInvalidationMethodException;
@@ -73,7 +74,7 @@ public function __construct(CacheProxyInterface $cache)
      *
      * @return bool
      *
-     * @throws \InvalidArgumentException
+     * @throws InvalidArgumentException
      */
     public function supports($operation)
     {
@@ -85,7 +86,7 @@ public function supports($operation)
             case self::INVALIDATE:
                 return $this->cache instanceof BanInterface;
             default:
-                throw new \InvalidArgumentException('Unknown operation ' . $operation);
+                throw new InvalidArgumentException('Unknown operation ' . $operation);
         }
     }
 

src/Exception/ExceptionCollection.php

@@ -6,7 +6,7 @@
  * A collection of exceptions that might occur during the flush operation of a
  * CacheProxyInterface implementation
  */
-class ExceptionCollection extends \Exception implements \IteratorAggregate, \Countable
+class ExceptionCollection extends \Exception implements \IteratorAggregate, \Countable,  HttpCacheExceptionInterface
 {
     protected $exceptions = array();
 
@@ -29,9 +29,9 @@ public function add(\Exception $e)
     }
 
     /**
-     * Get first exception in collection
+     * Get first exception in collection or null, if there is none.
      *
-     * @return \Exception | null
+     * @return \Exception|null
      */
     public function getFirst()
     {

src/Exception/HttpCacheExceptionInterface.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace FOS\HttpCache\Exception;
+
+/**
+ * Common interface for all exceptions thrown by this library.
+ */
+interface HttpCacheExceptionInterface
+{}

src/Exception/InvalidArgumentException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace FOS\HttpCache\Exception;
+
+/**
+ * Wrapping the base exception for FOSHttpCache.
+ */
+class InvalidArgumentException extends \InvalidArgumentException implements HttpCacheExceptionInterface
+{
+}

src/Exception/InvalidUrlException.php

@@ -2,21 +2,56 @@
 
 namespace FOS\HttpCache\Exception;
 
-class InvalidUrlException extends \InvalidArgumentException
+/**
+ * Thrown during setup if the configuration for a cache proxy is invalid.
+ */
+class InvalidUrlException extends InvalidArgumentException implements HttpCacheExceptionInterface
 {
     /**
-     * Constructor
+     * @param string $url    The invalid URL.
+     * @param string $reason Further explanation why the URL was invalid (optional)
      *
-     * @param string $url    Invalid URL
-     * @param string $reason Reason (optional)
+     * @return InvalidUrlException
      */
-    public function __construct($url, $reason = null)
+    public static function invalidUrl($url, $reason = null)
     {
         $msg = sprintf('URL "%s" is invalid.', $url);
         if ($reason) {
             $msg .= sprintf('Reason: %s', $reason);
         }
 
-        parent::__construct($msg);
+        return new InvalidUrlException($msg);
+    }
+
+    /**
+     * @param string $server  Invalid server
+     * @param array  $allowed Allowed URL parts
+     *
+     * @return InvalidUrlException
+     */
+    public static function invalidUrlParts($server, array $allowed)
+    {
+        return new InvalidUrlException(sprintf(
+            'Server "%s" is invalid. Only %s URL parts are allowed.',
+            $server,
+            implode(', ', $allowed)
+        ));
+    }
+
+    /**
+     * @param string $url     Requested full URL
+     * @param string $scheme  Requested URL scheme
+     * @param array  $allowed Supported URL schemes
+     *
+     * @return InvalidUrlException
+     */
+    public static function invalidUrlScheme($url, $scheme, array $allowed)
+    {
+        return new InvalidUrlException(sprintf(
+            'Host "%s" with scheme "%s" is invalid. Only schemes "%s" are supported',
+            $url,
+            $scheme,
+            implode(', ', $allowed)
+        ));
     }
 }

src/Exception/InvalidUrlPartsException.php

@@ -2,14 +2,18 @@
 
 namespace FOS\HttpCache\Exception;
 
-class MissingHostException extends \RuntimeException
+/**
+ * Thrown when there is no default host configured and an invalidation request
+ * with just a path is made.
+ */
+class MissingHostException extends \RuntimeException implements HttpCacheExceptionInterface
 {
     /**
-     * Constructor
+     * @param string $path The path that was asked to be invalidated.
      *
-     * @param string $path Path
+     * @return MissingHostException
      */
-    public function __construct($path)
+    public static function missingHost($path)
     {
         $msg = sprintf(
             'Path "%s" cannot be invalidated without a host. '
@@ -18,6 +22,6 @@ public function __construct($path)
             $path
         );
 
-        parent::__construct($msg);
+        return new MissingHostException($msg);
     }
 }

src/Exception/InvalidUrlSchemeException.php

@@ -3,18 +3,26 @@
 namespace FOS\HttpCache\Exception;
 
 /**
- * An error response from the caching proxy
+ * Wrapping an error response from the caching proxy.
  */
-class ProxyResponseException extends \RuntimeException
+class ProxyResponseException extends \RuntimeException implements HttpCacheExceptionInterface
 {
-    public function __construct($proxy, $statusCode, $statusMessage, \Exception $previous = null)
+    /**
+     * @param string     $host          The host name that was contacted.
+     * @param string     $statusCode    The status code of the reply.
+     * @param string     $statusMessage The content of the reply.
+     * @param \Exception $previous      The exception from guzzle.
+     *
+     * @return ProxyUnreachableException
+     */
+    public static function proxyResponse($host, $statusCode, $statusMessage, \Exception $previous = null)
     {
-        parent::__construct(
+        return new ProxyResponseException(
             sprintf(
                 '%s error response "%s" from caching proxy at %s',
                 $statusCode,
                 $statusMessage,
-                $proxy
+                $host
             ),
             $statusCode,
             $previous

src/Exception/MissingHostException.php

@@ -3,13 +3,21 @@
 namespace FOS\HttpCache\Exception;
 
 /**
- * Thrown when a request to the reverse caching proxy fails
+ * Thrown when a request to the reverse caching proxy fails to establish a
+ * connection.
  */
-class ProxyUnreachableException extends \RuntimeException
+class ProxyUnreachableException extends \RuntimeException implements HttpCacheExceptionInterface
 {
-    public function __construct($host, $message, \Exception $previous = null)
+    /**
+     * @param string     $host     The host name that was contacted.
+     * @param string     $message  The error message from guzzle.
+     * @param \Exception $previous The exception from guzzle.
+     *
+     * @return ProxyUnreachableException
+     */
+    public static function proxyUnreachable($host, $message, \Exception $previous = null)
     {
-        parent::__construct(
+        return new ProxyUnreachableException(
             sprintf(
                 'Request to caching proxy at %s failed with message "%s"',
                 $host,