From 69ea52e536577b65e2f3fbf7faa89e91edd929b1 Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@zend.com>
Date: Mon, 2 Feb 2015 12:42:26 -0600
Subject: [PATCH 1/2] Body parameters are the parsed body.

Per conversations with @Crell, @ircmaxell, @pmjones, and several others, the
body parameters are always the parsed body content; calling them out as such,
and without the "parameters" verbiage, implies that parsing may create non-array
values, which is exceptionally likely when working with API and/or
non-form-encoded payloads.

Moreover, the content will always be specific to the incoming request, so
supporting one method representing POST and another representing parsed content
is redundant and potentially confusing.

Finally, considering the fact that the parsed body is an ambiguous domain,
forcing an ubiquitous signature is an unnecessary and limiting constraint.

However, IF the request method is POST, AND the Content-Type is
application/x-www-form-urlencoded, THEN the parsed body MUST be
equivalent to $_POST.
---
 src/ServerRequestInterface.php | 40 +++++++++++++++++++++++-----------
 1 file changed, 27 insertions(+), 13 deletions(-)

diff --git a/src/ServerRequestInterface.php b/src/ServerRequestInterface.php
index 01e6d76..af9db11 100644
--- a/src/ServerRequestInterface.php
+++ b/src/ServerRequestInterface.php
@@ -136,32 +136,46 @@ public function getFileParams();
     /**
      * Retrieve any parameters provided in the request body.
      *
-     * If the request body can be deserialized to an array, this method MAY be
-     * used to retrieve them.
+     * If the request Content-Type is application/x-www-form-urlencoded and the
+     * request method is POST, this method MUST return the contents of $_POST.
      *
-     * @return array The deserialized body parameters, if any.
+     * Otherwise, this method may return any results of deserializing
+     * the request body content; as parsing returns structured content, the
+     * potential types MUST be arrays or objects only. A null value indicates
+     * the absence of body content.
+     *
+     * @return null|array|object The deserialized body parameters, if any.
+     *     These will typically be an array or object.
      */
-    public function getBodyParams();
+    public function getParsedBody();
 
     /**
      * Create a new instance with the specified body parameters.
      *
-     * These MAY be injected during instantiation from PHP's $_POST
-     * superglobal. The data IS NOT REQUIRED to come from $_POST, but MUST be
-     * an array. This method can be used during the request lifetime to inject
-     * parameters discovered and/or deserialized from the request body; as an
-     * example, if content negotiation determines that the request data is
-     * a JSON payload, this method could be used to inject the deserialized
-     * parameters.
+     * These MAY be injected during instantiation.
+     *
+     * If the request Content-Type is application/x-www-form-urlencoded and the
+     * request method is POST, use this method ONLY to inject the contents of
+     * $_POST.
+     *
+     * The data IS NOT REQUIRED to come from $_POST, but MUST be the results of
+     * deserializing the request body content. Deserialization/parsing returns
+     * structured data, and, as such, this method ONLY accepts arrays or objects,
+     * or a null value if nothing was available to parse.
+     *
+     * As an example, if content negotiation determines that the request data
+     * is a JSON payload, this method could be used to create a request
+     * instance with the deserialized parameters.
      *
      * This method MUST be implemented in such a way as to retain the
      * immutability of the message, and MUST return a new instance that has the
      * updated body parameters.
      *
-     * @param array $params The deserialized body parameters.
+     * @param null|array|object $params The deserialized body parameters. These
+     *     will typically be in an array or object.
      * @return self
      */
-    public function withBodyParams(array $params);
+    public function withParsedBody($params);
 
     /**
      * Retrieve attributes derived from the request.

From 5946843093ccffc8fe844deb7b6de3c327510e73 Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@zend.com>
Date: Wed, 11 Feb 2015 13:05:34 -0600
Subject: [PATCH 2/2] Reference $data instead of $params in withParsedBody

---
 src/ServerRequestInterface.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/ServerRequestInterface.php b/src/ServerRequestInterface.php
index af9db11..bc1f976 100644
--- a/src/ServerRequestInterface.php
+++ b/src/ServerRequestInterface.php
@@ -171,11 +171,11 @@ public function getParsedBody();
      * immutability of the message, and MUST return a new instance that has the
      * updated body parameters.
      *
-     * @param null|array|object $params The deserialized body parameters. These
-     *     will typically be in an array or object.
+     * @param null|array|object $data The deserialized body data. This will
+     *     typically be in an array or object.
      * @return self
      */
-    public function withParsedBody($params);
+    public function withParsedBody($data);
 
     /**
      * Retrieve attributes derived from the request.