Frameworks provide a tool for rapid application development, but often accrue technical debt as rapidly as they allow you to create functionality. Technical debt is created when maintainability isn't a purposeful focus of the developer. Future changes and debugging become costly, due to a lack of unit testing and structure.
Here's how to begin structuring your code to achieve testability and maintainability – and save you time.
We'll Cover (loosely)
- DRY
- Dependency Injection
- Interfaces
- Containers
- Unit Tests with PHPUnit
Let's begin with some contrived, but typical code. This might be a model class in any given framework.
class User {
public function getCurrentUser()
{
$user_id = $_SESSION['user_id'];
$user = App::db->select('id, username')
->where('id', $user_id)
->limit(1)
->get();
if ( $user->num_results() > 0 )
{
return $user->row();
}
return false;
}
}
This code will work, but needs improvement:
- This isn't testable.
- We're relying on the
$_SESSIONglobal variable. Unit-testing frameworks, such as PHPUnit, rely on the command-line, where$_SESSIONand many other global variables aren't available. - We're relying on the database connection. Ideally, actual database connections should be avoided in a unit-test. Testing is about code, not about data.
- We're relying on the
- This code isn't as maintainable as it could be. For instance, if we change the data source, we'll need to change the database code in every instance of
App::dbused in our application. Also, what about instances where we don't want just the current user's information?
An Attempted Unit Test
Here's an attempt to create a unit test for the above functionality.
class UserModelTest extends PHPUnit_Framework_TestCase {
public function testGetUser()
{
$user = new User();
$currentUser = $user->getCurrentUser();
$this->assertEquals(1, $currentUser->id);
}
}
Let's examine this. First, the test will fail. The $_SESSION variable used in the User object doesn't exist in a unit test, as it runs PHP in the command line.
Second, there's no database connection setup. This means that, in order to make this work, we will need to bootstrap our application in order to get the App object and its db object. We'll also need a working database connection to test against.
To make this unit test work, we would need to:
- Setup a config setup for a CLI (PHPUnit) run in our application
- Rely on a database connection. Doing this means relying on a data source separate from our unit test. What if our test database doesn't have the data we're expecting? What if our database connection is slow?
- Relying on an application being bootstrapped increases the overhead of the tests, slowing the unit tests down dramatically. Ideally, most of our code can be tested independent of the framework being used.
So, let's get down to how we can improve this.
Keep Code DRY
The function retrieving the current user is unnecessary in this simple context. This is a contrived example, but in the spirit of DRY principles, the first optimization I'm choosing to make is to generalize this method.
class User {
public function getUser($user_id)
{
$user = App::db->select('user')
->where('id', $user_id)
->limit(1)
->get();
if ( $user->num_results() > 0 )
{
return $user->row();
}
return false;
}
}
This provides a method we can use across our entire application. We can pass in the current user at the time of the call, rather than passing that functionality off to the model. Code is more modular and maintainable when it doesn't rely on other functionalities (such as the session global variable).
However, this is still not testable and maintainable as it could be. We're still relying on the database connection.
Dependency Injection
Let's help improve the situation by adding some Dependency Injection. Here's what our model might look like, when we pass the database connnection into the class.
class User {
protected $_db;
public function __construct($db_connection)
{
$this->_db = $db_connection;
}
public function getUser($user_id)
{
$user = $this->_db->select('user')
->where('id', $user_id)
->limit(1)
->get();
if ( $user->num_results() > 0 )
{
return $user->row();
}
return false;
}
}
Now, the dependencies of our User model are provided for. Our class no longer assumes a certain database connection, nor relies on any global objects.
At this point, our class is basically testable. We can pass in a data-source of our choice (mostly) and a user id, and test the results of that call. We can also switch out separate database connections (assuming that both implement the same methods for retrieving data). Cool.
Let's look at what a unit test might look like for that.
<?php
use Mockery as m;
use Fideloper\User;
class SecondUserTest extends PHPUnit_Framework_TestCase {
public function testGetCurrentUserMock()
{
$db_connection = $this->_mockDb();
$user = new User( $db_connection );
$result = $user->getUser( 1 );
$expected = new StdClass();
$expected->id = 1;
$expected->username = 'fideloper';
$this->assertEquals( $result->id, $expected->id, 'User ID set correctly' );
$this->assertEquals( $result->username, $expected->username, 'Username set correctly' );
}
protected function _mockDb()
{
// "Mock" (stub) database row result object
$returnResult = new StdClass();
$returnResult->id = 1;
$returnResult->username = 'fideloper';
// Mock database result object
$result = m::mock('DbResult');
$result->shouldReceive('num_results')->once()->andReturn( 1 );
$result->shouldReceive('row')->once()->andReturn( $returnResult );
// Mock database connection object
$db = m::mock('DbConnection');
$db->shouldReceive('select')->once()->andReturn( $db );
$db->shouldReceive('where')->once()->andReturn( $db );
$db->shouldReceive('limit')->once()->andReturn( $db );
$db->shouldReceive('get')->once()->andReturn( $result );
return $db;
}
}
I've added something new to this unit test: Mockery. Mockery lets you "mock" (fake) PHP objects. In this case, we're mocking the database connection. With our mock, we can skip over testing a database connection and simply test our model.
Want to learn more about Mockery?
In this case, we're mocking a SQL connection. We're telling the mock object to expect to have the select, where, limit and get methods called on it. I am returning the Mock, itself, to mirror how the SQL connection object returns itself ($this), thus making its method calls "chainable". Note that, for the get method, I return the database call result – a stdClass object with the user data populated.
This solves a few problems:
- We're testing only our model class. We're not also testing a database connection.
- We're able to control the inputs and outputs of the mock database connection, and, therefore, can reliably test against the result of the database call. I know I'll get a user ID of "1" as a result of the mocked database call.
- We don't need to bootstrap our application or have any configuration or database present to test.
We can still do much better. Here's where it gets interesting.
Interfaces
To improve this further, we could define and implement an interface. Consider the following code.
interface UserRepositoryInterface {
public function getUser($user_id);
}
class MysqlUserRepository implements UserRepositoryInterface {
protected $_db;
public function __construct($db_conn)
{
$this->_db = $db_conn;
}
public function getUser($user_id)
{
$user = $this->_db->select('user')
->where('id', $user_id)
->limit(1)
->get();
if ( $user->num_results() > 0 )
{
return $user->row();
}
return false;
}
}
class User {
protected $userStore;
public function __construct(UserRepositoryInterface $user)
{
$this->userStore = $user;
}
public function getUser($user_id)
{
return $this->userStore->getUser($user_id);
}
}
There's a few things happening here.
- First, we define an interface for our user data source. This defines the
addUser()method. - Next, we implement that interface. In this case, we create a MySQL implementation. We accept a database connection object, and use it to grab a user from the database.
- Lastly, we enforce the use of a class implementing the
UserInterfacein ourUsermodel. This guarantees that the data source will always have agetUser()method available, no matter which data source is used to implementUserInterface.
Note that our
Userobject type-hintsUserInterfacein its constructor. This means that a class implementingUserInterfaceMUST be passed into theUserobject. This is a guarantee we are relying on – we need thegetUsermethod to always be available.
What is the result of this?
- Our code is now fully testable. For the
Userclass, we can easily mock the data source. (Testing the implementations of the datasource would be the job of a separate unit test). - Our code is much more maintainable. We can switch out different data sources without having to change code throughout our application.
- We can create ANY data source. ArrayUser, MongoDbUser, CouchDbUser, MemoryUser, etc.
- We can easily pass any data source to our
Userobject if we need to. If you decide to ditch SQL, you can just create a different implementation (for instance,MongoDbUser) and pass that into yourUsermodel.
We've simplified our unit test, as well!
<?php
use Mockery as m;
use Fideloper\User;
class ThirdUserTest extends PHPUnit_Framework_TestCase {
public function testGetCurrentUserMock()
{
$userRepo = $this->_mockUserRepo();
$user = new User( $userRepo );
$result = $user->getUser( 1 );
$expected = new StdClass();
$expected->id = 1;
$expected->username = 'fideloper';
$this->assertEquals( $result->id, $expected->id, 'User ID set correctly' );
$this->assertEquals( $result->username, $expected->username, 'Username set correctly' );
}
protected function _mockUserRepo()
{
// Mock expected result
$result = new StdClass();
$result->id = 1;
$result->username = 'fideloper';
// Mock any user repository
$userRepo = m::mock('Fideloper\Third\Repository\UserRepositoryInterface');
$userRepo->shouldReceive('getUser')->once()->andReturn( $result );
return $userRepo;
}
}
We've taken the work of mocking a database connection out completely. Instead, we simply mock the data source, and tell it what to do when getUser is called.
But, we can still do better!
Containers
Consider the usage of our current code:
// In some controller
$user = new User( new MysqlUser( App:db->getConnection("mysql") ) );
$user->id = App::session("user->id");
$currentUser = $user->getUser($user_id);
Our final step will be to introduce containers. In the above code, we need to create and use a bunch of objects just to get our current user. This code might be littered across your application. If you need to switch from MySQL to MongoDB, you'll still need to edit every place where the above code appears. That's hardly DRY. Containers can fix this.
A container simply "contains" an object or functionality. It's similar to a registry in your application. We can use a container to automatically instantiate a new User object with all needed dependencies. Below, I use Pimple, a popular container class.
// Somewhere in a configuration file
$container = new Pimple();
$container["user"] = function() {
return new User( new MysqlUser( App:db->getConnection('mysql') ) );
}
// Now, in all of our controllers, we can simply write:
$currentUser = $container['user']->getUser( App::session('user_id') );
I've moved the creation of the User model into one location in the application configuration. As a result:
- We've kept our code DRY. The
Userobject and the data store of choice is defined in one location in our application. - We can switch out our
Usermodel from using MySQL to any other data source in ONE location. This is vastly more maintainable.
Final Thoughts
Over the course of this tutorial, we accomplished the following:
- Kept our code DRY and reusable
- Created maintainable code – We can switch out data sources for our objects in one location for the entire application if needed
- Made our code testable – We can mock objects easily without relying on bootstrapping our application or creating a test database
- Learned about using Dependency Injection and Interfaces, in order to enable creating testable and maintainable code
- Saw how containers can aid in making our application more maintainable
I'm sure you've noticed that we've added much more code in the name of maintainability and testability. A strong argument can be made against this implementation: we're increasing complexity. Indeed, this requires a deeper knowledge of code, both for the main author and for collaborators of a project.
However, the cost of explanation and understanding is far out-weighed by the extra overall decrease in technical debt.
- The code is vastly more maintainable, making changes possible in one location, rather than several.
- Being able to unit test (quickly) will reduce bugs in code by a large margin – especially in long-term or community-driven (open-source) projects.
- Doing the extra-work up front will save time and headache later.
Resources
You may include Mockery and PHPUnit into your application easily using Composer. Add these to your "require-dev" section in your composer.json file:
"require-dev": {
"mockery/mockery": "0.8.*",
"phpunit/phpunit": "3.7.*"
}
You can then install your Composer-based dependencies with the "dev" requirements:
$ php composer.phar install --dev
Learn more about Mockery, Composer and PHPUnit here on Nettuts+.
For PHP, consider using Laravel 4, as it makes exceptional use of containers and other concepts written about here.
Thanks for reading!
]]>
