Can get RequestInterface::getUri and MessageInterface::getBody return null?

[PJ Dietz]

The docblock for RequestInterface::getUri says "This method MUST return a UriInterface instance.", then says "Returns a UriInterface instance representing the URI of the request, if any." These seem to be at odds. 

If it MUST return a UriInterface, then "if any" is unnecessary.

If it is possible to have a no URI instance set, then the method should permit null as a return value.

Current:

    /**
     * Retrieves the URI instance.
     *
     * This method MUST return a UriInterface instance.
     *
     * @link http://tools.ietf.org/html/rfc3986#section-4.3
     * @return UriInterface Returns a UriInterface instance
     *     representing the URI of the request, if any.
     */
    public function getUri();

Allow null:

    /**
     * Retrieves the URI instance.
     *
     * This method MUST return a UriInterface instance or null.
     *
     * @link http://tools.ietf.org/html/rfc3986#section-4.3
     * @return UriInterface|null Returns a UriInterface instance
     *     representing the URI of the request, if any.
     */
    public function getUri();

Don't allow null:

    /**
     * Retrieves the URI instance.
     *
     * This method MUST return a UriInterface instance.
     *
     * @link http://tools.ietf.org/html/rfc3986#section-4.3
     * @return UriInterface|null Returns a UriInterface instance
     *     representing the URI of the request.
     */
    public function getUri();

MessageInterface::getBody doesn't have this ambiguity, but I do wonder if explicitly allowing null would be a good thing because it would allow implementations to skip creating empty or do-nothing streams.

Thoughts?

[Matthew Weier O'Phinney]

On Mon, Apr 13, 2015 at 8:24 AM, PJ Dietz <pjd...@gmail.com> wrote:
> The docblock for RequestInterface::getUri says "This method MUST return a
> UriInterface instance.", then says "Returns a UriInterface instance
> representing the URI of the request, if any." These seem to be at odds.
>
> If it MUST return a UriInterface, then "if any" is unnecessary.
>
> If it is possible to have a no URI instance set, then the method should
> permit null as a return value.

We could technically enforce `UriInterface`, and allow a value with no
components defined. This, in many ways, would be better, as you then
prevent these situations:

$path = $request->getUri()->getPath(); // E_FATAL, as it's calling
a method on a null value

<snip>

> MessageInterface::getBody doesn't have this ambiguity, but I do wonder if
> explicitly allowing null would be a good thing because it would allow
> implementations to skip creating empty or do-nothing streams.

Same rationale exists in that method: by always returning a
`StreamInterface`, even if it's a null stream, operations are
guaranteed.

I'll make the above clarification on the Uri momentarily.



--
Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/

[PJ Dietz]

Great, thanks!