Merge pull request #9742 from cakephp/request-getters

3.next - Add more consistent request getters

src/Http/ServerRequest.php

@@ -1389,6 +1389,7 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
      *
      * @param string|null $name Query string variable name or null to read all.
      * @return string|array|null The value being read
+     * @deprecated 3.4.0 Use getQuery() and withQueryParams() instead.
      */
     public function query($name = null)
     {
@@ -1396,7 +1397,19 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
             return $this->query;
         }
 
-        return Hash::get($this->query, $name);
+        return $this->getQuery($name);
+    }
+
+    /**
+     * Read a specific query value or dotted path.
+     *
+     * @param string $name The name or dotted path to the query param.
+     * @param mixed $default The default value if the named parameter is not set.
+     * @return null|string|array Query data.
+     */
+    public function getQuery($name, $default = null)
+    {
+        return Hash::get($this->query, $name, $default);
     }
 
     /**
@@ -1417,15 +1430,13 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
      * $request->data('Post.title', 'New post!');
      * ```
      *
-     * As of 3.4.0, the setter mode of this method is *deprecated*.
-     * Use `withData` instead.
-     *
      * You can write to any value, even paths/keys that do not exist, and the arrays
      * will be created for you.
      *
      * @param string|null $name Dot separated name of the value to read/write
      * @param mixed ...$args The data to set (deprecated)
      * @return mixed|$this Either the value being read, or this so you can chain consecutive writes.
+     * @deprecated 3.4.0 Use withData() and getData() or getParsedBody() instead.
      */
     public function data($name = null, ...$args)
     {
@@ -1442,15 +1453,45 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
     }
 
     /**
-     * Safely access the values in $this->params.
+     * Provides a safe accessor for request data. Allows
+     * you to use Hash::get() compatible paths.
+     *
+     * ### Reading values.
+     *
+     * ```
+     * // get all data
+     * $request->getData();
+     *
+     * // Read a specific field.
+     * $request->data('Post.title');
      *
-     * As of 3.4.0, the setter mode of this method is *deprecated*.
-     * Use `withParam` instead.
+     * // With a default value.
+     * $request->data('Post.not there', 'default value);
+     * ```
+     *
+     * When reading values you will get `null` for keys/values that do not exist.
+     *
+     * @param string|null $name Dot separated name of the value to read. Or null to read all data.
+     * @param mixed $default The default data.
+     * @return null|string|array The value being read.
+     */
+    public function getData($name = null, $default = null)
+    {
+        if ($name === null) {
+            return $this->data;
+        }
+
+        return Hash::get($this->data, $name, $default);
+    }
+
+    /**
+     * Safely access the values in $this->params.
      *
      * @param string $name The name of the parameter to get.
      * @param mixed ...$args Value to set (deprecated).
      * @return mixed|$this The value of the provided parameter. Will
      *   return false if the parameter doesn't exist or is falsey.
+     * @deprecated 3.4.0 Use getParam() and withParam() instead.
      */
     public function param($name, ...$args)
     {
@@ -1459,11 +1500,8 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
 
             return $this;
         }
-        if (!isset($this->params[$name])) {
-            return Hash::get($this->params, $name, false);
-        }
 
-        return $this->params[$name];
+        return $this->getParam($name);
     }
 
     /**
@@ -1507,6 +1545,7 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
      *
      * @param string $key The key you want to read.
      * @return null|string Either the cookie value, or null if the value doesn't exist.
+     * @deprecated 3.4.0 Use getCookie() instead.
      */
     public function cookie($key)
     {
@@ -1518,6 +1557,18 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
     }
 
     /**
+     * Read cookie data from the request's cookie data.
+     *
+     * @param string $key The key or dotted path you want to read.
+     * @param string $default The default value if the cookie is not set.
+     * @return null|array|string Either the cookie value, or null if the value doesn't exist.
+     */
+    public function getCookie($key, $default = null)
+    {
+        return Hash::get($this->cookies, $key, $default);
+    }
+
+    /**
      * Get all the cookie data from the request.
      *
      * @return array An array of cookie data.
@@ -1743,6 +1794,18 @@ class ServerRequest implements ArrayAccess, ServerRequestInterface
     }
 
     /**
+     * Safely access the values in $this->params.
+     *
+     * @param string $name The name or dotted path to parameter.
+     * @param mixed $default The default value if $name is not set.
+     * @return mixed
+     */
+    public function getParam($name, $default = false)
+    {
+        return Hash::get($this->params, $name, $default);
+    }
+
+    /**
      * Return an instance with the specified request attribute.
      *
      * @param string $name The attribute name.

tests/TestCase/Network/RequestTest.php

@@ -2396,40 +2396,40 @@ class RequestTest extends TestCase
         ];
         $request = new Request($array);
 
-        $result = $request->query('foo');
-        $this->assertSame('bar', $result);
-
-        $result = $request->query('zero');
-        $this->assertSame('0', $result);
-
-        $result = $request->query('imaginary');
-        $this->assertNull($result);
-
-        $result = $request->query();
-        $this->assertSame($array['query'], $result);
+        $this->assertSame('bar', $request->query('foo'));
+        $this->assertSame('0', $request->query('zero'));
+        $this->assertNull($request->query('imaginary'));
+        $this->assertSame($array['query'], $request->query());
     }
 
     /**
-     * Test the query() method with arrays passed via $_GET
+     * Test the getQuery() method
      *
      * @return void
      */
-    public function testQueryWithArray()
+    public function testGetQuery()
     {
-        $get['test'] = ['foo', 'bar'];
-
-        $request = new Request([
-            'query' => $get
-        ]);
-
-        $result = $request->query('test');
-        $this->assertEquals(['foo', 'bar'], $result);
+        $array = [
+            'query' => [
+                'foo' => 'bar',
+                'zero' => '0',
+                'test' => [
+                    'foo', 'bar'
+                ]
+            ]
+        ];
+        $request = new Request($array);
 
-        $result = $request->query('test.1');
-        $this->assertEquals('bar', $result);
+        $this->assertSame('bar', $request->getQuery('foo'));
+        $this->assertSame('0', $request->getQuery('zero'));
+        $this->assertNull($request->getQuery('imaginary'));
+        $this->assertSame('default', $request->getQuery('imaginary', 'default'));
+        $this->assertFalse($request->getQuery('imaginary', false));
 
-        $result = $request->query('test.2');
-        $this->assertNull($result);
+        $this->assertSame(['foo', 'bar'], $request->getQuery('test'));
+        $this->assertSame('bar', $request->getQuery('test.1'));
+        $this->assertNull($request->getQuery('test.2'));
+        $this->assertSame('default', $request->getQuery('test.2', 'default'));
     }
 
     /**
@@ -2527,14 +2527,17 @@ class RequestTest extends TestCase
             ]
         ];
         $request = new Request(compact('post'));
-        $result = $request->data('Model');
-        $this->assertEquals($post['Model'], $result);
+        $this->assertEquals($post['Model'], $request->data('Model'));
+        $this->assertEquals($post['Model'], $request->getData('Model'));
+
+        $this->assertEquals($post, $request->data());
+        $this->assertEquals($post, $request->getData());
 
-        $result = $request->data();
-        $this->assertEquals($post, $result);
+        $this->assertNull($request->data('Model.imaginary'));
+        $this->assertNull($request->getData('Model.imaginary'));
 
-        $result = $request->data('Model.imaginary');
-        $this->assertNull($result);
+        $this->assertSame('value', $request->getData('Model.field', 'default'));
+        $this->assertSame('default', $request->getData('Model.imaginary', 'default'));
     }
 
     /**
@@ -2587,7 +2590,7 @@ class RequestTest extends TestCase
      *
      * @dataProvider paramReadingDataProvider
      */
-    public function testParamReading($toRead, $expected)
+    public function testGetParam($toRead, $expected)
     {
         $request = new Request('/');
         $request->addParams([
@@ -2603,6 +2606,26 @@ class RequestTest extends TestCase
             'zero' => '0',
         ]);
         $this->assertSame($expected, $request->param($toRead));
+        $this->assertSame($expected, $request->getParam($toRead));
+    }
+
+    /**
+     * Test getParam returning a default value.
+     *
+     * @return void
+     */
+    public function testGetParamDefault()
+    {
+        $request = new Request([
+            'params' => [
+                'controller' => 'Articles',
+                'null' => null,
+            ]
+        ]);
+        $this->assertSame('Articles', $request->getParam('controller', 'default'));
+        $this->assertSame('default', $request->getParam('null', 'default'));
+        $this->assertNull($request->getParam('unset', null));
+        $this->assertFalse($request->getParam('unset'));
     }
 
     /**
@@ -2986,18 +3009,26 @@ XML;
      *
      * @return void
      */
-    public function testCookie()
+    public function testGetCookie()
     {
         $request = new Request([
             'cookies' => [
-                'testing' => 'A value in the cookie'
+                'testing' => 'A value in the cookie',
+                'user' => [
+                    'remember' => '1'
+                ]
             ]
         ]);
-        $result = $request->cookie('testing');
-        $this->assertEquals('A value in the cookie', $result);
+        $this->assertEquals('A value in the cookie', $request->cookie('testing'));
+        $this->assertEquals('A value in the cookie', $request->getCookie('testing'));
+
+        $this->assertNull($request->cookie('not there'));
+        $this->assertNull($request->getCookie('not there'));
+        $this->assertSame('default', $request->getCookie('not there', 'default'));
 
-        $result = $request->cookie('not there');
-        $this->assertNull($result);
+        $this->assertSame('1', $request->getCookie('user.remember'));
+        $this->assertSame('1', $request->getCookie('user.remember', 'default'));
+        $this->assertSame('default', $request->getCookie('user.not there', 'default'));
     }
 
     /**