Fluent interfaces. Sigh. They help sometimes, they really do. In fact I don’t have anything against the idea, it’s the actual use that makes me uncomfortable….

Think of the process of filling up that order as if it were a physical assembly line in a factory. The order starts as an empty container headed down a conveyor belt. At each step, a robot picks up the container, operates on its contents to add, alter, or remove things, and puts the container back on the line.

But when there is a side-effect created by one of those robots, how do we deal with that further down the assembly line? Maybe the factory is out of “TAL” widgets. One option would be to fail immediately. I tend to think that the construction of our customer’s order should continue, adding the HPK and LGV widgets. The robot in charge of adding that TAL widget to the order, should attach a notice with some nice info, perhaps the next expected date of TAL availability. At the end of my metaphorical assembly line, a quality-control engineer would see that notice and take action, perhaps throwing out the order, perhaps presenting some options to the customer.

It’s pretty obvious that Order->with() can never return null or throw an exception. These fluent interfaces like phpUnit’s mock object API surely make certain that null returns or exceptions will never arise. So, is it part of the definition of a fluent interface that the chained method calls will never return null, and never throw exceptions?

$ php -r '$o = null; $o->anything;';
PHP Notice:  Trying to get property of non-object in Command line code on line 1

$ php -r '$o = null; $o->anything();';
PHP Fatal error:  Call to a member function anything() on a non-object in Command line code on line 1

If you attempt to get a property of a non-object, a notice will be raised. If you attempt to call a method on a non-object, a fatal error will occur.

There are few examples of true fluent interfaces in PHP. One is the PHPUnit mocking API, which you can read about in the Pocket Guide. Its methods use appropriate vocabulary that make it a fluent interface as described by Martin Fowler’s original article. Since it is designed as an actual fluent interface, each method always returns the object handle and you don’t have these problems.

Both of your examples above use object chaining but neither is a fluent interface. It’s important to understand the difference and not abuse chaining.

Hope you see this, given that I’m commenting on a 2-year-old article, but since this page is the first Google hit for “PHP fluent interfaces” I’ve got a question-

Is there a workaround for when a method in the middle of a fluent call returns null, or a non-object, or something else unexpected? For instance, the SimpleXML API tries to expose a fluent interface, but it’ll throw you a fatal error if you try to access nodes that don’t exist, then call methods on them. Like
foo->bar->baz->children();
?>
if there is no node.

Or maybe you have an ORM where an Order has Items, and an Item may or may not have a shipping record with a shipping date, you might do this:
getItem(0)->getShippingRecord()->date;
?>
which would fail miserably if the Item has no shipping record.

I feel like usability would improve if my program would just return null in these cases. Are you aware of anything that would facilitate this?

However, in the fluent style, you apply it to the result of with(5, ‘HPK’), which is supposed to be $this representing the customer object, meaning the method skippable() is actually applied to the customer, not to the OrderLine to which it is appended.

Now, if the methods do not return $this, but maybe the created object (OrderLine in this case), AND if the the created object inherits from the original object (Customer) or contains a back reference to it, skippable() can be defined as a method of the created OrderLine and still return the original Customer for the next call to with(), but now, just suppose the OrderLine also needs another optional method like skippable() : how will this one obtain the OrderLine object ? This introduces limitations that seem unexpected initially.

Of course, in any case, methods could store additional information in the original object so methods like skippable() could fetch the OrderLine info from the Customer object, but this means that the class decoupling has been removed: methods for OrderLine now need knowledge about Customer, which they shouldn’t be needing in the first place (law of Demeter ?).

Or maybe I missed something ?

> It is perhaps simplest to always return $this, however any object
> handle can be returned.

looking at the zend framework, i note that there are places in the controller package, which return $this, so i have to think that is why you have done this, in regards to fluent interfaces?