Merge branch 'feature/redirect-response' into develop

Close #59

Author: weierophinney

CHANGELOG.md

@@ -14,6 +14,9 @@ All notable changes to this project will be documented in this file, in reverse
 - [#58](https://github.com/zendframework/zend-diactoros/pull/58) adds
   `Zend\Diactoros\Response\EmptyResponse`, a `Zend\Diactoros\Response` extension
   for quickly creating empty, read-only responses.
+- [#59](https://github.com/zendframework/zend-diactoros/pull/59) adds
+  `Zend\Diactoros\Response\RedirectResponse`, a `Zend\Diactoros\Response` extension
+  for quickly creating redirect responses.
 
 ### Deprecated
 

doc/book/custom-responses.md

@@ -17,6 +17,8 @@ Some standard use cases, however, make this un-wieldy:
 - Returning a response containing JSON; in this case, you likely want to provide the data to
   seriazlize to JSON, not a stream containing serialized JSON.
 - Returning a response with no content; in this case, you don't want to bother with the body at all.
+- Returning a redirect response; in this case, you likely just want to specify the target for the
+  `Location` header, and optionally the status code.
 
 Starting with version 1.1, Diactoros offers several custom response types and factories for
 simplifying these common tasks.
@@ -95,6 +97,34 @@ $response = new EmptyResponse(201, [
 $response = ( new EmptyResponse(201) )->withHeader('Location', $url);
 ```
 
+## Redirects
+
+`Zend\Diactoros\Response\RedirectResponse` is a `Zend\Diactoros\Response` extension for producing
+redirect responses. The only required argument is a URI, which may be provided as either a string or
+`Psr\Http\Message\UriInterface` instance. By default, the status 302 is used, and no other headers
+are produced; you may alter these via the additional optional arguments:
+
+```php
+class RedirectResponse extends Response
+{
+    public function __construct($uri, $status = 302, array $headers = []);
+}
+```
+
+Typical usage is:
+
+```php
+// 302 redirect:
+$response = new RedirectResponse('/user/login');
+
+// 301 redirect:
+$response = new RedirectResponse('/user/login', 301);
+
+// using a URI instance (e.g., by altering the request URI instance)
+$uri = $request->getUri();
+$response = new RedirectResponse($uri->withPath('/login'));
+```
+
 ## Creating custom responses
 
 PHP allows constructor overloading. What this means is that constructors of extending classes can

src/Response/RedirectResponse.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @see       http://github.com/zendframework/zend-diactoros for the canonical source repository
+ * @copyright Copyright (c) 2015 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Zend\Diactoros\Response;
+
+use InvalidArgumentException;
+use Psr\Http\Message\UriInterface;
+use Zend\Diactoros\Response;
+use Zend\Diactoros\Stream;
+
+/**
+ * Produce a redirect response.
+ */
+class RedirectResponse extends Response
+{
+    /**
+     * Create a redirect response.
+     *
+     * Produces a redirect response with a Location header and the given status
+     * (302 by default).
+     *
+     * Note: this method overwrites the `location` $headers value.
+     *
+     * @param string|UriInterface $uri URI for the Location header.
+     * @param int $status Integer status code for the redirect; 302 by default.
+     * @param array $headers Array of headers to use at initialization.
+     */
+    public function __construct($uri, $status = 302, array $headers = [])
+    {
+        if (! is_string($uri) && ! $uri instanceof UriInterface) {
+            throw new InvalidArgumentException(sprintf(
+                'Uri provided to %s MUST be a string or Psr\Http\Message\UriInterface instance; received "%s"',
+                __CLASS__,
+                (is_object($uri) ? get_class($uri) : gettype($uri))
+            ));
+        }
+
+        $headers['location'] = [$uri];
+        parent::__construct('php://temp', $status, $headers);
+    }
+}

test/Response/RedirectResponseTest.php

@@ -0,0 +1,76 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @see       http://github.com/zendframework/zend-diactoros for the canonical source repository
+ * @copyright Copyright (c) 2015 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
+ */
+
+namespace ZendTest\Diactoros\Response;
+
+use PHPUnit_Framework_TestCase as TestCase;
+use Zend\Diactoros\Response\RedirectResponse;
+use Zend\Diactoros\Uri;
+
+class RedirectResponseTest extends TestCase
+{
+    public function testConstructorAcceptsStringUriAndProduces302ResponseWithLocationHeader()
+    {
+        $response = new RedirectResponse('/foo/bar');
+        $this->assertEquals(302, $response->getStatusCode());
+        $this->assertTrue($response->hasHeader('Location'));
+        $this->assertEquals('/foo/bar', $response->getHeaderLine('Location'));
+    }
+
+    public function testConstructorAcceptsUriInstanceAndProduces302ResponseWithLocationHeader()
+    {
+        $uri = new Uri('https://example.com:10082/foo/bar');
+        $response = new RedirectResponse($uri);
+        $this->assertEquals(302, $response->getStatusCode());
+        $this->assertTrue($response->hasHeader('Location'));
+        $this->assertEquals((string) $uri, $response->getHeaderLine('Location'));
+    }
+
+    public function testConstructorAllowsSpecifyingAlternateStatusCode()
+    {
+        $response = new RedirectResponse('/foo/bar', 301);
+        $this->assertEquals(301, $response->getStatusCode());
+        $this->assertTrue($response->hasHeader('Location'));
+        $this->assertEquals('/foo/bar', $response->getHeaderLine('Location'));
+    }
+
+    public function testConstructorAllowsSpecifyingHeaders()
+    {
+        $response = new RedirectResponse('/foo/bar', 302, ['X-Foo' => ['Bar']]);
+        $this->assertEquals(302, $response->getStatusCode());
+        $this->assertTrue($response->hasHeader('Location'));
+        $this->assertEquals('/foo/bar', $response->getHeaderLine('Location'));
+        $this->assertTrue($response->hasHeader('X-Foo'));
+        $this->assertEquals('Bar', $response->getHeaderLine('X-Foo'));
+    }
+
+    public function invalidUris()
+    {
+        return [
+            'null'       => [ null ],
+            'false'      => [ false ],
+            'true'       => [ true ],
+            'zero'       => [ 0 ],
+            'int'        => [ 1 ],
+            'zero-float' => [ 0.0 ],
+            'float'      => [ 1.1 ],
+            'array'      => [ [ '/foo/bar' ] ],
+            'object'     => [ (object) [ '/foo/bar' ] ],
+        ];
+    }
+
+    /**
+     * @dataProvider invalidUris
+     * @expectedException InvalidArgumentException Uri
+     */
+    public function testConstructorRaisesExceptionOnInvalidUri($uri)
+    {
+        $response = new RedirectResponse($uri);
+    }
+}