• Embedded Entities
• Related Documents
• List of Keys
• Relationship Documents

See the presentation for more details. This topic is also covered in the MapReduce Views for SQL Users chapter in the second edition of Writing and Querying MapReduce Views in CouchDB.

1. Support for multiple types of clients
2. Reduce duplicate code when supporting multiple types of clients
3. Isolating domain logic from the user interface

Note that items 2 and 3 are both dependent on item 1. Support for multiple types of clients is the single driving force behind the MVC design pattern. Following are some examples of client types:

• Web Browsers
• API Clients
• Admin Processes (e.g. CLI, cron, daemon)
• Unit Tests
• Native GUI

Realistically, how many of these different client types do you need to support? If you’re taking a RESTful approach, then Web Browsers and API Clients can be combined into one type of client, which we can just call User Agents. Likely you’re not building a Native GUI. This leaves you with the following three types of clients to support:

• User Agents
• Admin Processes
• Unit Tests

Do you really need to use the MVC design pattern in order to support User Agents, Admin Processes, and Unit Tests? Likely not. That’s not to say that there aren’t benefits to isolating domain logic from the user interface. However, if you don’t need to support multiple types of clients you should really question your use of the MVC design pattern. There are many approaches one can take to separating the domain logic and the user interface, of which MVC is just one.

This bring me to The MVC Paradox. Modern MVC web frameworks inadvertently encourage the coupling of domain logic and user interface. If you don’t need to support multiple types of clients, then decoupling the domain logic from the user interface is the only reason left to use the MVC design pattern.

Modern MVC web frameworks often involve a lot of boilerplate code just to support the primary client type of User Agents. This boilerplate code typically does little to help with supporting the other client types of Admin Processes and Unit Tests. As a result of the overhead introduced by this extra boilerplate code, developers often find themselves creating Fat Controllers (a side-effect of The MVC Paradox). Controllers take on too many responsibilities, both vertically and horizontally. Vertically, Controllers start to handle domain logic that should be pushed down to the Model layer. Horizontally, multiple concerns get stuffed into a handful of Controllers. These different horizontal concerns should be separated out into multiple Controllers (the Single Responsibility Principle). The overhead introduced by modern MVC web frameworks leads directly to these problems.

In contrast, take a look at the Slim PHP 5 micro framework. While not a completely RESTful framework, it does a pretty good job of addressing the concerns I’ve laid out in this post. Here is the “Hello world” example from Slim’s homepage:

<?php
require 'Slim/Slim.php';
$app = new Slim();
$app->get('/hello/:name', function ($name) {
    echo "Hello, $name!";
});
$app->run();
?>

There is very little boilerplate code involved in handling a User Agent’s request. Minting and handling new routes is incredibly simple. Placing your entire front-end application layer in one file may seem absurd at first. However, it has the nice side-effect of making it painfully obvious if you start to handle domain logic outside of your Model layer or if one route is doing too many things. If your front-end application is large enough, then you can organize your routes into separate files.

This post is not intended to discourage you from using an MVC web framework. There are certainly times when such a framework is useful. As with any technology decision, carefully consider what problem you’re trying to solve and what technology will best address your problem set. Sometimes your technology choice can undermine the very purpose of using that technology in the first place, as is the case with The MVC Paradox.

5. CouchDB and Domain-Driven Design

This post covered two topics that are of great interest to me. Document databases like CouchDB have much potential when it comes to domain-driven design. The post outlined some techniques for serializing domain objects into CouchDB documents.

4. Addressing the NoSQL Criticism

I heard a lot of NoSQL bashing this year at OSCON. As a result, I decided to write a rebuttal to many of the criticisms that I heard. This post inspired a lively comment thread.

3. Testing PHP 5.4

This was a short post on how to help the PHP Quality Assurance Team by running the tests for the latest development version of PHP 5.4. It covered downloading, compiling, and running the tests. Most importantly, it also covered reporting your test results.

2. Exploring RabbitMQ and PHP

I was exploring the possibility of using RabbitMQ for an upcoming project. I decided to post some notes on my experience getting started with RabbitMQ and integrating it with PHP. I haven’t ended up using RabbitMQ in production yet, but I’m confident that I’ll end up using it at some point.

1. CouchDB jQuery Plugin Reference

I had been frustrated by the lack of documentation for the CouchDB jQuery plugin—so decided to write my own. After I wrote the blog post, Max Ogden pointed me to Dale Harvey‘s documentation generator for jquery.couch.js and a copy of the generated jQuery CouchDB documentation. Max and Dale are also working on a more flexible jquery.couch2.js.

I. Codebase

“One codebase tracked in revision control, many deploys”

There’s really not much here that would be different in PHP versus any other language. Who isn’t using some form of revision control these days?

II. Dependencies

“Explicitly declare and isolate dependencies”

There are a few tools available to PHP developers to help manage dependencies. The PEAR package manager may help here, but has its flaws. Pyrus, the PEAR2 package manager, looks promising. There’s also Composer. I’ve heard of people using their operating system’s package manager (e.g. RPM) to deploy their PHP applications and manage dependencies. I’m not sure if there any tools in PHP to enforce dependency isolation.

III. Config

“Store config in the environment”

The simplest option here is to use environment variables. Many frameworks, including Zend Framework, allow you to have environment-specific configuration such as development, test, and production. This is not recommended for twelve-factor apps as it doesn’t scale as new environments are added.

IV. Backing Services

“Treat backing services as attached resources”

There’s not really anything to say here that’s specific to PHP.

V. Build, release, run

“Strictly separate build and run stages”

Phing or the more general-purpose Ant could work here. Even though it’s not written in PHP, there’s no reason why you couldn’t use Capistrano for this. I don’t think the run stage typically applies to PHP, as it happens implicitly as part of the release stage. However, there are tasks such as flushing the APC cache (if apc.stat=0) that might be considered part of the run stage.

VI. Processes

“Execute the app as one or more stateless processes”

PHP processes are already stateless and shared-nothing. This makes PHP a great fit for twelve-factor apps. Memory space or the filesystem should be used as a short-lived, single-process cache. If you’re using an asset manager, such as Assetic, then any assets should be compiled and cached during the build stage.

VII. Port binding

“Export services via port binding”

I don’t think port binding applies to PHP applications—at least not in the way it’s meant in twelve-factor. PHP relies on a web server and uses something like FastCGI or PHP-FPM to communicate with the web server. PHP 5.4 will have its own built-in web server, but this is intended for development use only. It’s really the combination of PHP and its web server that will be bound to a port. This brings up challenges when it comes to dependency management, as the web server itself is now a dependency.

VIII. Concurrency

“Scale out via the process model”

I’m not sure how processes would become first-class citizens in a PHP web application. However, each individual request/response cycle is handled by its own process. In that regard, PHP already uses the process model.

IX. Disposability

“Maximize robustness with fast startup and graceful shutdown”

PHP processes are very disposable. Again, this is just part of how PHP works.

X. Dev/prod parity

“Keep development, staging, and production as similar as possible”

Nothing specific to PHP here. Although, it’s not uncommon for PHP developers to use SQLite in development and MySQL or PostgreSQL in production. This is not recommended for a twelve-factor app—use the same software and versions of backing services in all environments.

XI. Logs

“Treat logs as event streams”

There are tons of logging options in PHP. Zend_Log_Writer_Stream lets you send log data to a PHP stream. Alternatively, StatsD and the PHP StatsD library look pretty good.

XII. Admin processes

“Run admin/management tasks as one-off processes”

This is easy enough in PHP. If you want an interactive shell with readline history, tab completion, and quick access to documentation then check out phpsh.

If you were in this session, please give me feedback on Joind.in.

Aggregates are groupings of associated Entities and Value Objects. Within an Aggregate, one member is designated as the Aggregate Root. External references are limited to only the Aggregate Root. Aggregates should follow transaction, distribution, and concurrency boundaries. Guess what else is defined by transaction, distribution, and concurrency boundaries? That’s right, JSON documents in CouchDB.

Let’s take a look at an example Aggregate, that representing a blog entry and related metadata. Note that the following UML diagrams are for classes in PHP, but it should be easy enough to translate these examples to any object-oriented programming language. We’ll start with the Entry Entity, which will serve as our Aggregate Root:

-----------------------------------------
|                 Entry                 |
-----------------------------------------
|+ id : string                          |
|+ rev : string                         |
|+ title : Text                         |
|+ updated : Date                       |
|+ authors : Person[*]                  |
|+ content : Text                       |
-----------------------------------------
|+ __construct(entry : array) : void    |
|+ toArray() : array                    |
-----------------------------------------

The Text Value Object:

----------------------------------------------
|                    Text                    |
----------------------------------------------
|- type : string                             |
|- text : string                             |
----------------------------------------------
|+ __construct(type : string, text : string) |
|+ toArray() : array                         |
----------------------------------------------

The Date Value Object:

--------------------------------------
|                Date                |
--------------------------------------
|- timestamp : integer               |
--------------------------------------
|+ __construct(timestamp : integer)  |
|+ __toString() : string             |
--------------------------------------

The Person Value Object:

-------------------------------------------------------------
|                           Person                          |
-------------------------------------------------------------
|- name : string                                            |
|- uri : string                                             |
|- email : string                                           |
-------------------------------------------------------------
|+ __construct(name : string, uri : string, email : string) |
|+ toArray() : array                                        |
-------------------------------------------------------------

I recommend serializing each Aggregate, starting with the Aggregate Root, into a JSON document. Control access to Aggregate Roots through a Repository. The toArray() methods above return an associative array representation of each object. The Repository can then transform the array into JSON for storage in CouchDB. Let’s take a look at the EntryRepository:

---------------------------------
|        EntryRepository        |
---------------------------------
|                               |
---------------------------------
|+ get(id : string) : Entry     |
|+ post(entry : Entry) : void   |
|+ put(entry : Entry) : void    |
|+ delete(entry : Entry) : void |
---------------------------------

Here’s an example of what the Aggregate’s object graph might look like, serialized as a JSON document:

{
    "_id": "http://bradley-holt.com/?p=1251",
    "title": {
        "type": "text",
        "text": "CouchDB and Domain-Driven Design"
    },
    "updated": "2011-08-02T15:30:00+00:00",
    "authors": [
        {
             "name": "Bradley Holt",
             "uri": "http://bradley-holt.com/",
             "email": "bradley.holt@foundline.com"
        }
    ],
    "content": {
        "type": "html",
        "text": "<p>I've found CouchDB to be a great fit for…</p>"
    }
}

You can also provide access to CouchDB views through Repositories. In the above example, this could be through the addition of an index(skip : integer, limit : integer) : Entry[*] method to the the EntryRepository (note that this is a naive pagination implementation, especially on large data sets—but that’s beyond the scope of this blog post). For more complex views, you may want to create a separate Repository for each CouchDB view.

Putting the Model To Work

Domain-Driven Design is a set of three guiding principles:

• Focus on the Core Domain as that is where the complexity is. Technology plays a supporting role, use it as needed.
• Explore the Model in a collaborative process involving both Domain Experts and software practitioners.
• Speak a Ubiquitous Language within an explicitly Bounded Context.

I should point out that the word “Model” has many different meanings in software development. Within Domain-Driven Design a Model is a “system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain.” Those familiar with the Model–View–Controller (MVC) pattern should note that the word “Model” within the MVC pattern has a different meaning than “Model” within Domain-Driven Design. Within Domain-Driven Design a Model is a conceptual tool used to understand a Domain. An example that was used in the class was the game of baseball. A Model of the baseball Domain would include concepts such as strikes, balls, and outs. The classes and objects representing these concepts would not be the Model.

You might be wondering what the difference is between the Domain and the Model. The goal with Domain-Driven Design is not to create a Model of reality. Even if you could come up with some objective view of reality this would not be very useful. Instead, we are trying to understand (and perhaps develop) the Models that Domain Experts already use to understand the Domain. It’s important to note that Models are only useful for a particular purpose. What are you trying to do with this Model? Trying to use a Model designed for a different purpose will lead to a less than optimal outcome.

The Model Exploration Whirlpool might be a useful reference if you’re looking for concrete guidance on how to explore Models, especially in an Agile or Lean setting.

Building Blocks

Group Entities and Value Objects into Aggregates. Entities are objects defined by a thread of continuity and identity. Their only responsibilities should be around identity and life cycle. Within a customer relationship management (CRM) system a person would likely be an Entity. Note that context matters: a person in another context may be a Value Object. A Value Object “is an object that describes some characteristic or attribute but carries no concept of identity.” Using the CRM example again, a phone number might be a Value Object. Again, context matters: if you’re a telephone company then a phone number may very well be an Entity. Treat Value Objects as immutable. Delegate business logic to Value Objects, identity and life cycle are plenty of responsibility for Entities. Grouping these Entities and Value Objects into Aggregates is useful when defining transaction, distribution, and concurrency boundaries.

An interesting topic covered in the class that I don’t believe was in the book was the idea of Domain Events. A Domain Event is something important that happens within the Domain that may lead to a state change in a domain object. Instead of keeping track of the current state of an Entity, you can instead compute this state from the currently known Domain Events. Using a baseball analogy again, a Domain Event might be a strike. Domain Events can trigger other Domain Events: three strikes triggers an out. The current state of the game can be computed from all of the Domain Events.

Supple Design

Since this has been a topic of conversation here on my blog and on Twitter, I plan on writing another blog post on why Value Objects need to be immutable. However, I want to point out here that if you think you need to change the state of a Value Object then instead have a method on that Value Object that returns another instance of the same type with the new state. If your method takes any arguments then have these arguments be of the same type as the Value Object. This concept is called “closure of operations” and is covered in Chapter 10 of the book, Supple Design.

While I won’t go into the details here, there are several other useful patterns in creating supple designs including intention-revealing interfaces, side-effect-free functions, and assertions. Note that “supple” is not the same as “flexible”. A flexible design can be easily modified, but a supple design is a design that fits comfortably with the Domain.

Strategic Design

Strategic Design involves managing the interactions between Bounded Contexts. In my understanding, strategic design is most applicable in large teams or groups of teams. It starts by drawing a Context Map of the actual current Bounded Contexts, not what you want the Bounded Contexts to be. Some patterns to describe these relationships include Partnership, Shared Kernel, Big Ball of Mud, Customer/Supplier, Conformist, Anticorruption Layer, Separate Ways, Open Host Service, and Published Language. The details of these patterns can be found in the book.

Distillation

There are always multiple Models. Some of these Models my represent your Core Domain. Others may represent a Supporting Domain or a Generic Subdomain. Work with business leaders to create a Domain Vision Statement so that you can identify which is which. One good question to ask a Domain Expert at the outset of a project to get at the Core Domain is, “What keeps you awake at night?” Other questions to ask include:

• “What makes your system worth writing?”
• “Why not buy it off the shelf?”
• “Why not outsource it?”

Once you’ve identified your Core Domain this is where you should focus your modeling efforts. Put your best available internal developers and modelers on the Core Domain and make sure that the Core Domain is isolated in a clean, Bounded Context.

Summary

Don’t settle on not having access to a Domain Expert. Domain-Driven Design is a creative collaboration between Domain Experts and software developers. Cultivate strong relationships with Domain Experts, focus on the Ubiquitous Language, listen for clues in conversations, and be open to shifts in assumptions that destroy your understanding of the Model—this is where breakthroughs come from!

If you’re interested in learning more:

• Watch Eric Evan’s Putting the Model to Work and Strategic Design presentations (note that slides are provided below the videos).
• Read the Domain-Driven Design book.
• Attend a Domain Language class.

Modern object-oriented programming languages need support for immutable Value Objects. #DDD

The “DDD” in that tweet stands for Domain-Driven Design. There were several interesting responses to this tweet. Kevin Schroeder thought that it made a lot of sense but pointed out that “need” was a bit of a strong word. I should have instead said that this would be a “useful” feature. Matthew Weier O’Phinney shared an example of making an immutable object in PHP. Ralph Schindler suggested throwing an exception so as not to silently reject an attempt to modify the object’s state. Nicolas Bérard-Nault had a similar suggestion of implementing PHP’s __set magic method and throwing an exception so that new public attributes cannot be assigned and also not making any methods that change the state of the object. Giorgio Sironi suggested that PHP’s “private” keyword was all you needed to support immutable Value Objects.

The above suggestions are all useful when implementing immutable Value Objects in PHP. I would also add that you need to make the class “final” to truly guarantee that it’s immutable. This is so that someone can’t extend the class and add (or override) methods that change state (although I suppose if you made the __set method final and had it throw an exception that should do the trick since you wouldn’t be able to change any properties).

Regardless, all of these attempts to guarantee immutability miss the point. I don’t need to make sure the class is immutable when its defined, I need to know in my client code that it’s immutable. In other words, I need a contract that says the object is immutable. None of the above workarounds give you an explicit contract that the object is immutable. Hopefully you’re working on a team where you trust that if a teammate tells you that something is an immutable Value Object, it is immutable. In fact, I wouldn’t normally bother doing any of the above tricks to absolutely guarantee that the object is immutable. This is because you still can’t tell by looking at the object that it is immutable without inspecting its implementation. A built-in language feature would be useful because it would provide an explicit contract that the object is immutable.

I have a lot of experience building web applications that separate business logic from presentation and have been using Zend Framework’s model–view–controller (MVC) components for over two years now. This has certainly helped make web applications I work on more maintainable. However, creating effective models (the “M” in “MVC”) has always been difficult (this has nothing to do with Zend Framework and has everything to do with the difficulty of modeling in general). The Zend Framework team has been relatively quiet on models since modeling tends to be specific to your application’s domain (although Matthew Weier O’Phinney recently gave a great webcast and presentation on modeling in Zend Framework).

The Domain-Driven Design book has helped make a lot of things “click” for me. It drives home the point that modeling is a domain-specific task and that the complexity is usually in the domain, not the technical aspects of your project. If you think the complexity is in the technology then you should question your choice of tools (in my opinion) but in this case perhaps domain-driven design isn’t right for you. The book provides many patterns that help keep the focus on the domain. Arguably the most important of these patterns is the Ubiquitous Language which is “a language structured around the domain model and used by all team members to connect all the activities of the team with the software.” Other important patterns include Entities, Value Objects, Services, Repositories and Factories.

If effective modeling has been something that you’ve struggled with then I’d urge you to check out Eric Evans’ presentations and then read his Domain-Driven Design book.

Reuse is extremely important but difficult to achieve. You don’t get it for free, but it is achievable.

The lure of object-oriented programming is the ability to reuse code. However, creating reusable code is not as simple as switching from procedural to object-oriented programming. One may make the switch from procedural to object-oriented programming and then be disappointed that object-oriented programming didn’t deliver on the promise of reuse. Josh Bloch has a potential solution to this problem but it requires one to think about software in terms of public APIs.

Being disappointed with object-oriented programming, one may then decide to try agile programming, perhaps even extreme programming. One tenant of extreme programming is to “do the simplest thing that could possible work.” Josh Bloch points out that this is easy to misconstrue:

The extreme programming proponents don’t advocate writing something that will barely work as fast as you can. They don’t advise you to forgo any design. They do advocate leaving out the bells, whistles, and features you don’t need and add them later, if a real need is demonstrated. And that’s incredibly important, because you can always add a feature, but you can never take it out. Once a feature is there, you can’t say, sorry, we screwed up, we want to take it out because other code now depends on it. People will scream. So, when in doubt, leave it out.

He goes on to talk about other topics such as minimizing mutability, protected vs. private members, when to make a class final, and the copy constructor as a cloning mechanism. It is interesting reading if you are striving for the goal of reusable object-oriented code.