Proper Repository Pattern Design in PHP?

I thought I'd take a crack at answering my own question. What follows is just one way of solving the issues 1-3 in my original question.

Disclaimer: I may not always use the right terms when describing patterns or techniques. Sorry for that.

The Goals:

• Create a complete example of a basic controller for viewing and editing Users.
• All code must be fully testable and mockable.
• The controller should have no idea where the data is stored (meaning it can be changed).
• Example to show a SQL implementation (most common).
• For maximum performance, controllers should only receive the data they need—no extra fields.
• Implementation should leverage some type of data mapper for ease of development.
• Implementation should have the ability to perform complex data lookups.

The Solution

I'm splitting my persistent storage (database) interaction into two categories: R (Read) and CUD (Create, Update, Delete). My experience has been that reads are really what causes an application to slow down. And while data manipulation (CUD) is actually slower, it happens much less frequently, and is therefore much less of a concern.

CUD (Create, Update, Delete) is easy. This will involve working with actual models, which are then passed to my Repositories for persistence. Note, my repositories will still provide a Read method, but simply for object creation, not display. More on that later.

R (Read) is not so easy. No models here, just value objects. Use arrays if you prefer. These objects may represent a single model or a blend of many models, anything really. These are not very interesting on their own, but how they are generated is. I'm using what I'm calling Query Objects.

The Code:

User Model

Let's start simple with our basic user model. Note that there is no ORM extending or database stuff at all. Just pure model glory. Add your getters, setters, validation, whatever.

class User{    public $id;    public $first_name;    public $last_name;    public $gender;    public $email;    public $password;}

Repository Interface

Before I create my user repository, I want to create my repository interface. This will define the "contract" that repositories must follow in order to be used by my controller. Remember, my controller will not know where the data is actually stored.

Note that my repositories will only every contain these three methods. The save() method is responsible for both creating and updating users, simply depending on whether or not the user object has an id set.

interface UserRepositoryInterface{    public function find($id);    public function save(User $user);    public function remove(User $user);}

SQL Repository Implementation

Now to create my implementation of the interface. As mentioned, my example was going to be with an SQL database. Note the use of a data mapper to prevent having to write repetitive SQL queries.

class SQLUserRepository implements UserRepositoryInterface{    protected $db;    public function __construct(Database $db)    {        $this->db = $db;    }    public function find($id)    {        // Find a record with the id = $id        // from the 'users' table        // and return it as a User object        return $this->db->find($id, 'users', 'User');    }    public function save(User $user)    {        // Insert or update the $user        // in the 'users' table        $this->db->save($user, 'users');    }    public function remove(User $user)    {        // Remove the $user        // from the 'users' table        $this->db->remove($user, 'users');    }}

Query Object Interface

Now with CUD (Create, Update, Delete) taken care of by our repository, we can focus on the R (Read). Query objects are simply an encapsulation of some type of data lookup logic. They are not query builders. By abstracting it like our repository we can change it's implementation and test it easier. An example of a Query Object might be an AllUsersQuery or AllActiveUsersQuery, or even MostCommonUserFirstNames.

You may be thinking "can't I just create methods in my repositories for those queries?" Yes, but here is why I'm not doing this:

• My repositories are meant for working with model objects. In a real world app, why would I ever need to get the password field if I'm looking to list all my users?
• Repositories are often model specific, yet queries often involve more than one model. So what repository do you put your method in?
• This keeps my repositories very simple—not an bloated class of methods.
• All queries are now organized into their own classes.
• Really, at this point, repositories exist simply to abstract my database layer.

For my example I'll create a query object to lookup "AllUsers". Here is the interface:

interface AllUsersQueryInterface{    public function fetch($fields);}

Query Object Implementation

This is where we can use a data mapper again to help speed up development. Notice that I am allowing one tweak to the returned dataset—the fields. This is about as far as I want to go with manipulating the performed query. Remember, my query objects are not query builders. They simply perform a specific query. However, since I know that I'll probably be using this one a lot, in a number of different situations, I'm giving myself the ability to specify the fields. I never want to return fields I don't need!

class AllUsersQuery implements AllUsersQueryInterface{    protected $db;    public function __construct(Database $db)    {        $this->db = $db;    }    public function fetch($fields)    {        return $this->db->select($fields)->from('users')->orderBy('last_name, first_name')->rows();    }}

Before moving on to the controller, I want to show another example to illustrate how powerful this is. Maybe I have a reporting engine and need to create a report for AllOverdueAccounts. This could be tricky with my data mapper, and I may want to write some actual SQL in this situation. No problem, here is what this query object could look like:

class AllOverdueAccountsQuery implements AllOverdueAccountsQueryInterface{    protected $db;    public function __construct(Database $db)    {        $this->db = $db;    }    public function fetch()    {        return $this->db->query($this->sql())->rows();    }    public function sql()    {        return "SELECT...";    }}

This nicely keeps all my logic for this report in one class, and it's easy to test. I can mock it to my hearts content, or even use a different implementation entirely.

The Controller

Now the fun part—bringing all the pieces together. Note that I am using dependency injection. Typically dependencies are injected into the constructor, but I actually prefer to inject them right into my controller methods (routes). This minimizes the controller's object graph, and I actually find it more legible. Note, if you don't like this approach, just use the traditional constructor method.

class UsersController{    public function index(AllUsersQueryInterface $query)    {        // Fetch user data        $users = $query->fetch(['first_name', 'last_name', 'email']);        // Return view        return Response::view('all_users.php', ['users' => $users]);    }    public function add()    {        return Response::view('add_user.php');    }    public function insert(UserRepositoryInterface $repository)    {        // Create new user model        $user = new User;        $user->first_name = $_POST['first_name'];        $user->last_name = $_POST['last_name'];        $user->gender = $_POST['gender'];        $user->email = $_POST['email'];        // Save the new user        $repository->save($user);        // Return the id        return Response::json(['id' => $user->id]);    }    public function view(SpecificUserQueryInterface $query, $id)    {        // Load user data        if (!$user = $query->fetch($id, ['first_name', 'last_name', 'gender', 'email'])) {            return Response::notFound();        }        // Return view        return Response::view('view_user.php', ['user' => $user]);    }    public function edit(SpecificUserQueryInterface $query, $id)    {        // Load user data        if (!$user = $query->fetch($id, ['first_name', 'last_name', 'gender', 'email'])) {            return Response::notFound();        }        // Return view        return Response::view('edit_user.php', ['user' => $user]);    }    public function update(UserRepositoryInterface $repository)    {        // Load user model        if (!$user = $repository->find($id)) {            return Response::notFound();        }        // Update the user        $user->first_name = $_POST['first_name'];        $user->last_name = $_POST['last_name'];        $user->gender = $_POST['gender'];        $user->email = $_POST['email'];        // Save the user        $repository->save($user);        // Return success        return true;    }    public function delete(UserRepositoryInterface $repository)    {        // Load user model        if (!$user = $repository->find($id)) {            return Response::notFound();        }        // Delete the user        $repository->delete($user);        // Return success        return true;    }}

Final Thoughts:

The important things to note here are that when I'm modifying (creating, updating or deleting) entities, I'm working with real model objects, and performing the persistance through my repositories.

However, when I'm displaying (selecting data and sending it to the views) I'm not working with model objects, but rather plain old value objects. I only select the fields I need, and it's designed so I can maximum my data lookup performance.

My repositories stay very clean, and instead this "mess" is organized into my model queries.

I use a data mapper to help with development, as it's just ridiculous to write repetitive SQL for common tasks. However, you absolutely can write SQL where needed (complicated queries, reporting, etc.). And when you do, it's nicely tucked away into a properly named class.

I'd love to hear your take on my approach!

July 2015 Update:

I've been asked in the comments where I ended up with all this. Well, not that far off actually. Truthfully, I still don't really like repositories. I find them overkill for basic lookups (especially if you're already using an ORM), and messy when working with more complicated queries.

I generally work with an ActiveRecord style ORM, so most often I'll just reference those models directly throughout my application. However, in situations where I have more complex queries, I'll use query objects to make these more reusable. I should also note that I always inject my models into my methods, making them easier to mock in my tests.

Based on my experience, here are some answers to your questions:

Q: How do we deal with bringing back fields we don't need?

A: From my experience this really boils down to dealing with complete entities versus ad-hoc queries.

A complete entity is something like a User object. It has properties and methods, etc. It's a first class citizen in your codebase.

An ad-hoc query returns some data, but we don't know anything beyond that. As the data gets passed around the application, it is done so without context. Is it a User? A User with some Order information attached? We don't really know.

I prefer working with full entities.

You are right that you will often bring back data you won't use, but you can address this in various ways:

1. Aggressively cache the entities so you only pay the read price once from the database.
2. Spend more time modeling your entities so they have good distinctions between them. (Consider splitting a large entity into two smaller entities, etc.)
3. Consider having multiple versions of entities. You can have a User for the back end and maybe a UserSmall for AJAX calls. One might have 10 properties and one has 3 properties.

The downsides of working with ad-hoc queries:

1. You end up with essentially the same data across many queries. For example, with a User, you'll end up writing essentially the same select * for many calls. One call will get 8 of 10 fields, one will get 5 of 10, one will get 7 of 10. Why not replace all with one call that gets 10 out of 10? The reason this is bad is that it is murder to re-factor/test/mock.
2. It becomes very hard to reason at a high level about your code over time. Instead of statements like "Why is the User so slow?" you end up tracking down one-off queries and so bug fixes tend to be small and localized.
3. It's really hard to replace the underlying technology. If you store everything in MySQL now and want to move to MongoDB, it's a lot harder to replace 100 ad-hoc calls than it is a handful of entities.

Q: I will have too many methods in my repository.

A: I haven't really seen any way around this other than consolidating calls. The method calls in your repository really map to features in your application. The more features, the more data specific calls. You can push back on features and try to merge similar calls into one.

The complexity at the end of the day has to exist somewhere. With a repository pattern we've pushed it into the repository interface instead of maybe making a bunch of stored procedures.

Sometimes I have to tell myself, "Well it had to give somewhere! There are no silver bullets."

I use the following interfaces:

• Repository - loads, inserts, updates and deletes entities
• Selector - finds entities based on filters, in a repository
• Filter - encapsulates the filtering logic

My Repository is database agnostic; in fact it doesn't specify any persistence; it could be anything: SQL database, xml file, remote service, an alien from outer space etc.For searching capabilities, the Repository constructs an Selector which can be filtered, LIMIT-ed, sorted and counted. In the end, the selector fetches one or more Entities from the persistence.

Here is some sample code:

<?phpinterface Repository{    public function addEntity(Entity $entity);    public function updateEntity(Entity $entity);    public function removeEntity(Entity $entity);    /**     * @return Entity     */    public function loadEntity($entityId);    public function factoryEntitySelector():Selector}interface Selector extends \Countable{    public function count();    /**     * @return Entity[]     */    public function fetchEntities();    /**     * @return Entity     */    public function fetchEntity();    public function limit(...$limit);    public function filter(Filter $filter);    public function orderBy($column, $ascending = true);    public function removeFilter($filterName);}interface Filter{    public function getFilterName();}

Then, one implementation:

class SqlEntityRepository{    ...    public function factoryEntitySelector()    {        return new SqlSelector($this);    }    ...}class SqlSelector implements Selector{    ...    private function adaptFilter(Filter $filter):SqlQueryFilter    {         return (new SqlSelectorFilterAdapter())->adaptFilter($filter);    }    ...}class SqlSelectorFilterAdapter{    public function adaptFilter(Filter $filter):SqlQueryFilter    {        $concreteClass = (new StringRebaser(            'Filter\\', 'SqlQueryFilter\\'))            ->rebase(get_class($filter));        return new $concreteClass($filter);    }}

The ideea is that the generic Selector uses Filter but the implementation SqlSelector uses SqlFilter; the SqlSelectorFilterAdapter adapts a generic Filter to a concrete SqlFilter.

The client code creates Filter objects (that are generic filters) but in the concrete implementation of the selector those filters are transformed in SQL filters.

Other selector implementations, like InMemorySelector, transform from Filter to InMemoryFilter using their specific InMemorySelectorFilterAdapter; so, every selector implementation comes with its own filter adapter.

Using this strategy my client code (in the bussines layer) doesn't care about a specific repository or selector implementation.

/** @var Repository $repository*/$selector = $repository->factoryEntitySelector();$selector->filter(new AttributeEquals('activated', 1))->limit(2)->orderBy('username');$activatedUserCount = $selector->count(); // evaluates to 100, ignores the limit()$activatedUsers = $selector->fetchEntities();

P.S. This is a simplification of my real code