Posts with "PHP"

SOLID - The D is for Dependency Inversion Principle

Wed, 02 Jan 2013 10:35:43 +0100

The fifth principle of the five SOLID principles is the Dependency Inversion Principle (DIP). You might expect an article on the ISP first, but I feel the internet is filled with enough posts about SOLID. This one was already finished so I'll publish it nonetheless :)

The DIP deals with avoiding mixing different levels of abstraction in your code. In this article we will explore the last of these principles in depth.

As for the previous four, Robert C. Martin took the time to summarize the Dependency Inversion Principle for us:

1. High level modules should not depend upon low level modules. Both should depend upon abstractions.

2. Abstractions should not depend upon details. Details should depend upon abstractions.

Let's look at an example to clarify this:

function storeBike()
{
    $Bike = getBikeInformationFromPostRequest();
    writeBikeToMySQLi($Bike);
}

function getBikeInformationFromPostRequest()
{
    //parse $_POST and return a Bike object
}

function writeBikeToMySQLi(Bike $Bike)
{
    //store $Bike in a new MySQLi record
}

Of course this code is extremely trivial but we have managed to create a two line function (storeBike) with an algorithm that is absolutely not reusable. Why is it not reusable? Because a high level action (store a Bike) depends upon two low level actions: parse a request into bike information and save bike information to MySQL.

If you want to read from something else than $_POST or save to something else than MySQL you have to rewrite the algorithm. Although our algorithm is small and trivial it would be 100% reusable in other cases if the code was refactored to this:

interface BikeReader
{
    public function read();
}

interface BikeWriter()
{
    public function write(Bike $Bike);
}

function storeBike(BikeReader $Reader, BikeWriter $Writer)
{
    $Bike = $Reader->read();
    $Writer->write($Bike);
}

The new code works becuase the high level store function now only depends on abstractions. The same function could be used for reading bikes from a file and write them to output as long as the used BikeReader and BikeWriter implement the interfaces.

A more tangible example

I want to show you how depending on abstractions makes our lives easier in a larger example. Since we're going to be loading, updating and storing bikes a lot in our application I would like an Api for that. It would not be such a good idea to write the same queries or perform the same validation over and over.

In the following example there are two interfaces, one for bike and one for a repository. These are the abstractions details can depend on. Of course we need a detail as well, this will be our Api. This Api is where the logic is! Validation, logging, event triggering, you name it. This is what desperately needs to be tested in every application out there!

Lets have a look at our first interface:

interface Bike
{
    /**
     * @return int
     */
    public function getId();

    /**
     * @return string 
     */
    public function getName();

    /**
     * @param int $id
     */
    public function setId($id);

    /**
     * @param string $name
     */
    public function setName($name)

}

The second interface we need is for a class that is able to perform CRUD-like operations on bikes, a repository:

interface BikeRepository
{
    /**
     * @return int 
     */
    public function create();

    /**
     * @param int $bikeId
     * @return Bike
     */
    public function retrieve($bikeId)

    /**
     * @param Bike $Bike
     * @return bool
     */
    public function update(Bike $Bike);

    /**
     * @param Bike $Bike
     * @return bool
     */
    public function delete(Bike $Bike);
}

Now that we have defined our abstractions we can have a look at our detail. Again, this is where the logic is! For readability I only show a possible update function:

class BikeApi
{
    private $Repository;

    public function __construct(BikeRepository $Repository)
    {
        $this->Repository = $Repository;
    }

    /**
     * @param Bike $Bike
     * @return bool
     */
    public function update(Bike $Bike)
    {
        $name = $Bike->getName();
        $id = $Bike->getId();

        if (empty($name) || empty($id)) {
            return false;
        }

        if ( ! $this->BikeRepository->update($Bike) ) {
            return false;
        }
        
        return true;
    }
}

What did we gain?

Now why did we go to all that trouble of defining interfaces and injecting objects into our BikeApi?

It allows us to change implementation details of one detail without affecting another detail.

The repository that is used by the Bike Api can store the Bike data however it wants to. The business logic is completely detached from the implementation detail of our data storage. Changing the way we store data is a relatively small problem that has no effect outside repositories. As long as the new solution implements the existing interface we even know for sure that our application will keep working (tests remember!).

Confusion with dependency injection

Dependency inversion is often confused with dependency injection. While they touch similar grounds they are not the same. Dependency inversion is described in the two rules at the very start of this article. Dependency injection is a means to an end.

We enable dependency inversion by injecting the Repository into the constructor instead of calling new SomeImplementationOfRepository() inside the Api. With the "new call" we tie the Api to a specific implementation, with the typehinted constructor injection we don't.

This brings a second advantage. Since the repository is injected and the interface is type hinted we can replace it with a mock object based on that interface in our tests. This allows us to test the business logic in complete seperation of the rest of the system, which is all we really want to. You can see how easy testing the Api in isolation of the repository is in the two sample tests for the Api below:

class BikeApiTest
{
    public function testUpdate_whenBikeNameIsNotSet_shouldReturnFalse()
    {
        $RepositoryStub = $this
            ->getMockBuilder('BikeRepository')
            ->getMock();
        
        $BikeStub = $this
            ->getMockBuilder('Bike')
            ->getMock();
        $BikeStub
            ->expects($this->any())  
            ->method('getName')
            ->will($this->returnValue(false));

        $BikeApi = new BikeApi($RepositoryStub);
        $result = $BikeApi->update($BikeStub);

        $this->assertFalse($result); 
    }

    public function testUpdate_whenBikeRepositoryUpdateFails_shouldReturnFalse()
    {
        $RepositoryStub = $this
            ->getMockBuilder('BikeRepository')
            ->getMock();
        $RepositoryStub = $this
            ->expects($this->any())
            ->method('update')
            ->will($this->returnValue(false));
        
        // Make sure the update does not return false to early by setting up a
        // Bike that does return values for name and id.
        $BikeStub = $this
            ->getMockBuilder('Bike')
            ->getMock();
        $BikeStub
            ->expects($this->any())  
            ->method('getName')
            ->will($this->returnValue('name'));
        $BikeStub
            ->expects($this->any())  
            ->method('getId')
            ->will($this->returnValue('id'));

        $BikeApi = new BikeApi($RepositoryStub);
        $result = $BikeApi->update($BikeStub);

        $this->assertFalse($result); 
    }
}

Conclusion

By separating details from other details and writing software that only knows about other parts through interfaces we can create software that enables us to change implementation of parts without breaking or changing other parts. As an added bonus, this decoupling of parts allows us to unit test our code. Don't be afraid of code that others might find java-esque if it makes refactoring easier and your test suite larger!

Tags: SOLID, architecture, OOP, PHP

SOLID - The L is for Liskov Substitution Principle

Tue, 04 Sep 2012 09:01:50 +0200

Between a holiday in the states, buying and redecorating a house and a summer it has been a long time since my last blog entry. It seems about time for a new one :) Today we'll be dealing with the third principle of SOLID, the Liskov Substitution Principle.

The Liskov Substitution Principle (LSP) was coined by Barbara Liskov as early as 1987. The principle is very tightly connected to the earlier discussed Open Closed Principle. A good way of adhering to the OCP is understanding and implementing code that uses the Liskov Substitution Principle. In this article we will discover why and how.

Barbara Liskov described the Liskov Substitution Principle as follows in 1988:

What is wanted here is something like the following substitution property: If for each object O1 of type S there is an object O2 of type T such that for all programs P deﬁned in terms of T, the behavior of P is unchanged when O1 is substituted for O2 then S is a subtype of T

Wow.

That's a mouthfull, so lets replace the letters with something more understandable (Note: Raleigh is a UK-base bike manufacturer).

RaleighBike is a subtype of Bike if: "for each object of type RaleigBike there is an object of type Bike and a program that is defined in terms of Bikes does not change its behaviour when Bikes are substituted with RaleighBikes".

Still a mouthfull. This is how Robert C. Martin summarized it:

Functions that use pointers or references to base classes must be able to use Objects of derived classes without knowing it.

Finally something that is understandable. And if you've read the previous article on the Open Closed Principle, it should sound somewhat familiar. If you read back the article than the quote above is almost what we accomplished with our code to output the current stock of a bike:

foreach ($bikes as $Bike) {
    $API = BikeAPIFactory::getBikeAPI($Bike);
    echo $API->getCurrentStock();
}

If you haven't read the OCP article, here is a small recap for you. To avoid numerous switch statements to different kind of API calls for different brands of bikes, we decided to give each bike brand its own API that had exactly the same function signatures as the others. In the end a factory is used to decide which API should be used for a specific bike object.

But we have to deal with the trustworthyness of our API's. We expect them to all implement getCurrentStock, but no one is telling them. If the API's are a little like me, they might not implement that method untill they're told to ;) Also we have no common base to reference to (think type hinting in function signatures for instance).

Design against abstractions

API's are just like us humans, if we don't impose some rules, there will be hell to pay. So lets come up with some rules. We can do this by defining an interface or abstract class. Since the Bike API's all have in common that they receive a Bike and store it in their constructor, I feel it would make sense to make an abstract class out of it, but lets show both:

interface BikeAPI
{
    public function __construct(Bike $Bike);

    public function getCurrentStock();
}

abstract class BikeAPI
{
    private $Bike;

    public function __construct(Bike $Bike)
    {
        $this->Bike = $Bike;
    }

    abstract public function getCurrentStock();
}

Our API's can now either extend the abstract class or implement the interface (choose one though!), in both cases we have ensured that each of our API methods is present and has the same input parameters.

It seems like we are well on our way of adhering to the Liskov Substution Principle. After all, no code using a RaleighBikeApi object needs to know that it is dealing with a RaleighBikeApi as long as the RaleighBikeApi is a subclass of our parent BikeApi. Right?

Wrong!

The signatures of the BikeAPI methods are set now, so the input will not change. There is no way to create an API that does not take a Bike in its constructor for instance.

But what about return values? There are no rules for return values in the interface nor in the abstract class. We could add some comments with return value hints, but they would be exactly that: hints.

Design by contract

When reading up on the LSP you will soon come accross Bertrand Meyer's name and the term Design by contract. This is a programming methodology that defines contracts to ensure (amongst others) a classes's:

input and return variables
preconditions
postconditions

You can see where this touches the LSP. A subclass that changes the return variable for instance, can not be used in algorithm as if it was its parent. If we expect the getCurrentStock to return an array with info and one subclass starts returning a CurrentStock object (with stock for multiple warehouses for instance) we are in trouble. We solved this problem for input variables, but we can not force our API's to do the same for output variables. This means we need to have conventions in our development team.

This convention would be the LSP. A subclass may not change input our output, it must not change pre- or postconditions and it should leave the state of invariants as they are. This is something programmers will have to start doing, there is no syntax (at least not in PHP) to enforce it, but it is very important when you want to write code that adheres to the Open Closed Principle.

Some rulebreaking

Let's look at a small example where the LSP is violated to see what kind of problems it will cause. Gazelle (a dutch bike manufacturer) has started offering a new service. They don't return the total stock for all their warehouses anymore, instead they return the individual stock per warehouse, so customers can estimate delivery times. If a programmer notices this and wants to use this in a single location we are starting to get into trouble. If he starts refactoring to incorporate the new information in the return value without paying attention to the fact that he is violating the LSP, the code will start to fail on us:

class GazelleAPI extends BikeAPI
{
    public function getCurrentStock()
    {
        //parse response for stock per warehouse location
        return array(
            'dutchWarehouse' => $dutchWarehouse,
            'germanWarehouse' => $germanWarehouse,
        );
    }
}

When running (hopefully) the unit test suite before committing this change, the developer will soon notice that his change is going to cause trouble. All Api calls should return the same kind of information. At a minimum they must all return arrays but it would probably be for the better if the returned some sort of stock object. Right now, unit tests fail and users get presented with the word array instead of the actual stock.

Conclusion

Validating the LSP automatically is not that easy in PHP. There are languages built around the Design by contract paradigm (Eiffel by Bertrand Meyer for one), but PHP is not. There is a PEAR project that adds functionality for design by contract though.

However I feel something else is more important. Robert C. Martin writes in his article:

A model, viewed in isolation, can not be meaningfully validated. The validity of a model can only be expressed in terms of its clients.

And that is exactly it. It might seem perfectly valid to change the output of a function, certainly in cases that are less obvious than the one above. But if you don't look at the system, the software using the component you just changed, all kind of problems may arise. By now it must be clear that adhering to the Open Closed Principle is impossible without the Liskov Substitution Principle.

Tags: PHP, SOLID, architecture, OOP