1. Michael Dowling is the creator of Guzzle, so has a good base of experience with the many problems HTTP messages could bring up

2. It implements much of the advice from previous iterations, meaning we can theoretically get going quicker.

3. It avoids the "HTTP Client" stuff, just giving us the absolute basics of HTTP messaging.

If you gave specific issues then at this stage they can be taken up with Michael offline, via email, on GitHub, wherever but please leave them out of here. This is just a formality at this point, and we don't all need to agree on specific content.

If nobody has any major concerns then I'll put this in for a Entrance Vote a week from now. :)

Out of curiosity, what happened to the idea of having a separate URI
spec that this builds on? Did that get folded back in, or punted as
over-engineering? (I'm still in favor either way, I'm just wondering
what happened to that.)

While a URI spec would be interesting, I don't think it's required for the HTTP message PSR. For example, an HTTP message proposal can allow anything that can be cast to a string to be provided as the URL. This is what I present in the HTTP message PSR I've linked to.

I was never really sure what a URI spec was supposed to be, and as Michael says a URI is just a string, so in regards to this PSR it shouldn't really matter.

Yes, it is a string ultimately, when passed out to the web to make a request for a resource. However, when dealing with web services, the URI needs to be constructed, and that construction needs data to define it and rules/templates to follow. Depending on the scope of a HTTP spec, the construction of URIs may be relevant. A library such as Guzzle will be constructing URIs to access resources, but the part of that library that just deals with the HTTP communication will just be using the URL strings it is given from higher up.

In this case the scope is pretty much limited to the HTTP messaging part, so the URI is just a string. I can see how people may want to widen that to cover more of their use-cases, but scope creep has IMO always been the enemy of the PSR creation process. So yeah, it's just a string. Generating the string is what the URI spec would be about :-)

I fully support this initiative and agree with the reasons behind focusing only on messages. Thanks for taking the lead, Michael!

Kris

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

For the time being, we can probably get away with "string or an
object that implements __toString", which would let us or someone
else later implement URI objects if needed without any hard
dependencies. Drupal is currently debating a URI object for our own
use, although more coupled to the Symfony routing system we have, so
there is demand for it. But I'm fine with leaving it out of scope
for now as it's trivially easy to introduce later without any new
PSR dependencies.

I think we have general agreement that a vote to bring an HTTP
message proposal into the pipeline as PSR-7 would pass. I'd also be
happy to help make this happen.

It's only been two days but this was purely a formality. There is no time requirement, and as we've had enough time for people to see two email digests with subject, people don't have a huge amount of ability to complain.

I haven't had a chance to weigh in on this yet but as I am listed as a sponsor I think it should be obvious I'm interested in seeing this topic explored. Thanks for picking this up, Michael, and thanks to everyone whose work this is based on. I know we've been batting this idea around in various forms for a very long time. It will be great to see where this goes once we have it added to the PSR workflow.

This all seems very interesting, but I'm unclear on what exactly would be standardized by this and how it'll help with interoperability. This isn't to say that I don't think it'll help, just that I literally have not seen this explained anywhere. Is there any chance someone can comment on that a little bit, and speak to what the goals here would be?

This all seems very interesting, but I'm unclear on what exactly would be standardized by this and how it'll help with interoperability. This isn't to say that I don't think it'll help, just that I literally have not seen this explained anywhere. Is there any chance someone can comment on that a little bit, and speak to what the goals here would be?

Robert

HTTP has been discussed here several times which I guess could be a reason why this time the introduction was a little short. That is my fault, I should make things more clear.

A "HTTP" PSR has been on the cards for a really long time, but most felt that it was too much of a challenge to tackle in one go. Just like logging, people were fed up with writing adapter classes for interacting with multiple types of logger, so defining an interface helped people cut that down drastically.

A HTTP Client however did seem like a lot of work to dive straight into, as there were SO MANY factors. To easy this somewhat, a HTTP Message PSR was proposed to tackle the Request/Response stuff first. By defining these, a client would much later be easier to work with. Some systems could easily utilize this PSR to cut their code down, as HttpKernel, Joomla, Drupal, Kohana, Guzzle, Buzz, etc all have similar-by-different Req/Resp classes and that is a little silly.

There were about 5 alternatives happening and nobody had the time/effort/energy to find one and run with it - especially before we had a workflow for handling that stuff. But now Michael is on the case, we lookl like we have a team who is willing and able to get the job done. Hopefully when complete we can keep on trucking with get the HTTP Client lib on the go, which is considerably more useful for the average developer - much like your cache PSR.

Some of that made no sense. I think I must have edited it a few times and not done a very good job. I definitely don't think that "To easy this somewhat" is a valid sentence.

Regardless, it seems like most folks are content with this entering as a PSR, and the vote is going well. If anyone has questions then get in touch, otherwise we can start thinking about what needs to be done in draft.

This draft seems to be adopted this your proposal but I struggle to understand something about the methods getUrl() and setUrl() in the RequestInterface interface: it is unclear to me if this represents the request URI as defined by the HTTP standard (http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2), or an absolute URL that one must split into a Host header and the request URI, or maybe a third signification I don't see.

In the first case, the user has to provide the Host header explicitly for every request since it cannot be deduced from the request URI when the request is made to a proxy, which is OK (but a bit weird for me) but then the methods should be named set/getUri() instead of set/getUrl(), don't you think?.

In the second case, there is a real problem because the Host header may different that the host of the request URI, and the request URI can sometimes be absolute (when a request is issued to a proxy) so we should not split the given URL.

> the request URI can sometimes be absolute (when a request is issued to a proxy) so we should not split the given URL.

So in Guzzle, I have additional methods like getPath(), getQuery(), etc. I chose to go with the simpler approach of just having getUrl() and setUrl() in this PSR proposal in hopes that people would favor the simpler option.

Although I like pretty much everything in this proposal, some of the docblocks concern me.

There seems to be a convention of returning "self" for setter methods, enforcing some kind of dynamic interface (probably for method chaining). I don't think enforcing this logic is appropriate because of the controversial nature of this pattern.

IMHO, method chaining like this breaks encapsulation. To quote Martin Fowler: "every method should either be a command that performs an action, or a query that returns data to the caller, but not both."

But apart from that, this is awesome - really hope it gets official approval soon.

--
You received this message because you are subscribed to the Google
Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it,
send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

Thanks for the link. You're right, he does say that fluent interfaces follow a different set of rules - but he only seems to allow that rule breach for internal DSLs.

I guess the question is whether there is an overwhelming reason to use a fluent interface. I know they can be really helpful when defining verbose configurations or query building (to increase readability), but I'm not sure whether this applies to a simple process of setting a Request body, for example.

I guess it's down to personal preference: Uncle Bob says method chaining are "train wrecks" and should be avoided. Here's another blog post which disparages them.

My general rule is that if a method has
nothing useful to return (because it doesn't make sense in
context), it should return $this. Why? Because returning null is
totally and utterly useless 99% of the time. Returning $this lets
me chain if I want to, but I can safely ignore it if I don't. Not
returning $this means I can't chain even if it would make the code
easier to read.

I actually think that interfacing the fluent interface in those request/response objects will be useless in this case, and will also likely cause some confusion and bugs in implementations, as well as reduce the flexibility of the API.

An HTTP request/response is not an object builder, it is pretty much a VO in most cases, and a VO doesn't return itself when performing operations on it (unless we're doing CoW), and no code should be written (and especially interfaced) if there's no reason to do so.

If the point is saving a couple of keystrokes, then that's not a valid use case for fluent interfaces in first place :)

If you never saw a bad use-case for a fluent interface, or a bug because of its misuse, well then lucky you!

I would accept a fluent interface if there was a strong use-case for it.

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

On 05/23/2014 05:36 PM, Marco Pivetta wrote:
> I actually think that interfacing the fluent interface in those
> request/response objects will be useless in this case, and will also
> likely cause some confusion and bugs in implementations, as well as
> reduce the flexibility of the API.
>
> An HTTP request/response is not an object builder, it is pretty much a
> VO in most cases, and a VO doesn't return itself when performing
> operations on it (unless we're doing CoW), and no code should be
> written (and especially interfaced) if there's no reason to do so.
>
> If the point is saving a couple of keystrokes, then that's not a valid
> use case for fluent interfaces in first place :)
>
> If you never saw a bad use-case for a fluent interface, or a bug
> because of its misuse, well then lucky you!
>
> I would accept a fluent interface if there was a strong use-case for it.
>
>
> Marco Pivetta

Sure, I've seen ugly fluent interfaces. There is no coding technique
ever created that cannot be used to create an incomprehensible crime
against nature itself. That's not the point.

My general guideline is this: If a method has something
useful/meaningful to return, do so, whatever that is. If it has nothing
meaningful to return, return $this so that one *could* chain method
calls if one were so inclined. Given the option between returning NULL
(utterly useless) and $this (optionally saves some typing and can make
code easier to read if not used stupidly), always return $this. Because
being utterly useless is for suckers.

For *most* setter methods (by no means all), there's rarely anything
useful/meaningful to return. So return $this so that you can chain if
you feel like it. If you don't feel like it, cool, no harm done.

`self` is not the "result" of an operation, therefore it should not be returned unless really required.Your setter methods are accessors for a property, they does not produce any result.

If it has nothing meaningful to return, return $this so that one *could* chain method calls if one were so inclined.

I've just said what "meaningful" means here, and `@return self` is not "meaningful".

This is not the point of an interface. An interface is a contract, and the contract states what goes in and what comes out, and that is not to ease development, but to set strict constraints on what is allowed and what isn't
Chaining operations is not something that makes your interface safer or more useful.

Given the option between returning NULL (utterly useless)

We're not returning `NULL`, the method is simply `void`. There is a difference between `@return null` and `@return void`, which is that `@return null` basically "allows" for consumers to use the result of the operation (though indeed useless), while `@return void` defines that consumers SHOULD NOT use the result of the operation.

PHP is not strictly typed, but assigning the result of a `void` expression to a variable in strictly typed languages is a compiler error (as it should be).

and $this (optionally saves some typing and can make code easier to read if not used stupidly), always return $this.

Saving keystrokes is not a good reason to assign different (IMO wrong) semantic meaning to our methods.
If the problem is saving keystrokes, then start abbreviating variables (you will lose readability/explicitness in both cases):

There's nothing useless in a strict interface. The interface is here to avoid having you write wrong implementations, and removing `@return self` on setters makes that simpler.
Also, there is seriously nothing useful in chaining methods unless you are in need for a readable DSL structure, such as (for example) Symfony's DIC config extensions (using FOSUserBundle as an example):

`self` is not the "result" of an operation, therefore it should not be returned unless really required.Your setter methods are accessors for a property, they does not produce any result.

If it has nothing meaningful to return, return $this so that one *could* chain method calls if one were so inclined.

I've just said what "meaningful" means here, and `@return self` is not "meaningful".

This is not the point of an interface. An interface is a contract, and the contract states what goes in and what comes out, and that is not to ease development, but to set strict constraints on what is allowed and what isn't
Chaining operations is not something that makes your interface safer or more useful.

It does not make it less safe or less useful.

Given the option between returning NULL (utterly useless)

We're not returning `NULL`, the method is simply `void`. There is a difference between `@return null` and `@return void`, which is that `@return null` basically "allows" for consumers to use the result of the operation (though indeed useless), while `@return void` defines that consumers SHOULD NOT use the result of the operation.

PHP is not strictly typed, but assigning the result of a `void` expression to a variable in strictly typed languages is a compiler error (as it should be).

This is purely academic and more irrelevant to the conversation than the other talk of fluent stuff was. There is no difference between null and void, other than docblocks, so... whatever. Just pretend Larry said "void" instead of "null" and his point stands.

[snip]

It's not your place to suggest that fluent is a good way to do things or a bad way to do things. At best this interface would be indifferent to them as PHP interfaces do not currently support return types, so we can say do whatever you like, or we can accept that getters get things and setters are fluent - like every single PHP class and package I can remember using in the last few years.

This is purely academic and more irrelevant to the conversation than the other talk of fluent stuff was.

Please don't be the DHH of the situation. Academic knowledge works, otherwise it wouldn't be passed on. I just felt something was wrong and told why it is so. If it is irrelevant to you, then keep it that way, but `null` and `void` are different, and PHP turns out to be always returning `null` when a method is `void`. Yes, that's an engine thing, still different for the annotations.

It's not your place to suggest that fluent is a good way to do things or a bad way to do things.

Pardon me, this may be a language barrier issue, but I think there are more explicit ways to say "shut your mouth".If feedback is not welcome on this mailing list, then just say so and I'll keep lurking instead of trying to be helpful.

Isn't this a discussion list? Or maybe is it just for the votes? Did I miss something? Anyone?

At best this interface would be indifferent to them as PHP interfaces do not currently support return types, so we can say do whatever you like,

Wrong. We trust the return types, even if they aren't enforced by the engine. We've been doing that for years and we test our classes in order to respect our docblocks, and that's because PHP has always messed with us when we didn't.

Ultimately, type-hints are (hopefully) landing in PHP 5.7 (or whatever comes next) and we already have HackLang because we want them so badly.

So yes, even if it is a docblock, it still defines a contract, and people should implement every bit of it, even if just by using static introspection tools that use these annotations to tell us that we're doing it wrong, while at runtime everything works (woah, HackLang even does exactly this!).

Heck, we are even having something like a PSR just about annotations!

or we can accept that getters get things and setters are fluent - like every single PHP class and package I can remember using in the last few years.

Trends change, and TBH, I didn't find anything concrete (written/blogged/published) about why fluent interfaces are a smell, so that's why I felt the need to write it down.

This doesn't mean that what I write should be taken for granted, but that little thought has been put in fluent interface smells in the past (I think there's something about it in "Effective Java", but I'm not really sure).
That's why you probably have that many fluent interfaces coded without previous thoughts put in "why" making them fluent.Just like Larry said above, we've been (are) doing it blindly for no proper good reason.
Yes, there are bigger problems, but this is still a problem, and it can be solved immediately.

I second Ocramius' opinion and it may also save us on a possible expansion of PSRs PHPCS later.

It avoids WTF/min by "disallowing" context switching is the root cause of many already known NullPointerException in Java.

Example:

$user->getLocation()->getCity()->getName();

What happens if getLocation() returns null? In Java, NullPointerException.

Bringing same concept of context switching to setters for the sake of fewer keystrokes is really bad. Look again at Symfony's DIC config extension and ask yourselves how many context switches happened there.

That brings the exact reason why "One dot per line" is an Object Calisthenics rule. It provides you a tougher decision that addresses the problem that you guys tend to bypass by adopting fluent interfaces.

It also prevents anyone to write a standardized PHPCS rule to look for that.

Cheers,

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

Am 25.05.2014 04:21 schrieb "Larry Garfield" <la...@garfieldtech.com>:
>
> Forking the thread title...
>
> On 05/23/2014 05:36 PM, Marco Pivetta wrote:
>>
>> I actually think that interfacing the fluent interface in those request/response objects will be useless in this case, and will also likely cause some confusion and bugs in implementations, as well as reduce the flexibility of the API.
>>
>> An HTTP request/response is not an object builder, it is pretty much a VO in most cases, and a VO doesn't return itself when performing operations on it (unless we're doing CoW), and no code should be written (and especially interfaced) if there's no reason to do so.
>>
>> If the point is saving a couple of keystrokes, then that's not a valid use case for fluent interfaces in first place :)
>>
>> If you never saw a bad use-case for a fluent interface, or a bug because of its misuse, well then lucky you!
>>
>> I would accept a fluent interface if there was a strong use-case for it.
>>
>>
>> Marco Pivetta

>
>
> Sure, I've seen ugly fluent interfaces. There is no coding technique ever created that cannot be used to create an incomprehensible crime against nature itself. That's not the point.
>

> My general guideline is this: If a method has something useful/meaningful to return, do so, whatever that is. If it has nothing meaningful to return, return $this so that one *could* chain method calls if one were so inclined. Given the option between returning NULL (utterly useless) and $this (optionally saves some typing and can make code easier to read if not used stupidly), always return $this. Because being utterly useless is for suckers.
>
> For *most* setter methods (by no means all), there's rarely anything useful/meaningful to return. So return $this so that you can chain if you feel like it. If you don't feel like it, cool, no harm done.
>
> An "undefined" return type is a dead end. I don't like dead ends.

I always propagate to avoid fluent interfaces as long as one don't want to introduce a DSL. It only leads to bad habits. And that only to save some characters...

- What is the definition of "When a method has something useful to return"? Every method, that returns 'void' should return the current insurance instead? What happens, when the method can return something "useful" in the future? This is impossible and anyway would be confusing with other fluent methods.
- what if the context changes? One method returns a different instance? Now in a long chain of method calls we have a context change everybody needs to be aware of.
- who defined, what a "useful return value" is? A setter can always the old value instead.

I can find more, but at the end: all this only to save some characters?!

So as a non-voter I really prefer to rather discourage this, than recommend it. It only leads to bad behaviors.

Regards,
Sebastian

>
> --Larry Garfield

>
> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.

I started to say that a compromise here would be to allow for including a FluentDooblyGooblyInterface alongside any DooblyGooblyInterface, where the difference is "return void => becomes => return self". However, the proliferation of additional interface definitions to just allow this one behavioral difference feels like a code smell to me. Thinking further, would a FluentAwareInterface of just isFluent(boolean $flag) be a useful structure, where the PSR requirement for using that interface is that any "return void" behavior in an implementer is required to check that flag and "return self"? By moving the behavior distinction into an interface definition, then an implementer of some other interface can just list itself as also implementing FluentAwareInterface.

I'm not fully convinced here just yet, as this either requires a further documentation requirement for the implementer of "@return void|self", or it means a documented "return void" allows for a semi-undocumented "return self". Thus, consider this a brainstorming thought that I'm throwing against the wall ;-)

This is purely academic and more irrelevant to the conversation than the other talk of fluent stuff was.

Please don't be the DHH of the situation. Academic knowledge works, otherwise it wouldn't be passed on. I just felt something was wrong and told why it is so. If it is irrelevant to you, then keep it that way, but `null` and `void` are different, and PHP turns out to be always returning `null` when a method is `void`. Yes, that's an engine thing, still different for the annotations.

I'm sorry, I didn't meant that it was irrelevant to me, I meant that it was irrelevant to what we had been talking about. It was like picking a hole in something Larry said for no reason. He said NULL, you wanted to explain that really it was Void, being represented as a Null. That has no benefit to anyone, not me, not larry or anyone else in the conversation. It was a "well actually" that didn't need to be said. :)

It's not your place to suggest that fluent is a good way to do things or a bad way to do things.

Pardon me, this may be a language barrier issue, but I think there are more explicit ways to say "shut your mouth".If feedback is not welcome on this mailing list, then just say so and I'll keep lurking instead of trying to be helpful.

Isn't this a discussion list? Or maybe is it just for the votes? Did I miss something? Anyone?

This has nothing to do with memebership status and feedback is always welcome, of course!

One person can't just say "This design pattern is bad and shouldnt be used.", especially when that opinion can translate to forcing the hand of implementors. Writing off a whole design pattern because you've seen some bad uses of it is extreme. So lets just make sure we implement it logically - if we implement it.

At best this interface would be indifferent to them as PHP interfaces do not currently support return types, so we can say do whatever you like,

Wrong. We trust the return types, even if they aren't enforced by the engine.

When I mean "do whatever you like" I mean, we can just not specify that you MUST use the fluent pattern. Your PR does that, by removing the return type. Not specifying a return type means that implementors can do whatever they like.

So, im not against that PR. I would be against us specifically adding @return void or @return null, because that would be forcing the hand of implementers on something that is their decision - not yours. :)

or we can accept that getters get things and setters are fluent - like every single PHP class and package I can remember using in the last few years.

Trends change, and TBH, I didn't find anything concrete (written/blogged/published) about why fluent interfaces are a smell, so that's why I felt the need to write it down.

This doesn't mean that what I write should be taken for granted, but that little thought has been put in fluent interface smells in the past (I think there's something about it in "Effective Java", but I'm not really sure).
That's why you probably have that many fluent interfaces coded without previous thoughts put in "why" making them fluent.Just like Larry said above, we've been (are) doing it blindly for no proper good reason.
Yes, there are bigger problems, but this is still a problem, and it can be solved immediately.

It's a problem to you. I read your whole blog and disagree that its a problem. People using fluent pattern to do stupid things (requiring action A happens before action B but using fluent stuff to do it) is a problem, and I've not ever seen anyone doing that. If they did do that, I'd tell them to stop doing that.

My personal opinion is that it is not a problem, but I don't mind if we let this PR be vague enough to let people use fluent if they want, or not use it if they dont want.

I started to say that a compromise here would be to allow for including a FluentDooblyGooblyInterface alongside any DooblyGooblyInterface, where the difference is "return void => becomes => return self". However, the proliferation of additional interface definitions to just allow this one behavioral difference feels like a code smell to me. Thinking further, would a FluentAwareInterface of just isFluent(boolean $flag) be a useful structure, where the PSR requirement for using that interface is that any "return void" behavior in an implementer is required to check that flag and "return self"? By moving the behavior distinction into an interface definition, then an implementer of some other interface can just list itself as also implementing FluentAwareInterface.

I'm not fully convinced here just yet, as this either requires a further documentation requirement for the implementer of "@return void|self", or it means a documented "return void" allows for a semi-undocumented "return self". Thus, consider this a brainstorming thought that I'm throwing against the wall ;-)

I came to a similar conclusion after following this enormous thread over the last few moths, and posted it on the PR (having overlooked your post here). It's been suggested it may be worthwhile repeating it here:-

I like fluent interfaces. I love fluent interfaces. It is not about being able to type fewer characters, but about visualising the code. I look at a fluent structure, coming back to it months after coding it, and it just feels and looks right. That's not to say it cannot be abused, especially when chains of references hop between different objects at each stage. But it is the responsibility of the programmer to behave in these instances.

However, as a PSR recommendation I am not sure it should be mandated. The PSR needs to be explicit - to be compliant with this PSR, the methods must return void. If people are free to put in their their own return values (which will happen if the PSR does not say otherwise - what it not said, being open to interpretation), then developers relying on the return values of some implementations will have a problem switching to other implementations. As others have pointed out, it makes for less portable code.

There is no reason why a library could not provide a fluent version of its API though. There would be the PSR layer that does not make any assumptions about how code is going to be chained together. Then there can be the fluent layer that adds `return $this` to methods where relevant. That serves to keep the fluent users happy (inc. me), and also provides a source of documentation in one place showing which methods support fluent.

When fluent falls out of favour, and we all move to FluentPlus®, new layers can be added without affecting the underlying PSR compliant library.

If I want to swap out a library that has a fluent layer built-in, with a library that does not, then I port those fluent override classes to my own project, knowing that it will work with my code. And by "port", I mean just change the `namespace` and `use` clauses, since everything else in that layer would remain pretty much the same.

So I use `MyLib\Fluent\Stuff` instead of `MyLib\Stuff` to get at the fluent API.

Anyway, too much detail. The point is, fluent APIs can be layered over any library that wishes to support it. Not mandating it in the PSR - and being explicit that it should not be used for the PSR layers of a library - will mean more flexibility in the long run in what can be implemented *on top* of the PSR part of the library.

It's probably better to proxy/decorate as opposed to subclass in this
case, but this definitely demonstrates that for the folks that want a
fluid interface, it's still very easy to achieve this, without forcing
it upon people that don't want it.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

Nice start! I tweaked it a bit to account for the fluent wrapper to be able to know which methods should return self as some methods may intentionally return null and null being a valid response. You can argue whether this actually makes sense to do or not, but that is outside of the scope of this discussion.