Methodologies, Techniques and Tools

In this chapter I want to introduce the methodologies, techniques and tools incorporated in this book. None of these are exclusive to PHP and therefore they are worth learning about regardless of which language you’re developing in. Also, none of these are brand new to PHP - in fact any serious PHP development company will be using at least some, if not all of these already. While some of these are new and have been developed in recent years, many of them have been developed over the last one, two or more decades.

As in the previous chapter, I don’t want to go into any real depth with any of these topics. I just want to give a short introduction or primer on each subject. This should provide enough of an understanding to work through this book, but as always, I do encourage you dig deeper into each of the subjects yourself. I will provide references for each topic of good places to start looking when you want to learn more.

Object Oriented Programming (OOP)

Sometimes I think there is a misconception that if you use classes in your code then you are doing OOP. This is not the case. OOP is an approach to modelling which involves grouping your business model down into objects, then grouping the related data and behaviours (methods) of these objects in your code as classes. This style of programming can even be done in languages which have no concepts of classes, and classes can be used ways which really don’t represent good OO code.

This is not a book on OO design but we will be using it extensively. I will be explaining my choices for doing the things I do and as a result, if you’re coming in cold to the subject you will probably get a good feel for OOP from this book alone. Even so I think this is a subject which you should study in more detail. If you do already have some experience of OOP, but you’re not an expert, then I hope you will really have a lot to gain from this book.

Before moving on I just want to quickly cover a couple of OO topics:

Encapsulation

Objects consist of state (their properties) and a public interface (all public methods and properties). Generally there are rules as to what are the valid values for any object’s state. Encapsulation is making state private so that it can only be changed via the public interface’s methods.

The point I want to make here is: that you should design your public methods so that there is no way that the object can be put into an invalid state.

Let’s look at a couple of examples:

Example 1

An object to represent an email address should not be able to contain a value which could not be a valid email address. In this case it would make sense to throw an exception if the email address provided does not look like a valid email address:

 1 <?php
 2 
 3 class EmailAddress
 4 {
 5     /** @var string */
 6     private $address;
 7 
 8     /** @param string $address */
 9     public function __construct($address)
10     {
11         if (strpos($address, '@') === false) {
12             throw new InvalidArgumentException(
13                 'Email addresses must contain an @ symbol'
14             );
15         }
16 
17         $this->address = $address;
18     }
19 
20     public function __toString()
21     {
22         return $this->address;
23     }
24 }

In the example above we chose the simple rule that “anything with an @ symbol in it could be an email address”. Obviously in production code this would need to be more well defined.

If you study the code above you will find that there is no way that you can create an instance of EmailAddress with an email address which does not contain an @ symbol. This is good design!

Example 2

Now consider implementing a collection of words which maintains a count of how many words it contains. This collection class will have 2 properties: the list of words and the count. In order to add words to the collection we must add the word to the list and increment the count. First let’s try this with 2 separate methods:

 1 <?php
 2 
 3 class WordCollection
 4 {
 5     /** @var string[] */
 6     private $words = [];
 7 
 8     /** @var int */
 9     private $count = 0;
10 
11     /** @param string $word */
12     public function addWord($word)
13     {
14         $this->words[] = $word;
15     }
16 
17     public function incrementCounter()
18     {
19         $this->count++;
20     }
21 
22     /** @return string[] */
23     public getWords()
24     {
25         return $this->words;
26     }
27 
28     /** @return int */
29     public getNumberOfWords()
30     {
31         return $this->count;
32     }
33 }

Now you can probably see what’s wrong with that straight away, but let me explain for completeness. Take the following code:

1 <?php
2 
3 $collection = new WordCollection();
4 
5 $collection->addWord('hello');
6 $collection->incrementCounter();

It looks OK and $collection is left in a valid state at the end right? But is it always in a valid state? Look again:

 1 <?php
 2 
 3 $collection = new WordCollection();
 4 
 5 // words in list = 0
 6 // counter = 0
 7 
 8 $collection->addWord('hello');
 9 
10 // words in list = 1
11 // counter = 0
12 // Oh dear!
13 
14 $collection->incrementCounter();
15 
16 // words in list = 1
17 // counter = 1

There’s a point in the middle where the state of the object is invalid, we do fix it in the next line of code but what if a developer forgot to increment the counter? It could lead to a nasty bug!

The solution is simple - design the class so it can never be put into an invalid state:

 1 <?php
 2 
 3 class WordCollection
 4 {
 5     /** @var string[] */
 6     private $words = [];
 7 
 8     /** @var int */
 9     private $count = 0;
10 
11     /** @param string $word */
12     public function addWord($word)
13     {
14         $this->words[] = $word;
15 
16         // increment the counter when the word is added
17         $this->count++;
18     }
19 
20     /** @return string[] */
21     public getWords()
22     {
23         return $this->words;
24     }
25 
26     /** @return int */
27     public getNumberOfWords()
28     {
29         return $this->count;
30     }
31 }

SORTED!

Inheritance vs. Composition

Inheritance is a very useful and powerful tool in OOP but it’s often misused. The most common misuse of inheritance is using it to bring common functionality into 2 unrelated classes.

An example could be:

A bird and an aeroplane both fly, so it might seem reasonable to inherit both a Bird class and an Aeroplane class from a FlyingThing superclass:

 1 <?php
 2 
 3 abstract class FlyingThing
 4 {
 5     public function startFlying()
 6     {
 7         // ...
 8     }
 9 
10     // ...
11 }
12 
13 class Bird extends FlyingThing
14 {
15 }
16 
17 class Aeroplane extends FlyingThing
18 {
19 }

There are a few reasons why this is a problem:

Firstly, we only have single inheritance in PHP which means we can’t extend from more than one super class. Birds can communicate with each other and aeroplanes (well the pilots) can communicate with each other too. If we wanted to add a CommunicatingThing class then we couldn’t inherit from it as well as FlyingThing (without creating a horrible CommunicatingFlyingThing class instead).

Next up, birds start flying by flapping their wings whereas an aeroplane is propelled by its engines. Now we have 2 different types of FlyingThing. The same goes for communicating: birds do it by tweeting and aeroplanes do it by radio.

Finally, we’ve categorised birds and aeroplanes, which are 2 very different things, together as flying things and communicating things - which we’ve had to make up. A much more sensible category for an aeroplane might be a vehicle, and for a bird maybe an animal.

So how to fix it? So far we’ve been talking about is a relationships; a bird is a flying thing. Inheritance is all about is a relationships, but we also have has a relationships. What might be better would be if we said “a bird has a flight system” or “an aeroplane has a communication system”. When talking about has a relationships we are talking about composition. With this in mind Let’s take a look at a better example of how to model this:

 1 <?php
 2 
 3 class FlightSystem
 4 {
 5     public function startFlying()
 6     {
 7         // ...
 8     }
 9 
10     // ...
11 }
12 
13 class CommunicationSystem
14 {
15     /** @param string $message */
16     public function sendMessage($message)
17     {
18         // ...
19     }
20 
21     // ...
22 }
23 
24 class Bird
25 {
26     /** @var FlightSystem */
27     private $flightSystem;
28 
29     /** @var CommunicationSystem */
30     private $communicationSystem;
31 
32     public function __construct()
33     {
34         $this->flightSystem = new FlightSystem();
35         $this->communicationSystem = new CommunicationSystem();
36     }
37 
38     public function startFlying()
39     {
40         $this->flightSystem->startFlying();
41     }
42 
43     /** @param string $message */
44     public function sendMessage($message)
45     {
46         $this->communicationSystem->setMessage($message);
47     }
48 }
49 
50 
51 class Aeroplane
52 {
53     /** @var FlightSystem */
54     private $flightSystem;
55 
56     /** @var CommunicationSystem */
57     private $communicationSystem;
58 
59     public function __construct()
60     {
61         $this->flightSystem = new FlightSystem();
62         $this->communicationSystem = new CommunicationSystem();
63     }
64 
65     public function startFlying()
66     {
67         $this->flightSystem->startFlying();
68     }
69 
70     /** @param string $message */
71     public function sendMessage($message)
72     {
73         $this->communicationSystem->setMessage($message);
74     }
75 }

What’s more, once we start to realise that a bird’s flight system is very different from an aeroplane’s, then we can start having different flight systems which can still be instructed to start flying in the same way by making use of an interface:

 1 interface FlightSystem
 2 {
 3     public function startFlying();
 4 }
 5 
 6 class FlappingFlightSystem implements FlightSystem
 7 {
 8     public function startFlying()
 9     {
10         // ...
11     }
12 }
13 
14 class PropelledFlightSystem implements FlightSystem
15 {
16     public function startFlying()
17     {
18         // ...
19     }
20 }
21 
22 class Bird
23 {
24     // ...
25 
26     public function __construct()
27     {
28         $this->flightSystem = new FlappingFlightSystem();
29         // ...
30     }
31 
32     // ...
33 }
34 
35 class Aeroplane
36 {
37     // ...
38 
39     public function __construct()
40     {
41         $this->flightSystem = new PropelledFlightSystem();
42         // ...
43     }
44 
45     // ...
46 }

The general rule here is: determine if you are really modelling an is a relationship or a has a relationship. Don’t bend your model to fit your code, rather make your code fit the model. When done properly you should find you actually use inheritance pretty rarely.

Design Patterns

Design Patterns are tried and tested solutions to various problems programmers often face. There’s several common design patterns which are very well known, these are called things like the visitor pattern and the strategy pattern.

The de facto resource on this subject is the book titled Design Patterns: Elements of Reusable Object-Oriented Software by the Gang of Four[^the-gang-of-four]. Robert C. Martin says this book is “probably the most important book in software engineering which has been written in the last 30 years”. This book is definitely a must read for all programmers. However, you can also find all the common design patterns listed and explained on Wikipedia.

If you’d prefer to learn about Design Patterns from a PHP point of view then Brandon Savage has written a book on the subject called Practical Design Patterns in PHP.

I’m not going to go into any more details on design patterns here, I just wanted you to know what they are for now. As we work though this book we will be using various design patterns, and as they come up I shall point out which one we are using and explain the choice to do so.

Value Objects & Immutability

When we say something is immutable we mean that its value is fixed and can not be changed. This means a class is either mutable or immutable depending on whether its public interface contains methods which change its internal state. Let’s see an example of each:

 1 <?php
 2 
 3 class MutableEmailAddress
 4 {
 5     /** @var string */
 6     private $address;
 7 
 8     /** @var string */
 9     public function __construct($address)
10     {
11         $this->address = $address;
12     }
13 
14     /** @var string */
15     public function setAddress($address)
16     {
17         $this->address = $address;
18     }
19 
20     public function __toString()
21     {
22         return $this->address;
23     }
24 }

 1 <?php
 2 
 3 class ImmutableEmailAddress
 4 {
 5     /** @var string */
 6     private $address;
 7 
 8     /** @var string */
 9     public function __construct($address)
10     {
11         $this->address = $address;
12     }
13 
14     public function __toString()
15     {
16         return $this->address;
17     }
18 }

We call immutable classes value objects. This is because an instance of a given class represents a value and only that value. In the same way that we can say 5 will always be 5, we can say that an ImmutableEmailAddress object containing the email address bill@microsoft.com will always contain the email address bill@microsoft.com - therefore this object represents the value of that email address.

Value objects are used to make the type of things explicit and should be used to classify anything which can be classified:

An Example

Instead of using a float for temperate use a Temperature value object - even if it simply contains a single float value. You might however also want to store the unit (Fahrenheit or Celsius) in the Temperature object - a value object can contain more than 1 scalar value. Also, the unit of temperature is classifiable itself, therefore make that a value object too.

Your value objects should only be able to be created with valid values, we don’t want anyone to be able to create a temperature of “30 degrees hotness“. This should be enforced in the class definition!

For completeness, let’s look a good implementation of what we’ve just discussed:

 1 <?php
 2 
 3 class TemperatureUnit
 4 {
 5     const CELSIUS    = 'c';
 6     const FAHRENHEIT = 'f';
 7 
 8     /** @var string */
 9     private $value;
10 
11     /** @param string $value */
12     public function __construct($value)
13     {
14         $this->assertValueIsValid($value);
15 
16         $this->value = $value;
17     }
18 
19     /** @return string */
20     public function getValue()
21     {
22         return $this->value;
23     }
24 
25     private function assertValueIsValid($value)
26     {
27         if (!in_array($value, [self::CELSIUS, self::FAHRENHEIT])) {
28             throw new InvalidArgumentException(
29                 'A temperature unit must be celsius or fahrenheit'
30             );
31         }
32     }
33 }
34 
35 class Temperature
36 {
37     /** @var float */
38     private $degrees;
39 
40     /** @var TemperatureUnit */
41     private $unit;
42 
43     /** @param float $degrees */
44     public function __construct($degrees, TemperatureUnit $unit)
45     {
46         $this->degrees = $degrees;
47         $this->unit    = $unit;
48     }
49 
50     /** @return float */
51     public function getDegrees()
52     {
53         return $this->degrees;
54     }
55 
56     /** @return TemperatureUnit */
57     public function getUnit()
58     {
59         return $this->unit;
60     }
61 }

The benefits

There are several benefits to using value objects:

Confidence

With a value object you know that it can’t change unexpectedly. Using our MutableEmailAddress class from earlier consider the following code:

 1 <?php
 2 
 3 function sendEmail(MutableEmailAddress $address)
 4 {
 5     mail($address->getValue(), 'Hello', '...');
 6     $address->setValue('steve@apple.com');
 7 }
 8 
 9 function logEmailSent(MutableEmailAddress $address)
10 {
11     echo "A message was sent to " . $address->getValue();
12 }
13 
14 $address = new MutableEmailAddress('bill@microsoft.com');
15 
16 sendEmail($address);    // send email to bill@microsoft.com
17 logEmailSent($address); // but logs "A message was sent to steve@apple.com"

Looking at just the last 3 lines of code in the example, you would expect the message would get sent to Bill and the log message would reflect that, but it doesn’t!

If we had used an ImmutableEmailAddress object instead then the $address->setValue('steve@apple.com'); line of code would not have been allowed and would have caused an error. Therefore, we could be certain that our last 3 lines of code would work as expected.

Consistency

If we create a function that takes a Temperature as an argument we can be sure that the value we get is a valid Temperature. We don’t need to write any defensive code to check that the unit is valid or that degrees are specified as a floating point value, because all that has been taken care of in the class definitions of our value objects.

Documentation

When you open a file and look at the code, it’s much easier to know the type of a parameter that was typehinted in the method argument list. This is really a benefit of typehints rather than of value objects. However, by using value objects abundantly you will have more types to typehint for.

Entities

Entities make up an important part of the business model of most applications. Unlike value objects they are mutable. They are also the objects which are often persisted and make up the ongoing state of the application.

Entities have identities. They can have all their properties changed but they continue to maintain the same identity through out their lifetime. A simple analogy of an entity object is a person, they can change their name but they are still the same person. This means that the equality of entities determined by the equality of their identities - unlike value objects the equality of their other properties are not important when determining equality.

Here’s a simple example of what a simple entity class make look like:

 1 <?php
 2 
 3 class Customer
 4 {
 5     /** @var CustomerId */
 6     private $id;
 7 
 8     /** @var PersonName */
 9     private $name;
10 
11     /** @var EmailAddress */
12     private $email;
13 
14     public function __construct(
15         CustomerId $id,
16         PersonName $name,
17         EmailAddress $email
18     ) {
19         $this->id    = $id;
20         $this->name  = $name;
21         $this->email = $email;
22     }
23 
24     public function changeName(PersonName $newName)
25     {
26         $this->name = $newName;
27     }
28 
29     public function changeEmail(EmailAddress $newAddress)
30     {
31         $this->email = $newAddress;
32     }
33 
34     /** @return CustomerId */
35     public function getId()
36     {
37         return $this->id;
38     }
39 
40     /** @return Name */
41     public function getName()
42     {
43         return $this->name;
44     }
45 
46     /** @return EmailAddress */
47     public function getEmail()
48     {
49         return $this->email;
50     }
51 }

Dependency Injection (DI) & Inversion of Control (IoC)

Dependency Injection is simply explained by saying: if you have a class that relies on another class, rather than letting it create that other class internally, inject the dependency into it.

Example without dependency injection:

 1 <?php
 2 
 3 class Foo
 4 {
 5     public function doFoo()
 6     {
 7         // ...
 8     }
 9 }
10 
11 class Bar
12 {
13     /** @var Foo */
14     private $fooer;
15 
16     public function __construct()
17     {
18         /*
19          * Bar is in control of creating a Foo.
20          *
21          * As a result bar can only ever use a Foo and never a subtype of
22          * Foo.
23          *
24          * This is known as "tight coupling" because Bar can not exist without
25          * Foo
26          */
27         $this->fooer = new Foo();
28     }
29 
30     public function doBar()
31     {
32         $this->fooer->doFoo();
33     }
34 }

Example with dependency injection:

 1 <?php
 2 
 3 class Foo
 4 {
 5     public function doFoo()
 6     {
 7         // ...
 8     }
 9 }
10 
11 class Bar
12 {
13     /** @var Foo */
14     private $fooer;
15 
16     /**
17      * The Foo must be injected into the instances of Bar.
18      *
19      * It is also possible to inject a subtype of Foo.
20      */
21     public function __construct(Foo $fooer)
22     {
23         $this->fooer = $fooer
24     }
25 
26     public function doBar()
27     {
28         $this->fooer->doFoo();
29     }
30 }

That’s it, Dependency Injection is as easy as that, but why do it?

Substituting Behaviour

By injecting dependencies you’re promoting the development of flexible and reusable code. Since you can not only can you inject the dependent type but also any subtype. This makes it possible to extend your code without actually modifying it - by simply injecting a different subtype of a dependency.

Example

Take this simple email address printer:

 1 <?php
 2 
 3 class EmailAddress
 4 {
 5     /** @var string */
 6     private $address;
 7 
 8     /** @param string $address */
 9     public function __construct($address)
10     {
11         $this->address = (string) $address;
12     }
13 
14     public function __toString()
15     {
16         return $this->address;
17     }
18 }
19 
20 interface EmailAddressRenderer
21 {
22     /** @return string */
23     public function render(EmailAddress $email);
24 }
25 
26 class PlainTextRenderer implements EmailAddressRenderer
27 {
28     public function render(EmailAddress $email)
29     {
30         return (string) $email;
31     }
32 }
33 
34 class EmailAddressPrinter
35 {
36     /** @var EmailAddressRenderer */
37     private $renderer;
38 
39     public function __construct(EmailAddressRenderer $renderer)
40     {
41         $this->renderer = $renderer;
42     }
43 
44     public function printAddress(EmailAddress $address)
45     {
46         echo $this->renderer->render($address) . "\n";
47     }
48 }

To use our class we’d simply write something like this:

1 <?php
2 
3 $address = new EmailAddress('bill@microsoft.com');
4 
5 $printer = new EmailAddressPrinter(new PlainTextRenderer());
6 
7 $printer->printAddress($address);

This works great! But then we’re told we need to print out the email address on a web page as a mailto link. Since we’ve injected our EmailAddressRenderer into the printer rather than letting the printer create it, we can now inject anything which implements the EmailAddressRenderer interface.

Let’s add a HTMLRenderer:

1 <?php
2 
3 class HTMLRenderer implements EmailAddressRenderer
4 {
5     public function render(EmailAddress $email)
6     {
7         return sprintf('<a href="mailto:%1$s">%1$s</a>', htmlentities($email));
8     }
9 }

Our code to make use of this would now look like this:

1 <?php
2 
3 $address = new EmailAddress('bill@microsoft.com');
4 
5 $printer = new EmailAddressPrinter(new HTMLRenderer());
6 
7 $printer->printAddress($address);

Simples! Notice how in order to change the way it behaves we have not altered the original code in any way, instead we’ve simply extended it. Here we’ve written our code in such a way that even though the printer uses a renderer, it does not have control over how that renderer is created. Instead it is uses the one given. This is known as inversion of control.

Inversion Of Control

We’ve just seen an example of inversion of control so we know what it is. But again, what is it useful for?

Well…

• Using it creates extensible code.
• It removes the need for your business model to know about implementation details such as: how things are displayed or how messages are sent. Instead, it allows those details to be plugged in; this is often done using the Adapter design pattern.
• It allows your code to be easily tested as small, independent units. This is possible through the use of test doubles.

Testing

Each class in your codebase may depend on on other classes, each of which may then depend on even more classes. As your codebase grows, testing anything becomes quite hard as you need create all the dependencies of the class you are trying to test. Also, each of these dependencies will have their own dependencies which will need to be created as well. In this situation tests get very complex and also fragile; if you were to change anything then lots of your tests could break, and it could take a long time to get them passing again.

By using dependency injection, inversion of control and interfaces, you get code which doesn’t depend on fixed dependencies but rather on abstractions (the interface) of the dependency. When your code is written like this your dependencies are considered to be loosely coupled.

When your dependencies are loosely coupled you can create test doubles. These are very simple and predictable versions of a class’s dependencies. These can be injected into the class instead of the real dependencies, allowing the class to be tested in isolation. We’ll look at this in more detail in the next chapter.

Dependency Injection Containers (DIC) & Service Managers

These are tools which can manage the creation of objects and ensure that the required dependencies get injected into them on creation. I’m not going to talk about these here but will cover them in more detail when we need to use one.

All I will add now is that there are many DIC and Service Manager libraries available should you ever decide you need one.

The SOLID Principles

The SOLID Principles are the first 5 principles from a list compiled by Robert C. Martin of Principles of Object Oriented Design. These 5 principles are:

Single Responsibility Principle (SRP)

A class should only have a single responsibility - don’t create classes which do a lot of different things.

Open Closed Principle (OCP)

Your application should be open for extension but closed for modification. We saw an example of this in action in the Dependency Injection section.

Liskov Substitution Principle (LSP)

This states objects can be replaced by subtypes of themselves and the program should still work. What this means is: when you extend a class you should make sure its public interface still behaves in the expected way, making it possible to use the class in place of its parent anywhere in the program.

Interface Segregation Principle (ISP)

This principle states that if something has a dependency but only uses a subset of that dependency’s public interface, then that subset should be made into a separate interface. The new interface then becomes the dependency.

Dependency Inversion Principle (DIP)

Classes should not depend on other concrete classes, but rather on abstractions (i.e. abstract classes and interfaces). Again, we looked at this earlier on in the email printer example.

More in-depth details can be found on Robert Martin’s article: Principles of OOD.

If you stick to these principles you will create fantastically modular, extensible and testable code.

Functional Programming (FP)

History

PHP is naturally heavily biased towards the imperative programming paradigm. Imperative programs are basically sequences of statements which are executed in order, changing the program state they run. The imperative style of programming has been the most popular style for several decades now.

There are however other paradigms, one of which is functional programming. Functional Programming pre-dates Imperative Programming, but Imperative Programming still won the popularity race up until recently. Once it stopped being possible for computer CPUs to get any faster, the manufacturers decided to start adding more cores instead. So rather than trying to have a single thread of instructions executing faster and faster, we have multiple threads executing simultaneously.

The imperative style of programming is very well suited towards single threads of execution because statements always run in the correct order. With multiple threads however, one thread might run faster than another, and if they are both trying to read and change the same state then there’s no guarantee that it will happen in the right order. To make this work using imperative programming you need to introduces locks to keep track of and synchronise how the threads are interacting with the shared state. This is tricky and is not fun to do!

The functional style of programming, makes this a lot simpler. You can tell the computer to execute 2 different functions in 2 different threads and be sure that they will behave as expected, and not conflict with each other. For this reason, functional programming and functional programming languages are gaining a lot of popularity at the moment. Also, many imperative languages are adding more and more functional style features.

So What is Functional Programming?

Functional programming has its roots in lambda calculus, and is based on the idea that whenever you call a given function with the same set of arguments, you will always get the same result. Some other aspects of functional programming are:

• Functions have no side effects - they never modify or read global/persistent state. These are considered pure functions.
• There is no assignment - once a variable has been initialised with a value it will always be that value.
• Functions can accept other functions as arguments and return new functions. These are known as higher order functions.

I’m not going to go much deeper into functional programming in this book, I only really want to show what pure functions are. I will be applying some functional programming knowledge during the building of our application but I’m not going to highlight it too much.

Pure Functions

As previously mentioned, pure functions are functions which have no side effects. Let’s look at some examples of pure functions:

All these functions will always return the same value when given the same arguments. And they never alter persistent state:

 1 <?php
 2 function add($a, $b)
 3 {
 4     return $a + $b;
 5 }
 6 
 7 function fahrenheitToCelsius($fahrenheit)
 8 {
 9     return ($fahrenheit - 32) / 1.8;
10 }
11 
12 function applyTwiceAndAdd(callable $fn, $value)
13 {
14     return $fn($value) + $fn($value);
15 }

The following functions are not pure. If called twice with the same arguments the result may not be the same:

 1 <?php
 2 $counter = 0;
 3 
 4 function incrementCounter()
 5 {
 6     global $counter;
 7 
 8     $counter++;
 9 }
10 
11 function getCount()
12 {
13     global $counter;
14 
15     return $counter;
16 }
17 
18 function getCountAndIncrement()
19 {
20     global $counter;
21 
22     return $counter++;
23 }
24 
25 function threeTimesRand($max)
26 {
27     return 3 * rand(0, $max);
28 }
29 
30 function readFile($filename)
31 {
32     return file_get_contents($filename);
33 }

Now some functional programming languages do not have assignment statements to allow the changing of the value of a variable - but PHP does! It is possible to make use of this inside a function, while still providing a functionally pure interface to it:

 1 <?php
 2 
 3 function applyNTimesAndAdd(callable $fn, $n, $value)
 4 {
 5     $total = 0;
 6 
 7     for ($count = 0; $count < $n; $count++) {
 8         $total += $fn($value);
 9     }
10 
11     return $total;
12 }

While applyNTimesAndAdd does have internal state, it is never persisted beyond each execution of the function. Therefore, this can still be considered a pure function - even though the implementation uses imperative code.

Now lets move this theory inside objects. Obviously we can have methods which are pure functions:

 1 <?php
 2 
 3 class RandomFunctions
 4 {
 5     public function add($a, $b)
 6     {
 7         return $a + $b;
 8     }
 9 
10     public function fahrenheitToCelsius($fahrenheit)
11     {
12         return ($fahrenheit - 32) / 1.8;
13     }
14 
15     public function applyTwiceAndAdd(callable $fn, $value)
16     {
17         return $fn($value) + $fn($value);
18     }
19 }

Of course this hasn’t really achieved much other than grouping some functions together.

However, as soon as methods start to make use of properties, they can no longer be considered as pure functions. This is because the properties persist beyond method calls:

 1 <?php
 2 
 3 class Counter
 4 {
 5     private $counter = 0;
 6 
 7     public function incrementCounter()
 8     {
 9         $this->counter++;
10     }
11 
12     public function getCount()
13     {
14         return $this->counter;
15     }
16 
17     public function getCountAndIncrement()
18     {
19         return $this->counter++;
20     }
21 }

Since the behaviour of the methods in the Counter class now depends on the $counter property, none of the methods in the class could be considered pure.

Now thinking back to the applyNTimesAndAdd function, can we do something similar in the context of an object? Take a look at this example and consider whether you think it behaves in a functional way:

 1 <?php
 2 
 3 class ResultAdder
 4 {
 5     private $fn;
 6 
 7     private $total;
 8 
 9     private $value;
10 
11     public function applyNTimesAndAdd(callable $fn, $n, $value)
12     {
13         $this->fn = $fn
14         $this->total = 0;
15         $this->value $value;
16         
17         for ($count = 0; $count < $n; $count++) {
18             $this->applyFunction();
19         }
20 
21         return $this->total;
22     }
23 
24     private function applyFunction()
25     {
26         $fn = $this->fn;
27 
28         $fn($this->value);
29     }
30 }

What do you think? If you study it carefully you will notice that: even though properties are being used inside the class, every time a method in the public interface is invoked, the properties are being reset. This means that the applyNTimesAndAdd method does indeed appear to be working in a functional way.

Classes like this one are often created by the use of the Replace Method with Method Object refactoring.

Learn More About FP

Learning a functional programming language is not only fascinating, but it also gives you a whole new set of tools which you can apply in any language. Also, as we’re get more and more cores in our computers, it’s going to become increasingly important over the next few years! So, if you’re not already familiar with functional programming I really recommend taking a look at it in the not so distant future - it will be a very rewarding experience!

There are many resources on functional programming which can be easily found. Two notable ones are:

Structure and Interpretation of Computer Programs (SICP)

This is one of the most recommended text books covering functional programming. It was written by MIT professors Harold Abelson & Gerald Jay Sussman with Julie Sussman, and was formerly used there as a text book. It can also be read for free online.

Functional Programming in PHP

This is a much easier book to read, written by Simon Holywell. It introduces functional programming to PHP programmers, along with some useful functional libraries which are available for PHP.

Command Query Separation (CQS)

Command Query Separation is more or what the name implies:

Methods are classified as either commands or a queries (but not both). A command is a method which changes the state of the object. Whereas, a query is a method which returns a value from the object. Also, a command must not return a value, and a query must not change the object’s state.

Let’s take another quick look at the Counter class we made earlier:

 1 <?php
 2 
 3 class Counter
 4 {
 5     /** @var int */
 6     private $counter = 0;
 7 
 8     /**
 9      * This method is a COMMAND since it updates the state
10      * and doesn't return a value.
11      */
12     public function incrementCounter()
13     {
14         $this->counter++;
15     }
16 
17     /**
18      * This method is a QUERY since it returns a value
19      * but does not alter the object's state.
20      *
21      * @return int
22      */
23     public function getCount()
24     {
25         return $this->counter;
26     }
27 
28     /**
29      * This method alerts the state and returns a value so it
30      * is not a separate COMMAND or QUERY.
31      *
32      * Such methods should be avoided.
33      *
34      * @return int
35      */
36     public function getCountAndIncrement()
37     {
38         return $this->counter++;
39     }
40 }

CQS means we can repeatedly query our object (to make assertions, display, or what ever other reason), while being confident that we are not inadvertently making changes to its state in the process. Generally, with the objects inside your model this is a good approach to try to adhere to.

What might seem an exception to this rule is, methods working in a functional way. However, since the state they modify is not used again, it does not actually break this rule.

Naming

When writing code, you have to decide on the names of many things. These include variables, classes and methods. Choosing the names of these carefully, makes the difference between code which is easily understandable, and which is completely indecipherable.

When choosing names, make them descriptive, so that the intent of your code is clear. If your code is well written and the names are chosen well, there should be no need for any comments in your code. Robert C. Martin goes as far as saying that choosing to adding a comment to your code, is accepting that you have failed as a programmer to solve the problem clearly. That does sound a bit harsh, but the underlying message is that your code should be self descriptive. It’s OK to use comments when something cannot be made clear in code, but those situations should be very, very rare!

One very simple rule for naming is: use nouns for variable and class names and use verbs for method names. It’s not quite as black and white as that, but it’s a very good place to start.

For some more interesting talk on naming I thoroughly recommend having a read of Mathias Verraes’ blog.

Make Method Names Describe Intent

When creating methods, make the intent of the method’s purpose clear in terms of the business language.

Say for example: a customer moves house and needs to have their address updated in the system. What might seem like an obvious approach would be to add a setAddress method to the Customer class. This works but it’s not as informative as it could be. A better method name might be ‘moveHouse’.

So far so good, but what if the customer’s address was entered into the system incorrectly and it just needs to be amended? Does it make sense to call moveHouse to update it? Of course not! So we add a amendPostalAddress method also:

 1 <?php
 2 
 3 class Customer
 4 {
 5     /** @var string */
 6     private $name;
 7 
 8     /** @var EmailAddress */
 9     private $emailAddress;
10 
11     /** @var PostalAddress */
12     private $postalAddress;
13 
14     /** @param string $name */
15     public function __construct(
16         $name,
17         EmailAddress $emailAddress
18         PostalAddress $postalAddress
19     ) {
20         $this->name          = $name;
21         $this->emailAddress  = $emailAddress;
22         $this->postalAddress = $postalAddress;
23     }
24 
25     public function moveHouse(PostalAddress $newAddress)
26     {
27         $this->postalAddress = $newAddress;
28     }
29 
30     public function amendPostalAddress(PostalAddress $amendedAddress)
31     {
32         $this->postalAddress = $amendedAddress;
33     }
34 
35     /** @return string */
36     public function getName()
37     {
38         return $this->name;
39     }
40 
41     /** @return EmailAddress */
42     public function getEmailAddress()
43     {
44         return $this->emailAddress;
45     }
46 }

This is definitely more descriptive, but it’s essentially 2 methods which do the same thing - surely there’s no point in that you might think. But there is! The 2 action are actually 2 separate tasks, by separating them we make it very clear to anyone reading the code that there are 2 different events which result in the change of a customer’s address data. This also makes it possible to easily extend the system: say, for example, we are told that emails should be sent to the customer when their address changes:

• When they move house, we need to send them an email congratulating them on moving into a new home.
• When amending the address, we just want to notify them that their details have been updated.

Because we’ve separated the 2 actions, this is very easy to add on. For this example let’s use the Decorator pattern¹:

 1 <?php
 2 
 3 class NotifyingCustomerDecorator extends Customer
 4 {
 5     /** @var Customer */
 6     private $customer;
 7 
 8     /** @var Mailer */
 9     private $mailer;
10 
11     public function __construct(Customer $customer, Mailer $mailer)
12     {
13         $this->customer = $customer;
14         $this->mailer   = $mailer;
15     }
16 
17     public function moveHouse(PostalAddress $newAddress)
18     {
19         $this->customer->moveHouse($newAddress);
20 
21         $this->mailer->send(
22             $this->customer,
23             'Congratulations on moving into your new house!',
24             '...'
25         );
26     }
27 
28     public function amendPostalAddress(PostalAddress $newAddress)
29     {
30         $this->customer->amendPostalAddress($newAddress);
31 
32         $this->mailer->send(
33             $this->customer,
34             'We have updated your details on our system',
35             '...'
36         );
37     }
38 
39     /** @return string */
40     public function getName()
41     {
42         return $this->customer->getName();
43     }
44 
45     /** @return EmailAddress */
46     public function getEmailAddress()
47     {
48         return $this->customer->getEmailAddress();
49     }
50 }

Pretty neat huh? Once again we have easily extended the system to add new functionality, without modifying the existing code. Therefore, we are obeying the Open Closed Principle.

Refactoring

Refactoring is the process of restructuring your code without changing its external behaviour. The purpose of refactoring is to try to make the code easier to understand, manage and extend. As programmers, we should be refactoring all the time while we write our code.

While you can get quite a long way refactoring your code by just using common sense, all the common refactorings have been named and catalogued. To learn more about refactoring I don’t think there’s any better recommendation than to read Martin Fowler’s book titled Refactoring.

Also, much like with design patterns, lots of information can be found about the different refactorings online. In fact, Martin Fowler also has website called http://refactoring.com/ which has a catalogue of refactorings on it.

As I write this book I’ll be refactoring all the example code as I go. Sadly you’ll often not get to see this process as the book will just contain the finished, refactored result. That said you will see the code evolve throughout the book as functionality is added, and that will include some refactoring. I’ll also cover it a bit more in the next chapter.

Object Calisthenics

Object Calisthenics is an idea suggested by Jeff Bay in The ThoughtWorks Anthology book. It consists of 9 rules to help write better Object Oriented code.

These rules are:

Only One Level Of Indentation Per Method

Code with multiple indents gets tricky to read and follow. Also, there’s a greater chance of having to scroll the page to the right which is a nuisance. This can be avoided by extracting methods and using guard clauses.

Don’t Use The ELSE Keyword

There are some cases where else can be useful, but more often than not you can find a neater way. This again, produces code which is easier to read.

Wrap All Primitives And Strings

This pretty much means: use value objects instead of scalar types in PHP. As I’ve already said, this is particularly useful in PHP when combined with typehinting. Always question the use of a scalar property in a domain object.

First Class Collections

Rather than having arrays properties in your classes, create a collection object. Quite often there are actions which you want to apply across a collection, these actions really belong as part of the collection rather than the containing class. Doing this also makes collections reusable.

One Dot Per Line

In PHP this should really be Two Arrows Per Line since we use -> instead of ., and the $this-> must be used inside methods to access things in class scope. What this rule actually means is - don’t call methods on objects returned from other methods - creating a chain of method calls like so: $this->getX()->doY()->doZ(). This rule ties in very tightly with the Law of Demeter.

Don’t Abbreviate

Use descriptive names for everything, so other people (or yourself in 6 months time) reading the code can clearly understand its intent. This ties in with the previous Naming section.

Keep All Entities Small

Simply put - don’t let your classes get to long. If they are starting to get big then there are probably more classes inside which can be extracted out.

No Classes With More Than Two Instance Variables

Nice idea but a bit extreme in my opinion! Still it’s worth keeping in mind as if you’re adding lots of properties to your classes, then are probably some composite types hiding in there which should be extracted.

No Getters/Setters/Properties

The idea here is to tell the class to perform an action and let it get on with it; rather than getting values out, changing them and setting them again - often referred to as tell, don’t ask. Sometimes a getter or setter is needed, but always try your best to find a better way.

I can’t say I stick to all of these rules 100% of the time. But, by trying to follow them as much as possible, you will write much cleaner and more manageable, Object Oriented code.

For more details on these rules take a look at William Durand’s blog post titled Object Calisthenics.

Also, Guilherme Blanco’s slides on the subject are worth a look if you want to see the rules applied in PHP.

Automated Testing

Automated tests are simply tests which can be run to confirm the logic in your program is behaving as expected.

Automated test can be:

• Test code which executes and verifies the code being tested.
• Scripts written in a test language, which executes and verifies the code via a testing framework.
• Code which automates interaction with the user interface or API.
• Scripts written in a test language, which automate interaction with the user interface or API via a testing framework.

There are different types of test. These are categorised depending on what they are testing. For example you have:

Tests provide confidence in your codebase, and confidence in the ability to add to and modify the code. Also, when refactoring, tests let you know that you haven’t made a mistake and broken the logic. When adding new or modifying existing functionality, tests give you confidence that you haven’t broken a different feature in the process.

Tests are great! You should have them! One often cited argument for not writing tests, is the extra time is takes to write them. What people who say this don’t know about, is all the debugging time it saves. Also, if you use TDD then the process of creating the tests is not separate from the writing of the code, so it’s not an extra task which has to be done.

Test Driven Development (TDD)

I’m going to be very brief here as the next chapter is going to go into it in much more depth.

Simply put, Test Driven Development is a discipline which involves using the tests to guide what production code is actually written - rather than writing the code, then working out how to test it. Through this process, TDD encourages you to write much cleaner and more modular code than you might write without it. It also gives you much higher confidence in the coverage of your test suite.

If you’re new to TDD and want to start learning how to apply it, then the next chapter will get you started. Also, someone really worth checking out is Chris Hartjes aka The Grumpy Programmer - he preaches TDD to PHP programmers, has written a great book called The Grumpy Programmer’s Guide to Building Testable Applications to PHP, and has videos available from http://grumpy-learning.com/

Behaviour Driven Development (BDD)

Behaviour Driven Development is an extension to TDD. It uses testing tools which encourage the language used in the tests to be written in a declarative way - conveying intent from a business perspective. Throughout this book we will be using BDD extensively.

Uncle Bob’s Clean Code

Robert C. Martin, aka Uncle Bob, is a very outspoken and published programmer who has strong ideals about how high quality code should be written. His books include:

• Clean Code: A Handbook of Agile Software Craftsmanship
• The Clean Coder: A Code of Conduct for Professional Programmers
• Agile Software Development, Principles, Patterns, and Practices

He also has a fantastic video series called Clean Code.

Through his books and videos he covers all the topics we’ve looked at in this chapter in a lot more depth. If you really want to improve the way you work he is definitely someone to whom you should be paying attention.

Domain Driven Design (DDD)

Domain Driven Design is much more than how to write code. It includes the full process from understanding the business (domain), to translating that into software. As the name implies, DDD’s driving factor is the domain (the business we are modelling), and the fact that as developers we have to accept that no one understands the domain as much as the domain experts (the people who understand and use the business we are modelling). When doing DDD we do not try to squeeze the domain we are modelling into our software development world’s terms. Rather, we aim to transfer the domain language into our software’s code.

The first stage of DDD, is sitting down with the domain experts and starting to learn about their domain. During this time, we start to crate a ubiquitous language. This is made up of the words and phrases that we can use to discuss the domain in the domain expert’s terms. This ubiquitous language should then be used in all following discussions, as well as being transferred into the actual source code of the application.

While DDD is about the full process, from analysing and understanding the domain through to actually modelling it, there is a certain style of code and set of design patterns which it makes use of. These include use of value objects, entities, aggregates, the repository pattern and more.

Since DDD has a far broader scope than just the writing of the code, this book doesn’t really cover it in any depth. However, the code produced in this book is heavily influence by this style of design.

If you really want to understand DDD, you want to start off by reading Eric Evans’ book Domain-Driven Design.

Another person to keep an eye on regarding this subject in the PHP community is Mathias Verraes.

Command Query Responsibility Segregation (CQRS)

A lot of the techniques I have talked about have about so far, have been about building a rock solid domain model which cannot be broken by creating objects in invalid states. All these careful checks are very important when state is being changed and manipulated. However, often we just want to view the state. In this circumstance the construction of a complex domain model may be considered unnecessarily computationally expensive. For this reason we could consider a bomb proof domain model to be optimised for change.

Now consider this: most web applications have far more hits where state is just viewed, than they do when state is being updated. Take a basic web shop, you view tens of pages of search results, lists, products and reviews, before adding the product you want to the cart then checking out. Here the adding to the cart and checkout processes are the parts which actually update state, all the browsing actions are read only. We could assume that maybe only 1 in 5 hits change state, and we’ve already established that building a complex model for reading only is overly expensive. This is where CQRS comes in.

Before I explain CQRS let me introduce one more point about application architecture. I’ve already introduced how a robust domain model is the key, central part to an application. However, I’ve not said how it is interacted with. On top of the domain layer you might typically build a layer of application service, use case or transaction classes, which talk to the domain model to perform a specific action.

As an example, you might have a ChangeCustomersEmail transaction which loads up a Customer entity from the storage, changes the email address, then stores it. You might also might have a ListCustomers transaction which returns a list of customers on the system.

Now let’s say the site is getting busy and growing, and it’s getting slower and slower. It needs to scale, but how? Well since it’s running on a domain model which is optimised for changing, and we also know that most hits are read only, it would make sense to make those actions optimised for reading. To do this you could separate out all transactions which are read only, and instead of building a complicated model from a complex data store for them. You could create a thin read layer, which reads it’s information from a version of the data store which is optimised for the required queries. The result of this is you would have some transactions which modify state by talking to the complex domain model and updating the master data store. We call these commands. Then you have another set of transactions, which read from a denormalised version of the data store, to display the information quickly for reading only. We call these queries.

That’s it, CQRS is all about splitting your application in half. One half is optimised for updating, the other for reading. There is more to CQRS regarding scaling across multiple servers, but what we have just talked about is the main gist of it from the software architecture point of view.

In this book we will not be building a full CQRS implementation (maybe that could be the sequel). However, I do feel that it is worthwhile making the distinction between the command and query transactions in our application. My reason for this is, that without the extra effort of building a full CQRS solution, we still make it clear which transactions change state. Should the day come that the application needs to be scaled up in a big way and the decision to implement CQRS is taken, this will make it just that little bit easier.

If you want to learn more about CQRS there’s a few great articles by Greg Young in the documents section of http://cqrs.wordpress.com/

Agile

Agile is an approach to software development which is embodied in methodologies such as Extreme Programming (XP) and SCRUM. It accepts the fact that, getting from the stakeholder’s idea to the final product, is not something that can be set as a rigid path from the beginning. As the project progresses, the stakeholder’s ideas evolve and technical challenges might affect the way the project progresses.

With agile development, the stakeholder is heavily involved with the development process, and the project is broken down into manageable sized tasks. The stakeholder prioritises the tasks, then the development team works in small bursts of time, to get the tasks completed and delivered to the stakeholder - in order of priority. In XP these bursts of time are called iterations, whereas in SCRUM they’re known as sprints. After each iteration/sprint, the stakeholder and development team review what has been done and decide what to tackle next.

Agile is about the approach to work and the idea that things can change as they develop. In this book I won’t be discussing this any further, but I will be presenting the code examples as if we’re working in an Agile environment. What this means is: the code I present in an earlier chapter may well change, be replaced or even be deleted in a later chapter. The reason for this is that I don’t just want to present an application architecture as an end product of the book. Rather, I want to go through the process of how we get to that point.

A great book to check out on Agile style development is Kent Beck’s Extreme Programming Explained.

User Stories

A user story is a short description of one of the tasks that a user will do when interacting with the system:

A customer can view their previous orders.

These are created as part of the planning and analysis process. They are often written on small cards called story cards. Acceptance tests are then decided on for a story, then that feature can be implemented.

One thing to note is that a story is not a specification! It’s intentionally vague and it’s purpose is to exist as a request for conversation. When it is time to implement a story, the team (which includes the stakeholder) should discuss the story and decide on the details - this will result in the generation of the acceptance tests. For the purpose of this book, I’ll provide the story and tests as though this conversation has already taken place, I’ll do this for each part of the application we implement.

Creating user stories is not something I will be covering. For this I really recommend Mike Cohn’s rather fantastic book on the subject: User Stories Applied.