Merge pull request #103 from clue-labs/headers

Add request header accessors (à la PSR-7)

Author: clue

README.md

@@ -36,6 +36,53 @@ $loop->run();
 
 See also the [examples](examples).
 
+## Usage
+
+### Server
+
+See the above usage example and the class outline for details.
+
+### Request
+
+See the above usage example and the class outline for details.
+
+#### getHeaders()
+
+The `getHeaders(): array` method can be used to
+return an array with ALL headers.
+
+The keys represent the header name in the exact case in which they were
+originally specified. The values will be a string if there's only a single
+value for the respective header name or an array of strings if this header
+has multiple values.
+
+> Note that this differs from the PSR-7 implementation of this method,
+which always returns an array for each header name, even if it only has a
+single value.
+
+#### getHeader()
+
+The `getHeader(string $name): string[]` method can be used to
+retrieve a message header value by the given case-insensitive name.
+
+Returns a list of all values for this header name or an empty array if header was not found
+
+#### getHeaderLine()
+
+The `getHeaderLine(string $name): string` method can be used to
+retrieve a comma-separated string of the values for a single header.
+
+Returns a comma-separated list of all values for this header name or an empty string if header was not found
+
+#### hasHeader()
+
+The `hasHeader(string $name): bool` method can be used to
+check if a header exists by the given case-insensitive name.
+
+### Response
+
+See the above usage example and the class outline for details.
+
 ## Install
 
 The recommended way to install this library is [through Composer](http://getcomposer.org).

src/Request.php

@@ -48,11 +48,69 @@ public function getHttpVersion()
         return $this->httpVersion;
     }
 
+    /**
+     * Returns an array with ALL headers
+     *
+     * The keys represent the header name in the exact case in which they were
+     * originally specified. The values will be a string if there's only a single
+     * value for the respective header name or an array of strings if this header
+     * has multiple values.
+     *
+     * Note that this differs from the PSR-7 implementation of this method,
+     * which always returns an array for each header name, even if it only has a
+     * single value.
+     *
+     * @return array
+     */
     public function getHeaders()
     {
         return $this->headers;
     }
 
+    /**
+     * Retrieves a message header value by the given case-insensitive name.
+     *
+     * @param string $name
+     * @return string[] a list of all values for this header name or an empty array if header was not found
+     */
+    public function getHeader($name)
+    {
+        $found = array();
+
+        $name = strtolower($name);
+        foreach ($this->headers as $key => $value) {
+            if (strtolower($key) === $name) {
+                foreach((array)$value as $one) {
+                    $found[] = $one;
+                }
+            }
+        }
+
+        return $found;
+    }
+
+    /**
+     * Retrieves a comma-separated string of the values for a single header.
+     *
+     * @param string $name
+     * @return string a comma-separated list of all values for this header name or an empty string if header was not found
+     */
+    public function getHeaderLine($name)
+    {
+        return implode(', ', $this->getHeader($name));
+    }
+
+    /**
+     * Checks if a header exists by the given case-insensitive name.
+     *
+     * @param string $name
+     * @return bool
+     */
+    public function hasHeader($name)
+    {
+        return !!$this->getHeader($name);
+    }
+
     public function expectsContinue()
     {
         return isset($this->headers['Expect']) && '100-continue' === $this->headers['Expect'];

tests/RequestTest.php

@@ -23,4 +23,38 @@ public function expectsContinueShouldBeTrueIfContinueExpected()
 
         $this->assertTrue($request->expectsContinue());
     }
+
+    public function testEmptyHeader()
+    {
+        $request = new Request('GET', '/');
+
+        $this->assertEquals(array(), $request->getHeaders());
+        $this->assertFalse($request->hasHeader('Test'));
+        $this->assertEquals(array(), $request->getHeader('Test'));
+        $this->assertEquals('', $request->getHeaderLine('Test'));
+    }
+
+    public function testHeaderIsCaseInsensitive()
+    {
+        $request = new Request('GET', '/', array(), '1.1', array(
+            'TEST' => 'Yes',
+        ));
+
+        $this->assertEquals(array('TEST' => 'Yes'), $request->getHeaders());
+        $this->assertTrue($request->hasHeader('Test'));
+        $this->assertEquals(array('Yes'), $request->getHeader('Test'));
+        $this->assertEquals('Yes', $request->getHeaderLine('Test'));
+    }
+
+    public function testHeaderWithMultipleValues()
+    {
+        $request = new Request('GET', '/', array(), '1.1', array(
+            'Test' => array('a', 'b'),
+        ));
+
+        $this->assertEquals(array('Test' => array('a', 'b')), $request->getHeaders());
+        $this->assertTrue($request->hasHeader('Test'));
+        $this->assertEquals(array('a', 'b'), $request->getHeader('Test'));
+        $this->assertEquals('a, b', $request->getHeaderLine('Test'));
+    }
 }