DragonBe's PHP blog

UA Testing with Selenium and PHPUnit

2013-05-23T20:00:00.000+02:00

Last week I spoke at php[tek] 2013 where I explained to people how to get started with Selenium IDE to record user interaction with the web interface, convert them to PHPUnit testcases and automatically execute them on multiple browsers on multiple platforms.

The feedback I got was awesome, you're all a great crowd! But on twitter I also received a bunch of questions regarding how to set up multiple platforms and why I used Windows in my presentation to deploy to.

So today I deceided it was time to write a full article on this subject.

What is Selenium?

Selenium is a tool that allows you to continuously test user interfaces of web applications. The most common usages for Selenium testing are the following:

testing elements are (not) on the web interface
users can't break out a certain flow on the web interface
calculated values are correct after modification
errors appear on screen when mistakes are made by users
reported issues are valid

In general we call these type of tests User Acceptance Tests or UAT and are all focused from the point of the end-user, the person using the web interface to accomplish a certain goal.

Why are they important?

UAT have their own right to exist. Just like regular unit, performance and stress tests they have their own agenda and are adressing a particular part of your application that needs testing. All to prevent your customers/visitors from finding issues, bugs or just unfunctional pieces on your web application and loose their trust in your products or services.

Therefor it's always good to invest in the "visibile" part of your web application. Especially when using javascript, you want to ensure it always works as intended.

Disclaimer

Selenium tests are in no way a replacement for regular unit tests. Their focus is on generated output of your web application within a browser. Unit tests are still necessary to ensure the logic of your application is not broken when making modifications or adding new functionality!

Setting things up

You can write your own Selenium tests by hand, but the easiest way is to use the Firefox plugin to recored Selenium tests.

Start Firefox and download the plugin at the Selenium IDE download page.

When you are asked to "restart", wait a little and scroll down on the downloads page to PHP Formatter and install this formatter plugin as well.

Once all is installed, restart your Firefox browser.

Now you're all set to get started creating UA tests.

Overview of what we're doing here

The Selenium IDE plugin allows you to record all events you make on the web application you want to test. These can be mouse clicks, entering text inside input fields, pressing enter, drag-and-drop and so much more. All activities are being captured using this recording tool.

For my example I used a simple project that's still a work-in-progress. There were already some issues reported in the bug tracker and I'm showing here how to get started with confirming the issue is truely an issue. Then we fix the issue and rerun our test to see it resolves.

Next we're going to export the Selenium test as PHPUnit test and run it as we'd normally run our unit tests. We can use our IDE, command line (as I will use) or a continuous integration (CI) system to run these tests over and over again.

Since we have a Selenium test we can modify our test case to verify our application works on multiple browsers.

Step 1: Verify an issue from bug tracker

In many cases you're already working on a project and you have issues to resolve. The easiest way to get started with UAT would be to pick an issue and verify the issue is genuine.

Go to your bug tracker and pick an issue. Look at the detailed description of the issue as this will be your test goal.

Now that we have a full understanding of the issue, we can start recording a Selenium test. Our goal is to ensure we can reproduce the issue which is hard sometimes as reports (like this) can specify items that are missing.

Therefor we're going to add "assertions" in our Selenium test of items we expect to be present, but aren't at the moment. This may sound weird, but this way we think ahead on how we need to resolve the issue if the reported issue is genuine.

Step 2: Fix the reported issue and test again

Once we fixed the issue, we can then rerun our test and see it succeed.

We now save the Selenium test as .html file.

Step 3: Convert to PHPUnit test

In the menu of your Selenium IDE window, you can select "File" -> "Export as" -> "PHP (PHPUnit)" and store this in the application's tests directory. I have chosen to create an additional directory called "seleneum" so I can differentiate unit tests for the project.

Step 5: Set up Selenium Server

In order to run your exported Selenium test in an automated, headless way you need to set up a computer that will run the Selenium Server service (as our unit tests will try to contact it for running the tests within a browser). Selenium Server is a Java daemon that will continuously listen to incomming calls from unit tests, so no matter if you run it manually from your IDE or command line, or you have a CI system to run your unit tests automatically, it should be able to contact the system.

I have chosen to use a Windows 7 64bit virtual machine as it supports the most essential browsers like Internet Explorer, Firefox, Google Chrome and others, but as the Selenium Server is a Java service, you can run it on Windows, Linux and Mac OS.

Go back to the Selenium HQ website and download the selenium-server-standalone-X.X.X.jar where X.X.X represents the current version of the tool.

Once downloaded, you can set up your test machine for receiving Selenium Test calls. I created a simple startSeleniumStandalone.BAT file that I launch during startup.

"C:\Program Files (x64)\Java\jre6\bin\java.exe" -jar "C:\Tools\Selenium\selenium-server-standalone-X.X.X.jar" --port 12666

This will launch Selenium Server on port 12666 and will execute for each browser defined a new window.

Step 6: Modifying your PHPUnit Selenium Test

When you first export your Selenium test to a PHPUnit Testcase you need to modify a couple of things before you can execute it. This is the rawexport from Selenium IDE:

<?php
class Example extends PHPUnit_Extensions_SeleniumTestCase
{
  protected function setUp()
  {
    $this->setBrowser("*chrome");
    $this->setBrowserUrl("http://www.theialive.com/");
  }

  public function testMyTestCase()
  {
    $this->open("/");
    $this->click("link=login");
    $this->waitForPageToLoad("30000");
    $this->type("id=email", "dragonbe+tek13@gmail.com");
    $this->type("id=password", "test1234");
    $this->click("id=signin");
    $this->waitForPageToLoad("30000");
    $this->click("link=Test demo");
    $this->waitForPageToLoad("30000");
    $this->assertEquals("Done", $this->getText("xpath=//th[5]"));
    $this->click("link=[EDIT]");
    $this->waitForPageToLoad("30000");
    $this->assertTrue($this->isElementPresent("id=done"));
    $this->click("link=sign off");
    $this->waitForPageToLoad("30000");
  }
}
?>

First we need to rename our test class to something more meaningful, like MarkTaskDoneTest.

class MarkTaskDoneTest extends PHPUnit_Extensions_SeleniumTestCase

Secondly we need to modify our setup so it can connect with our Selenium Server and run Internet Explorer.

protected function setUp()
{
    $this->setBrowser("*iexplore");
    $this->setBrowseUrl("http://www.theialive.com/");
    $this->setHost('192.168.10.33');
    $this->setPort(12666);
}

Lastly we modify our test method to something meaningful like testMarkTaskAsDone:

public function testMarkTaskAsDone()

We also add the following line to our test so on our test machine, all will be executed in full screen. Not really a required feature, but allways nice to see stuff running automatically.

$this->windowMaximize();

So our full test class would look like the following:

<?php
/**
 * Class MarkTaskDoneTest
 *
 * @group SeleniumTest
 */
class MarkTaskDoneTest extends PHPUnit_Extensions_SeleniumTestCase
{
    protected function setUp()
    {
        $this->setBrowser("*iexplore");
        $this->setBrowserUrl("http://www.theialive.com/");
        $this->setHost('192.168.10.33');
        $this->setPort(12666);
    }

    public function testMarkTaskAsDone()
    {
        $this->windowMaximize();
        $this->open("/");
        $this->click("link=login");
        $this->waitForPageToLoad("30000");
        $this->type("id=email", "dragonbe+tek13@gmail.com");
        $this->type("id=password", "test1234");
        $this->click("id=signin");
        $this->waitForPageToLoad("30000");
        $this->click("link=Test demo");
        $this->waitForPageToLoad("30000");
        $this->assertEquals("Done", $this->getText("xpath=//th[5]"));
        $this->click("link=[EDIT]");
        $this->waitForPageToLoad("30000");
        $this->assertTrue($this->isElementPresent("id=done"));
        $this->click("link=sign off");
        $this->waitForPageToLoad("30000");
    }
}

That's it! Now all is ready to run our tests using PHPUnit on the command line.

And this is how our unit tests run on our test machine:

Step 7: Testing with multiple browsers

Running these tests is fun, but they still test a single browser. A better way would be to set up a base TestCase where you set all browser configurations and extend this base TestCase whenever you create a Selenium Test.

File: tests/SeleniumTestCase.php

<?php

require_once 'PHPUnit/Extensions/SeleniumTestCase.php';

class SeleniumTestCase extends PHPUnit_Extensions_SeleniumTestCase
{
    const TEST_HUB = '192.168.10.33';
    const TEST_PORT = 12666;

    const USERNAME = 'dragonbe+tek13@gmail.com';
    const PASSWORD = 'test1234';
    const BASURL = 'http://www.theialive.com';

    public static $browsers = array (
        array (
            'name' => 'Internet Explorer 8 on Windows 7',
            'browser' => '*iexplore',
            'host' => self::TEST_HUB,
            'port' => self::TEST_PORT,
        ),
        array (
            'name' => 'Firefox on Windows 7',
            'browser' => '*firefox',
            'host' => self::TEST_HUB,
            'port' => self::TEST_PORT,
        ),
        array (
            'name' => 'Google Chrome on Windows 7',
            'browser' => '*googlechrome',
            'host' => self::TEST_HUB,
            'port' => self::TEST_PORT,
        ),
    );

    protected function setUp()
    {
        $this->setBrowserUrl(self::BASURL);
    }
}

Now we just need to extend from our base test case to continuously use all configured browsers.

File: tests/selenium/TaskTest.php

<?php
/**
 * Class MarkTaskDoneTest
 *
 * @group SeleniumTest
 */
require_once 'SeleniumTestCase.php';
class MarkTaskDoneTest extends SeleniumTestCase
{
    public function testMarkTestAsDone()
    {
        $this->windowMaximize();
        $this->open("/");
        $this->click("link=login");
        $this->waitForPageToLoad("30000");
        $this->type("id=email", TestCase::USERNAME);
        $this->type("id=password", TestCase::PASSWORD);
        $this->click("id=signin");
        $this->waitForPageToLoad("30000");
        $this->click("link=Test demo");
        $this->waitForPageToLoad("30000");
        $this->assertEquals("Done", $this->getText("xpath=//th[5]"));
        $this->click("link=[EDIT]");
        $this->waitForPageToLoad("30000");
        $this->assertTrue($this->isElementPresent("id=done"));
        $this->click("link=sign off");
        $this->waitForPageToLoad("30000");
    }
}

Running it on CLI will execute 3 times this test as we're testing 3 browsers: Internet Explorer, Firefox and Google Chrome.

On our test machine it would look something like this:

Closing Remarks

Authentication

When running Selenium Tests and your application requires authentication, the best thing you can do is to have your test do the following:

log into your application (carefull, passwords are plain text!!!)
run your tests and assertsions
log out of your application

This way your tests always behave the same.

Multi platform setup

As good developer I not only test on different browsers, but also on multiple platforms. I use virtual machines for this that are always running and I use the following setup to achieve this:

Dom changes

Be careful as Selenium tests heavily depend on the DOM of a web application. Any changes there can have an effect on your Selenium Tests and might result in failing tests.

Survived php tek 2013

2013-05-20T14:14:00.001+02:00

If you were last week in Chicago, you've might felt the city was buzzing PHP all over the place. php[tek] 2013 was taking place at the Sheraton Gateway Suites Chicago O'Hare in Rosemont, just outside of Chicago city.

This year it was also the first time Musketeers.me, a php consulting team from the East Coast, was running the show, putting their own signature onto the event. And with great success I might add. A well deserved applause to Eli White, Kevin Bruce, Sandy Smith, Oscar Merida and of course the Beth Tucker Long for their unlocked achievement running a great conference.

For me was also the first time I was running the uncon, where attendees and conference speakers could propose talks they wanted to present at the uncon and have other attendees vote for them.

One uncon talk really stood out: "Open Sourcing mental illness" by Ed Finkler (@funkatron) where he discussed the issues people face who suffer a mental illness. It was an emotional talk where Ed described his own experiences and how his mind made him think about things differently then the rest of us. For me it was a real eye-opener and made me understand that there are people that don't really take things for granted.

This year's edition was filed with very good talks and it's almost impossible to give my feedback on all of them. A few talks that I attended really stood out that I would really want to promote here.

Chris Cornut, the driving force behind phpdeveloper.org, talked about "Beyond the Basics: Security with PHP" where he did not just list the top 10 of OWASP, but also gave good advices on how to protect yourself against most of the common attacks. A good closing hint: be better secured than the next guy.

Jeremy Kendall was giving good advice on how to improve your code you wrote a couple of weeks or months ago in his talk "PHP 102: Out with the Bad, In with the Good". What I like about Jeremy is he can bring very complex subjects in an easy, understandable way that even a novice can understand complex software engineering stuff. And so he did with this talk.

One talk I missed which I really wanted to see was the Distractions talk of Sean Prunka, or how to deal with distractions when you're a developer. When I look at the reviews on joind.in I see he did an amazing good job giving this was his first conference talk ever. So hopefully he will do a webinar or an online recording of this talk *hint, hint*.

This year my company was sponsoring the hackathon and can be called a good success, knowing we had to compete against Lego fun party. According to Lorna a bunch of pull requests were made for joind.in (the community feedback platform for conference speakers). And we captured the first pull request on twitter.

Can I get a woot? First @joindin pull request of the night has been merged at #tek13 hackathon!
— Lorna Mitchell (@lornajane) May 16, 2013

At the introduction of the hackathon we also had a nice surprise for Mr. Keith Casey from his colleagues at Twillio where he worked 2 years now.

And of course the hallway tracks were not only fun, but also hugely valuable for the community. A spontanious group were giving lessons on doing TDD, others were hacking on gadgets, or just having discussions on best practices. Guess who talked about "how to get started with a user group" and got 3 people stating they would either start or reboot a user group in their area. So Riga in Latvia, Charlottesville in Virginia and Paris in France: get ready as there's a php user group coming near you!

In my experience the best php[tek] ever, and I'm really looking forward to the 2014 edition. If you don't believe me, have a look at the pictures taken at php[tek] 2013. They will tell the story.

Maybe I'll see you next year at #tek14!

Look mama, no databases

2013-03-17T12:08:00.000+01:00

I recently got a question about testing services, where this person was under the impression that when calling services you did not need to know what was going on. You just pass in data and a result is returned. How this result was given was of no importance, all you needed to test was that you got a result and it matched up with what was expected.

The only problem in this case was that he was talking about testing the business logic in the service and I replied he should perform tests on that business logic instead of just asserting the returned result. After some further discussions it was clear that he tested the service "as is", meaning the service makes a call to a database to gather its results and returns the calculation on those results.

When I state "as is", I truly mean the way it's being used in production. So the database call collects real data on which business logic is applied. You can see this is not a healthy situation, especially when you also have services that apply business logic on data and store it back into the database.

In "The Grumpy Programmer's PHPUnit Cookbook", author Chris Hartjes wrote this one sentence that says it all: "Unit test suites are meant to be testing code, not the ability of a database server to return results". And he's right, you shouldn't use database connections when your testing business rules and functional logic.

DISCLAIMER: I'm still using PHPUnit 3.4.15 for testing Zend Framework 1 projects, so all tests here should work with higher versions of PHPUnit. If not, let me know in the comments.

Say you have a service that calculates margins for sold products, it's easy to connect to a sandboxed database and retrieve the product purchase and sales prices, retrieve the commission for the sales person on top of it all and return the calculated margin. Easy enough, right? But say you have thousands of tests like this that all connect to several tables in the database. Running tests will only go slower and slower until it reaches the point developers on the team don't run them because they will take too long to run.

Example: Product.php

<?php

class Product
{
    protected $_db;

    public function __construct()
    {
        $dsn = 'mysql:dbname=test;host=localhost;';
        $user = 'testuser';
        $pass = 'test123';
        $this->_db = new PDO($dsn, $user, $pass);
    }
    public function calculateMargins($productId)
    {
        $sql = 'SELECT * FROM product
                    LEFT JOIN employee
                        ON product.employeeId = employee.employeeId
                    WHERE product.id = ?';
        $stmt = $this->_db->prepare(
            $sql, array (PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));

        $stmt->execute(array ($productId));
        $result = $stmt->fetchAll();
        $margin = ($result[0]['salesPrice'] - $result[0]['purchasePrice'])
                * (1 - $result[0]['commission']);
        return $margin;
    }
}

This can be just a normal class like you must have dozens off. In the case where a test is being made to validate this business logic, this class will connect to your database, retrieves the data and performs the calculation.

Example test that will pass when the values are the following:

purchasePrice: 299.95
salesPrice: 399.95
commission: 15%

<?php
require_once 'Product.php';

class ProductTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupGlobals disabled
     * @backupStaticAttributes disabled
     */
    public function testCalculateProductMargin()
    {
        $expectedMargin = 85.00;
        $product = new Product();
        $result = $product->calculateMargins(1);
        $this->assertSame($expected, $result,
            sprintf('Expected margin of %02f did not match actual margin %02f',
                $expected, $result));
    }
}

The main issue I have with this test is that I'm too depending on the database to deliver me the data. And what happens if another developer needs to modify the data in the database for his tests? Exactly, my test will fail.

How can we solve this so we can test the business logic without connecting to the database?

The first thing we need to do is to ensure we can pass in a database replacement into our Product class, our mock object. So we rewrite the Product class a little so the constructor accepts a dbAdapter as parameter.

<?php

class Product
{
    protected $_db;

    public function __construct($db = null)
    {
        if (null === $db) {
            $dsn = 'mysql:dbname=test;host=localhost;';
            $user = 'testuser';
            $pass = 'test123';
            $db = new PDO($dsn, $user, $pass);
        }
        $this->_db = $db;
    }
    public function calculateMargins($productId)
    {
        $sql = 'SELECT * FROM product
                    LEFT JOIN employee
                        ON product.employeeId = employee.employeeId
                    WHERE product.id = ?';
        $stmt = $this->_db->prepare(
            $sql, array (PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));

        $stmt->execute(array ($productId));
        $result = $stmt->fetchAll();
        $margin = ($result[0]['salesPrice'] - $result[0]['purchasePrice'])
                * (1 - $result[0]['commission']);
        return $margin;
    }
}

The next thing we need to do is to modify our ProductTest class so we can set our values directly in our test, without relying on databases for providing us this data.

<?php
require_once 'Product.php';

class ProductTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupGlobals disabled
     * @backupStaticAttributes disabled
     */
    public function testCalculateProductMargin()
    {
        $data = array (
            array (
                'purchasePrice' => 299.95,
                'salesPrice' => 399.95,
                'commission' => 0.15,
            ),
        );

        $stmt = $this->getMock('PDOStatement', array ('execute','fetchAll'));
        $stmt->expects($this->any())
             ->method('execute')
             ->will($this->returnValue(true));
        $stmt->expects($this->any())
             ->method('fetchAll')
             ->will($this->returnValue($data));

        $pdo = $this->getMock('PDO', array('prepare'),
            array('sqlite:dbname=:memory'),'PDOMock',true);
        $pdo->expects($this->any())
            ->method('prepare')
            ->will($this->returnValue($stmt));

        $expectedMargin = 85.00;
        $product = new Product($pdo);
        $result = $product->calculateMargins(1);
        $this->assertSame($expected, $result,
            sprintf('Expected margin of %02f did not match actual margin %02f',
                $expected, $result));
    }
}

Yes, we need to mock out our PDO object and our PDOStatement object just to mock the behaviour of our database call, but the benefit is now we can focus on the business logic instead of expecting everything will be provided. We now have just one set of values, but we can just add more and more values to it and move it to a data provider.

<?php
require_once 'Product.php';

class ProductTest extends PHPUnit_Framework_TestCase
{
    public function marginDataProvider()
    {
        return array (
            array (299.95, 399.95, 0.15, 85.00),
            array (1200.00, 1500.00, 0.10, 270.00),
            array (1200.00, 1200.00, 0.10, 0.00),
            array (1200.00, 1000.00, 0.10, -180.00),
        );
    }
    /**
     * @backupGlobals disabled
     * @backupStaticAttributes disabled
     * @dataProvider marginDataProvider
     */
    public function testCalculateProductMargin($pp, $sp, $comm, $expected)
    {
        $data = array (
            array (
                'purchasePrice' => $pp,
                'salesPrice' => $sp,
                'commission' => $comm,
            ),
        );

        $stmt = $this->getMock('PDOStatement', array ('execute','fetchAll'));
        $stmt->expects($this->any())
             ->method('execute')
             ->will($this->returnValue(true));
        $stmt->expects($this->any())
             ->method('fetchAll')
             ->will($this->returnValue($data));

        $pdo = $this->getMock('PDO', array('prepare'),
            array('sqlite:dbname=:memory'),'PDOMock_' . uniqid(),true);
        $pdo->expects($this->any())
            ->method('prepare')
            ->will($this->returnValue($stmt));

        $product = new Product($pdo);
        $result = $product->calculateMargins(1);
        $this->assertSame($expected, $result,
            sprintf('Expected margin of %02f did not match actual margin %02f',
                $expected, $result));
    }
}

So now we can test multiple values over and over again, and if for some reason we need to test a specific combination of values, we just add it to our data provider method. In this example we added values to see what happens when we have no margin and when we have sold products below purchase price.

The end result is you have a test that will test the business requirements, isn't making an expensive database call (runs faster) and allows you to modify the test in case the scope of business logic changes (e.g. no commission is paid when sales price is equal or below the purchase price).

Route default is not defined

2012-11-28T14:50:00.001+01:00

Working this long with Zend Framework makes me do things that have become a real routine and I don't pay much attention to it. So when I just add few custom routes to my Zend Framework application, I don't make a big fuss out of it. But apparently people do struggle with it. They get messages like this:

Zend_Controller_Router_Exception: Route default is not defined

Apparently when you create custom routes, Zend Framework "forgets" about the default route, causing this error to appear.

To quickly resolve this issue, you just open up application/Bootstrap.php and add the following to your routines:

    protected function _initDefaultRoutes()
    {   
        $frontController = Zend_Controller_Front::getInstance();
        $frontController->getRouter()->addDefaultRoutes();
    }

If you already have routine for loading routes, just ensure you add the default routes!

    protected function _initRouteSetup()
    {   
        $frontController = Zend_Controller_Front::getInstance();
        $router = $frontController->getRouter();
        $config = new Zend_Config_Ini('/path/to/config.ini', APPLICATION_ENV);
        $router->addConfig($config, 'routes');

        // ensure you load the default routes as well!!!
        $router->addDefaultRoutes();
    }

With this blog article I hope to save a bunch of people a lot of time looking for an example and get on with building awesome applications.

Learning lessons at ZendUncon

2012-11-13T00:40:00.001+01:00

In my previous post I already mentioned Sebastian Jerzy Wilczyński (@dj_sebastian_w) and his uncon session "Unit Testing for Databases using fixtures and phpunit". It made me wonder how much difference it would make if you use fixtures instead of testing database interactions using predefined sets of data.

Since I work a lot with Zend Framework I was looking at how I could use fixtures and mock objects to follow Sebastian's guidelines. So I gave it a try. This is what I came up with.

I use the domain model design pattern for accessing data storages with Zend Framework so this means I have a model (Order_Model_Order) which is the representation of my data object, a mapper (Order_Model_OrderMapper) to connect my model with an underlying data storage backend and a table gateway object (Order_Model_DbTable_Order) to link everything to the database. The object we're going to focus on is Order_Model_OrderMapper as this is the link that connects my model to the database.

At first I start my test class with fixtures.

<?php

class Order_Model_OrderMapperTest extends PHPUnit_Framework_TestCase
{
    protected $_order = array (
        0 => array (
            'id'             => 1,
            'status'         => 0,
            'price'          => 2499.95,
            'currency'       => 'USD',
            'exchange_rate'  => 1.2714,
            'vat_id'         => 3,
            'vat_percentage' => 0.00,
            'created_by'     => 400,
            'created_at'     => '2012-02-29 10:11:12',
            'updated_by'     => 303,
            'updated_at'     => '2012-11-04 03:01:01',
        ),
        1 => array (
            'id'             => 1,
            'status'         => 0,
            'price'          => 10000.00,
            'currency'       => 'EUR',
            'exchange_rate'  => 1.00,
            'vat_id'         => 1,
            'vat_percentage' => 21.00,
            'created_by'     => 400,
            'created_at'     => '2012-02-29 10:11:12',
            'updated_by'     => 303,
            'updated_at'     => '2012-11-04 03:01:01',
        ),
    );
}

The next thing we need to come up with is how to mock out the data gateway as we don't want to connect to the database of course. Because my mapper class Order_Model_OrderMapper has 2 methods to set and retrieve the data gateway it's easy to flip in and out the data gateway object. Here's my Order_Model_OrderMapper class:

<php
class Order_Model_OrderMapper
{
    /**
     * @var Zend_Db_Table_Abstract
     */
    protected $_dbTable;
    /**
     * Sets the data gateway for this Mapper class
     * 
     * @param Zend_Db_Table $dbTable
     * @throws In2it_Model_Exception
     */
    public function setDbTable($dbTable)
    {
        if (is_string($dbTable)) {
            if (!class_exists($dbTable)) {
                throw new In2it_Model_Exception(
                    'Non-existing data gateway provided'
                );
            }
            $dbTable = new $dbTable;
        }
        if (!$dbTable instanceof Zend_Db_Table_Abstract) {
            throw new In2it_Model_Exception('Invalid data gateway provided');
        }
        $this->_dbTable = $dbTable;
    }
    /**
     * Retrieves the data gateway class from this Mapper class
     * 
     * @return Zend_Db_Table
     * @throws In2it_Model_Exception 
     */
    public function getDbTable()
    {
        if (!isset ($this->_dbTable)) {
            throw new In2it_Model_Exception('Data gateway not set');
        }
        return $this->_dbTable;
    }

    ...
}

All we need to do now is create a mock object that we can inject in our mapper test so we don't need to connect to the database in order to test our mapper logic.

public function testOrderMapperCanFindSingleItem()
{
    $order = new Order_Model_Order();
    $orderMapper = new Order_Model_OrderMapper();
        
    $mockDb = $this->getMock('Order_Model_DbTable_Order', array ('find'));
    $mockDb->expects($this->atLeastOnce())
           ->method('find')
           ->will($this->returnValue(new ArrayIterator($this->_order)));
    $orderMapper->setDbTable($mockDb);

    $orderMapper->find($order, 1);
    $this->assertEquals($this->_order[0], $order->toArray());
}

So we create our $mockDb object replacing our data gateway object Order_Model_DbTable_Order, and by overriding the find method we can now control how we want this method to operate. By returning an ArrayIterator object, we can use the iterator method current() which is used by the find method in our mapper class. All that's left is to find our order and assert it's the same as our fixture.

I hope this might give a few ideas on saving time running your tests. The less you have expensive connections, the quicker your tests will execute.

ZendCon 2012

2012-11-11T22:48:00.002+01:00

October is often the month where all PHP businesses look towards sunny California, because it's ZendCon time! This year was no exception and it was a true blast. And ZendCon means not just 4 days of PHP goodness but also 2 days and a half of Uncon power. And this year I had the honour and pleasure to be in charge of the ZendUncon sessions.

Because my involvement in those uncon sessions, I missed most of the regular tracks. But on the bright side I was able to discover new speakers and was sitting in a few awesome sessions I would like to recommend here.

Let me explain the idea behind uncon sessions first, so you at least have a good grasp of the importance of these sessions. An uncon session is different from regular conference sessions because they are not scheduled and can be given by anybody. It's a great way for conference attendees to give a talk or a round table discussion. For the first situation, people can learn how to speak in public and get their first steps in talking at conferences. It's also a solution for open-source project leads to teach and answer questions regarding their projects.

Every day of the conference a clean registration board was set up, and people could select a specific time they wanted to run an uncon session. Of course this meant that availability is a "first-come, first-serve" kind of thing. Early people were able to select the best slots, because they could compare their uncon session with the conference schedule and pick a slot when none of the regular conference sessions was of interest for the speaker.

Back to the ZendUncon sessions of ZendCon 2012. Three days of uncon goodness, making it an unforgettable event. Let me highlight a couple of remarkable talks I've seen during these three days, which I can highly recommend to have at any given PHP conference.

Stefan Koopmanschap (@skoop) with "Conference Speaking 101" where he gives a whole bunch of tips and concepts anyone could use as advice for speaking at conferences. Even the regular speakers!

First time speaker Sebastian Jerzy Wilczyński (@dj_sebastian_w) with "Unit Testing for Databases using fixtures and phpunit" where he gives a very interesting point of view for testing database interactions using fixtures without reaching the database.

Best talk was given by Lorna Mitchel (@lornajane) with "Git + Github: everything you need to know!" with a standing room and enormous positive feedback.

Elizabeth Marie Smith (@auroraeosrose) was giving a true community driven talk "Mentoring Developers (and phpmentoring.org)" where she explained why and how experienced developers could take mentorship to assist and train developers seeking mentoring (apprentices). If you're in a situation where you're looking for mentorship, please visit phpmentoring.org for more information.

If you're interested in the whole ZendUncon series, you can find all the talks and most of the slides on the joind.in page for ZendUncon.

Returning from PHPNW12

2012-10-10T23:32:00.001+02:00

This last weekend Manchester (UK) was buzzing PHP all over the place, because PHPNW12was held in the city center! I arrived on Thursday, a day before the tutorial day and had an opportunity to talk to a bunch of early attendees and got to meet new faces in the community.

For the past 4 years I've been attending this community driven conference, seeing it grow into a professional organized event run by professionals that know their stuff on both PHP and organizing a good gig. And I was really honored to be the closing keynote for this year's conference.

Tutorial Day

PHPNW12 is known to have incredible good tutorial sessions, given by involved people into any given project. This time it was no different. I attended the Zend Framework 2 tutorial track given by no one less than Rob Allen (@akrabat) and Evan Cory (@EvanDotPro). Since they were heavily involved in the development process before Zend Framework 2 was stable, they were best positioned to give this tutorial. And they did a great job! I even got a certificate to prove I participated this tutorial.

Hackathon evening

In the evening a hackathon session was organized and in2it vof was proud sponsor for the pizza's. We should also have sponsored the wifi as lack of internet was a serious issue during this event.

Conference

The conference itself was a great event on it's own. Meeting new folks and seeing old friends is one of those magical moments you experience when going to such a community driven conference. But Jeremy Coates (@phpcodemonkey) and his crew did a great job putting great names down for this conference. Names like Thijs Feryn, Lorna Mitchell, Igor Wiedler, Ian Barber, Rowan Merewood, Mike van Riel, Ben Waine and Anthony Ferrara (just to name a few). And guess what, the wifi was stable during the whole conference!!!

I had the honor to close this conference with a community keynote called "Community Works for business too!", a talk to inspire business owners and to provide great arguments for developers within businesses to become more involved in community work. Even though the audience felt it was too much focused to business owners, I still believe it was a magical closure for three great days of brain hurting talks and enormous amount of information. I'm already looking forward to next year.

I also want to express my sincere gratitude to Rob Alan (@Akrabat) for taking an awesome photo of me.

Conclusion

An awesome community driven PHP conference, period. Make sure you attend #phpnw13!

Microsoft Hackathon at PHPBenelux Conference 2012

2011-12-23T19:36:00.002+01:00

I started these series on Zend Framework Apps on Windows Azure and maybe it's nice to know I'll be at the PHPBenelux Conference 2012 Microsoft Hackathon where I'll be joined by Windows Azure MVP Maarten Balliauw, Katrien De Graeve and Craig Kitterman of Microsoft and offer you the opportunity to hack on the PHP tools Microsoft and partners have developped to integrate your apps on the various Microsoft platforms.

Even if you have no knowledge of any of Microsoft's PHP solutions you're more then happy to join us and see how you can build applications so they can be distributed with the Web Platform Installer for running on Windows IIS servers.

Or maybe you just ended up with a new job in a company that only runs Windows Servers. We'll explain what you need to do so your applications run smoothly on these Microsoft IIS infrastructures.

And of course we'll have a look at Windows Azure, the cloud solution of Microsoft that allows you to develop PHP apps for the future. With grandmasters Maarten Balliauw and Craig Kitterman it's going to be an experience comparable to Alice in Wonderland. Are you ready to see how deep the Microsoft PHP tunnel runs?

Get your tickets now for the PHPBenelux Conference 2012 and join us to hack and learn more of all the Microsoft PHP tools and blow away your teammates and competitors with awesome applications.

Configuring Zend Framework apps for Windows Azure

2011-12-18T20:56:00.000+01:00

Building web applications is nothing new anymore, as we've been doing it since the early days of the internet, but we've always done this on a single system. Even when Zend Framework came round, we kept doing the same thing and build apps for a single environment.
But as I've discussed already in my previous article, developing for the cloud requires another approach.

As you can see, your system now falls appart into all different components that are systems by themselves. And each system has its own purpose, completely independent from each other.

With Zend Frameworkdeveloping applications running on these separate compontents becomes really easy. It's like having your cloud toolbox right in your pocket.

Databases

With Zend Framework, connecting to databases is really easy and swapping out a database brand is just a matter of modifying your configuration application/configs/application.ini.

resources.db.adapter = "pdo_mysql"
resources.db.params.host = "10.20.30.40"
resources.db.params.username = "user1"
resources.db.params.password = "secret"
resources.db.params.dbname = "db1"
resources.db.isDefaultTableAdapter = true

Even if you need to connect to multiple databases, you can just pile them up as configuration setting and be done with it.

resources.multidb.server1.adapter = "pdo_mysql"
resources.multidb.server1.host = "10.20.30.40"
resources.multidb.server1.username = "user1"
resources.multidb.server1.password = "secret1"
resources.multidb.server1.dbname = "db1"
resources.multidb.server1.default = true

resources.multidb.server2.adapter = "pdo_pgsql"
resources.multidb.server2.host = "10.20.30.41"
resources.multidb.server2.username = "user2"
resources.multidb.server2.password = "secret2"
resources.multidb.server2.dbname = "db2"

resources.multidb.server3.adapter = "pdo_sqlite"
resources.multidb.server3.dbname = APPLICATION_PATH "/files/db/project.db"

But this is just the basics. When dealing with the cloud you often get a connection string for the host, so it's real easy to hook up to an relational database in the cloud. Here's an example to connecting to SQL Azure.

resources.db.adapter = "SQLSRV"
resources.db.params.host = "abcdefghijk.database.windows.net"
resources.db.params.port = 1234
resources.db.params.username = "user1"
resources.db.params.password = "secret"
resources.db.params.dbname = "db1"
resources.db.isDefaultTableAdapter = true

Bottom line, no worries connecting to a cloud database. Zend Framework has your back!

Sessions

As you want to assist your visitors as much as possible, you probably want to use sessions in your application. If you don't configure anything, PHP stores session on your filesystem by default and so does Zend Framework.

For the cloud, you don't want to write to your local filesystem, so you set up session storage. I chose to use the SQL Azure server I already had setup using the following settings.

resources.session.use_only_cookies = true
resources.session.gc_maxlifetime = 864000
resources.session.remember_me_seconds = 864000
resources.session.saveHandler.class = "Zend_Session_SaveHandler_DbTable"
resources.session.saveHandler.options.name = "session"
resources.session.saveHandler.options.primary = "id"
resources.session.saveHandler.options.modifiedColumn = "modified"
resources.session.saveHandler.options.dataColumn = "data"
resources.session.saveHandler.options.lifetimeColumn = "lifetime"

No further changes need to be done as all fields are defined and this Zend_Session_SaveHandler_DbTable takes care of all the rest.

Caching

Just like databases, providing caching for your application requires just a few simple configuration settings, this example sets up a memcache service.

resources.cachemanager.memcached.frontend.name = Core
resources.cachemanager.memcached.frontend.options.automatic_serialization = On
resources.cachemanager.memcached.backend.name = Libmemcached
resources.cachemanager.memcached.backend.options.servers.one.host = localhost
resources.cachemanager.memcached.backend.options.servers.one.port = 11211
resources.cachemanager.memcached.backend.options.servers.one.persistent = On

Caching on the cloud requires a little different approach as most cloud services offer their own flavor of caching, making it difficult to find a PHP driver that is capable to access this cloud caching layer. But don't let this stop you in moving to the cloud. Windows Azure provides a superb caching platform, and I'll show you later in these series how to modify your application as it requires a little tweek on the configuration of your Windows Azure installation.

Storage

Uploading and distributing files can be considered as an importan part of any application, and with Zend Framework you can manage file uploads relatively simple using Zend_Form and Zend_File.

An example would be to upload a small image.

public function uploadAction()
{
 $adapter = new Zend_File_Transfer_Adapter_Http();
 
 $adapter->setDestination(APPLICATION_PATH '/files/upload');

 if (!$adapter->receive()) {
 $messages = $adapter->getMessages();
 echo implode("\n", $messages);
 }
 $this->view->filename = $adapter->getFileName('avatar', false);
}

Saving into a specific location is done with $adapter->setDestination(), but this still requires the usage of a local location! And we know that in the cloud saving locally has no use! Luckily for you, Zend Framework has a bunch of components that will allow you to store files onto a Windows Azure Storage instance.

 public function uploadAction()
 {
 $config = new Zend_Config_Ini(APPLICATION_PATH . '/configs/api.ini', APPLICATION_ENV);
 
 $azure = new My_Cloud_WindowsAzure_AzureStorage(
 $config->azure->storage->account, 
 $config->azure->storage->primkey);
 
 $container = $config->azure->storage->container;
 
 $adapter = new Zend_File_Transfer_Adapter_Http();
 $adapter->setDestination(APPLICATION_PATH '/files/upload');

 if (!$adapter->receive()) {
 $messages = $adapter->getMessages();
 echo implode("\n", $messages);
 }
 
 $storageClient = new Zend_Service_WindowsAzure_Storage_Blob(
 My_Cloud_WindowsAzure_AzureStorage::AZURE_STORAGE_HOST, 
 $azure->getAccountName(), $azure->getPrimaryKey());
 
 $result = null;
 
 if (!$storageClient->containerExists($container)) {
 $result = $storageClient->createContainer($container);
 $storageClient->setContainerAcl($container, 
 Zend_Service_WindowsAzure_Storage_Blob::ACL_PUBLIC_CONTAINER);
 }

 $fileName = $adapter->getFileName('resume', true);
 $result = $storageClient->putBlob(
 $container, basename($fileName), $fileName
 );
 
 $this->view->filename = basename($fileName);
 $this->view->location = sprintf('http://%s.%s/%s/%s',
 $azure->getAccountName(),
 My_Cloud_WindowsAzure_AzureStorage::AZURE_STORAGE_HOST,
 $config->azure->storage->container,
 $result->Name);
 }

As you can see, you only need to add a little more functionality to the first example. But once you have everything in place, nothing can stop you achieving your goals.

; These are local configuration settings
; Primarily used to access API's using credential tokens
[production]
...
azure.storage.account = "myblobstorageaccount1"
azure.storage.primkey = "fjldjljdlfjadladjsljdfljfdljd/akjddfjldfjjd22kajdajfei3234ajldjfjklajlajd=="
azure.storage.container = "myblobstoragecontainer"
...

[staging: production]
[testing: production]
[development: production]

In this example I used an api.ini which is very convenient to store your most import settings like account names, api keys and passwords to various api services. It's just a file containing key-value pairs for easy configuration. In this case my INI settings look like the following listing.

Now that we've talked about the specific settings in your Zend Framework application it's about time we set up our environment, download all the tools, register for a Windows Azure account and get started with running our Zend Framework app in the cloud. So stay tuned for more.

Windows Azure for PHP developers

2011-12-11T23:03:00.001+01:00

Introduction

Since a couple of years the term "cloud" has moved from simple buzz-word to real business opportunities that make a difference within the market. The technology behind "cloud" is not new as we've grown accustomed to server clusters, distributed datacenters and separation of responsibilities, but the "cloud" offers everyone the opportunity to scale and not just the companies who have a huge cash reserve to purchase another rack with servers.

The strange thing is that cloud is being provided by companies you wouldn't expect to serve it. Best known are Amazon.com and Rackspace.com that offers a complete set of services you can use to run applications in the cloud, they provide the infrastructure and you have to set up and maintain your platform and infrastructure. Microsoft also jumped on this cloud hype offering a platform in the cloud. And this is exactly the reason it caught my attention and got me interested. I'm a developer and I don't want to fiddle with setting up and maintaining an operating system, basically since I don't have the time for it.

If you are eager to learn more about cloud and what different kind of cloud solutions are out there, I can recommend the book "PHP Development In The Cloud" by Ivo Jansch and Vito Chin. In this book both authors look beyond the buzz of the cloud and discuss what each cloud service provider has to offer for PHP developers and how you can easily consume their services using PHP code. A must read for everyone that has an interest in developing web applications using PHP and cloud technology, as I already posted a book review for this book here on my blog.

Windows Azure

I got in touch with Microsoft's Windows Azureback in 2008 through our local Microsoft Evengalist Katrien De Graeve, who told me Windows Azure is like running a Windows 2008 Server with IIS in the cloud. Along with Maarten Balliauw Microsoftwas working out more tools and features to support PHP (amongst other open source technologies) on their new cloud platform.

I was completely sold when Josh Holmes came to Brussels in 2009 and told us more about what Windows Azure has to offer and how perfectly it is to build applications consuming these cloud services, without having to deal with setting up and maintaining the platform the run on. And so, I started playing with it and discovering about what Windows Azure is all about, what kind of services they offer and how I as a PHP developer could make good use out of it. In 2010 PHPBeneluxand Microsoft joind efforts to promote Windows Azure by organizing a PHPonAzure contest to develop an application that would run and make use of Windows Azure's services.

Developing for cloud

When developing PHPapplications, you mostly develop for a single server setup or maybe one server running your PHPcode and one server for the database. This is the easiest way to set up an environment as you don't need to worry about anything except to connect to the correct database.
When developing for the cloud, more things should be considered before you get started. Some things that you take for granted require some additional thoughts when designing the architecture of your application. Fortunately for you, there are only a few things to take into account before you can deploy your latest killer app in the cloud provided by Windows Azure.

Operating System

On a bare metal server or even a virtual server, you know you need to set up your own operating system (or have your hosting service provider or sysadmin do this for you). This means you need to take responsibilty in keeping your OS up-to-date with security fixes and all kinds of software upgrades.
Windows Azure is a platform on it's own, comparable to a fully set up Windows 2008 Server complete with IIS 7. Microsoft takes care of updating and securing their instances you use without compromizing your application.

Data Storage

When creating a normal website session data, logs, caches and file uploads are often stored on the local filesystem. With a cloud solution, you need to consider that multiple instances of your web application might be up and running and don't share each others filesytem. To facilitate filesystem storage, cloud services offer so called "file buckets" or storage endpoints. Windows Azureoffers 5 types of storage:

Blob storage: simple binary storage for video, images, audio and other types of files
Table storage: a structured storage for large amounts of data, behaving like a NoSQL storage
Queue: a messaging queue to transfer messages between applications and services
Windows Azure Drive: a mounted shared disk partition formatted as NTFS VHD
SQL Azure: a true relational database based on Microsoft SQL Server technology

One storage location I need to mention a little separate is Windows Azure Cache, a memory storage. It's a caching layer comparable to Memcached or WinCache, residing completely in memory.

File uploads are easy as you only need to worry where they end up and how you make sure files cannot overwrite existing files, unless specified to do so. Using one of the 5 storage solutions provided by Windows Azure is not difficult using PHP, it only requires correct settings for transferring the uploaded file to the chosen storage. PHP's move_uploaded_file()method can be used in most cases. In other cases, use the Windows Azure SDK for PHPas it offers a rich abstraction layer for the different storage options of Windows Azure.

Sessions in PHP can easily be stored in a database, a storage endpoint or on a memory layer by modifying the session_set_save_handler(). Windows Azure can store session data on the blob storage, table storage, the Windows Azure Drive, in SQL Azure or on it's Cache layer. I prefer to use either the SQL Azure or the Cache, as they both perform really fast, even for session data.

When using logs within your application, you also need to be aware that your log files should reside somwehere central. Best is to either log against Table storage or SQL Azure as it's a fast way to keep track of changes and easily accessible. But, storing logs on the blob storage is perfectly good as well, only know it might grow your storage space too much.

Caching is something best handled by Windows Azure Cache, the memory storage I mentioned earlier. It's fast, very easy to maintain and super easy to scale in or out.

Data itself can be stored in SQL Azure or on Table Storage. SQL Azure is a full featured relational database, comparable to Microsoft SQL Server. It offers all the features you can expect from a relational database, including stored procedures, transactions and separation of responsibilities. Table Storage is a simple key/value storage table, that behaves more like a NoSQL storage and thus capable of storing documents and constructs in an organized way.

Other considerations

Cloud applications should be designed to scale horizontally. This means when your application requires more resources to cope with the usage, more instances of the application will run together behaving as a single application.

Cloud is also "pay as you go". If you use a little, you pay a little. If you use a lot, you pay also a lot but less then when you need to scale with traditional hardware. The following graphs by Josh Holmesexplains it best.

Now it doesn't matter if you're a big company or just a start-up. You can launch your product slowly and grow as your usage and budget grows. A perfect match.

Now that I've introduced you to what Windows Azure has to offer PHP developers, or any other technology developer for that matter, I show you how I have a simple Zend Framwork application build on a traditional LAMP stack deployed to Windows Azure. So stay tuned for more.

PHPBenelux Conference 2012 Announcement

2011-11-16T18:54:00.001+01:00

Hey, just letting you guys know there's an awesome conference happening in January: The PHPBenelux Conference 2012! They just opened up their ticket sales at really low prices, so even if you come from abroad it's still cheap.

The PHPBenelux team only announced the names of tutorial speakers, but with names like Ivo Jansch, Torsten Rhinne, Fabien Potencier and Matthew Weier O'Phinney you know it's going to rock! And that's tutorials only.

It's all happening on January 27 and 28, so make sure you block those days in your calendar, because the center of Europe is going to buzz PHP like it never had before!!! Get your tickets now while their still hot (and cheaper than cheap)!!!

Pfcongres 2011 wrap up

2011-09-18T22:32:00.000+02:00

This Saturday I started early to go to Pfcongres, a small PHP community conference in Utrecht organized by the Dutch PHP user group PHPFreakz and after about two hours driving I arrived about half an hour in time before the conference started, with me kick starting with my keynote "Community Works", a 199 slide deck explaining what the PHP community is and how people can be part of that community.

My keynote was well received by the audience, although some comments were made it needed a more elegant flow of community tips. It even started a discussion whether I should use visuals or not to emphasize my words. I will take these comments into consideration when I'm reviewing these slides.

Although I spend a major part of the conference in the so-called "Hallway tracks" I was able to jump into a couple of great talks that have intrigued me to look into their details. A couple of tracks that really stood out were "SPL Data Structures and their Complexity" by Jurrien Stutterheim, "15 Protips for MySQL users" by Joshua Thijssen and of course the closing keynote "PHP — Status Check" by no one less than co-founder of Zend Mr. Zeev Suraski.

The good
The team of PHPFreakz managed to do the impossible: creating a good balance for Dutch and non-Dutch speakers, offering a good lunch (especially for Dutch standards) with a wide variety of sandwiches and a constant flow of good coffee.

The bad
I have no complaints regarding the organization, the audience or the venue. I just felt bad I had to wake up at 6am just to be there on time.

The ugly
The venue's wifi was a real burden, and I know from experiences that most conference wifi settings are flakey as a rule, but this wifi experience was bad, even considering the flakey ones.

Conclusion
This conference showed the world again that a small community group can amaze everyone by bringing quality speakers into their community offering them high level content at a really reasonable prize. I'd like to express my gratitude to the organization to be part of this event.

Bonus challenge
I keep thinking about what Joshua Thijssen said during his talk about getting certified as a MySQL engineer. As it was on my to-do list for a couple of years, I think I needed the push Joshua had given me to follow up on my commitments and schedule an exam.

Quality Assurance on PHP projects - PHPUnit lessons learned

2011-09-15T10:46:00.001+02:00

This is what I like about the PHP community: people work out similar ideas and share what they've learned in the process. Sometimes people pick up ideas and work them out, sometimes people just continue the conversation.

And I believe Lars Tesmer has done the latter, where he blogs on testing PHPUnit itself and the lessons learned in that process.

Thank you Lars for sharing your lessons.

Quality Assurance on PHP projects - PHPUnit part 4

2011-09-03T23:27:00.000+02:00

In parts one, two and three we focussed on writing tests for a game of tic-tac-toe, with in parts two and three we optimized our tests so they focus on the functionality of the individual parts Grid and Player, with a collection class Players to handle Player objects.

In this fourth part we should focus on playing the game. Let's go over the steps again:

each player chooses a symbol
for each turn (max 9 turns)

a player places his symbol on the grid
if 3 symbols appear in a single row (horizontal, vertical or diagonal)

player is a winner

So this is a simple and a straightforward rule we can turn into code. But let's look at the tests we've written in part 1 to see if they're still valid.

    public function testGameCanBePlayed()
    {
        $playerX = $this->_ttt->getPlayers()->seek(0)->current();
        $playerO = $this->_ttt->getPlayers()->seek(1)->current();
        
        $this->assertFalse($this->_ttt->play(0, 0, $playerX));
        $this->assertFalse($this->_ttt->play(0, 1, $playerX));
        $this->assertTrue($this->_ttt->play(0, 2, $playerX));
        
        $this->_ttt->setGrid(new Grid());
        
        $this->assertFalse($this->_ttt->play(0, 0, $playerX));
        $this->assertFalse($this->_ttt->play(1, 0, $playerX));
        $this->assertTrue($this->_ttt->play(2, 0, $playerX));
        
        $this->_ttt->setGrid(new Grid());
        
        $this->assertFalse($this->_ttt->play(0, 0, $playerX));
        $this->assertFalse($this->_ttt->play(1, 1, $playerX));
        $this->assertTrue($this->_ttt->play(2, 2, $playerX));
        
        $this->_ttt->setGrid(new Grid());
        
        $this->assertFalse($this->_ttt->play(0, 2, $playerX));
        $this->assertFalse($this->_ttt->play(1, 1, $playerX));
        $this->assertTrue($this->_ttt->play(2, 0, $playerX));
    }

As you see, we only tested the functionality to see if we can have a winner when 3 identical symbols appear in a single row horizontal, vertical or diagonal. We can make a couple of comments on this test:

this test is named wrong as it doesn't test the gameplay functionality
this test should be branched out into different tests for each row
this test doesn't test turn-by-turn game play

In other words, we need to clean this up and come up with better tests! Let's focus on tearing this test into 3 separate tests, testing just a single direction. Again, we can use a dataProvider method for this.

    public function rowColProvider()
    {
        return array (
            array (array (array (0,0), array (0,1), array (0,2))),
            array (array (array (0,0), array (1,0), array (2,0))),
            array (array (array (0,0), array (1,1), array (2,2))),
            array (array (array (0,2), array (1,1), array (2,0))),
        );
    }
    /**
     * @dataProvider rowColProvider
     */
    public function testGameplayCanDetectWinner($rowCols)
    {
        $player = $this->_ttt->getPlayers()->seek(0)->current();
        $this->assertFalse($this->_ttt->play($rowCols[0][0], $rowCols[0][1], $player));
        $this->assertFalse($this->_ttt->play($rowCols[1][0], $rowCols[1][1], $player));
        $this->assertTrue($this->_ttt->play($rowCols[2][0], $rowCols[2][1], $player));
    }

Now we know that with each turn, the return value will indicate if we have a winner (TRUE) or not (FALSE). But we still need to see if we can have the same result when playing with two players. As you see with the last line, the third entry gives us a positive result.

But we still don't have a gameplay going! We need to have two players enter the arena and each player playing turn by turn. So how do we approach this? Well, the easiest way for now is to create a test that does just that. The benefit here is we can decide which player is going to win the game.

    public function testGameCanBePlayed()
    {
        $playerX = $this->_ttt->getPlayers()->seek(0)->current();
        $playerO = $this->_ttt->getPlayers()->seek(1)->current();
        $this->assertFalse($this->_ttt->play(0, 0, $playerX));
        $this->assertFalse($this->_ttt->play(0, 1, $playerO));
        $this->assertFalse($this->_ttt->play(1, 1, $playerX));
        $this->assertFalse($this->_ttt->play(2, 2, $playerO));
        $this->assertFalse($this->_ttt->play(1, 0, $playerX));
        $this->assertFalse($this->_ttt->play(2, 0, $playerO));
        $this->assertTrue($this->_ttt->play(1, 2, $playerX));
    }

Visual this result looks like the following grid:

 X | O |   
 X | X | X 
 O |   | O

But most importantly our tests are still green, giving us that wonderful feeling of achievement.

Let's finish up our tests so we can see no one can play any further after we've got a winner. PHPUnit provides a nice anotation we can use for this: depends. So now we can test that the game is stopped, depending on our test "testGameCanBePlayed".
For this to work, we need to return our game (in this case $this->_ttt). Just add the following line at the bottom of the test class "testGameCanBePlayed".

    public function testGameCanBePlayed()
    {
        $playerX = $this->_ttt->getPlayers()->seek(0)->current();
        $playerO = $this->_ttt->getPlayers()->seek(1)->current();
        $this->assertFalse($this->_ttt->play(0, 0, $playerX));
        $this->assertFalse($this->_ttt->play(0, 1, $playerO));
        $this->assertFalse($this->_ttt->play(1, 1, $playerX));
        $this->assertFalse($this->_ttt->play(2, 2, $playerO));
        $this->assertFalse($this->_ttt->play(1, 0, $playerX));
        $this->assertFalse($this->_ttt->play(2, 0, $playerO));
        $this->assertTrue($this->_ttt->play(1, 2, $playerX));
        return $this->_ttt;
    }

And the next step is simple:

    /**
     * @depends testGameCanBePlayed
     * @expectedException RuntimeException
     */
    public function testGameStopsAfterWinning($game)
    {
        $playerO = $game->getPlayers()->seek(1)->current();
        $game->play(2,1, $playerO);
    }

In order for this test to succeed we need to add a couple of things to our game:

a status property that will tell us if there's a winner
a setter method to flip the flag once a winner is detected
a checking method to verify a winner is not yet detected
modify our play method so it throws a RuntimeException when we try to play when a winner exists.

<?php
...

class Tictactoe
{
    ...

    /**
     * Status indicator to say there's a winner or not
     * 
     * @var bool
     */
    protected $_winner = false;

    ...

    /**
     * Sets a flag to indicate this game has a winner
     * 
     * @param bool $flag
     * @return Tictactoe
     */
    public function setWinner($flag = true)
    {
        $this->_winner = $flag;
        return $this;
    }
    /**
     * Checks if the game has a winner
     * 
     * @return bool
     */
    public function hasWinner()
    {
        return $this->_winner;
    }
    /**
     * Plays the game and returns TRUE if a player has become a winner, FALSE
     * if the player is not (yet) a winner.
     * 
     * @param int $row
     * @param int $column
     * @param Player $player
     * @return bool
     * @throws RuntimeException
     */
    public function play($row, $column, Player $player)
    {
        if ($this->hasWinner()) {
            throw new RuntimeException('Game already has a winner');
        }
        $this->getGrid()->setSymbol($row, $column, $player->getSymbol());
        return $this->isWinner($player);
    }
    /**
     * Returns TRUE if a player has become a winner, FALSE if not.
     * 
     * @param Player $player
     * @return bool
     */
    public function isWinner(Player $player)
    {
        if ($this->getGrid()->inRow($player->getSymbol())) {
            $this->setWinner();
            return true;
        }
        if ($this->getGrid()->inColumn($player->getSymbol())) {
            $this->setWinner();
            return true;
        }
        if ($this->getGrid()->inDiagonal($player->getSymbol())) {
            $this->setWinner();
            return true;
        }
        return false;
    }
}

That's it. We covered the main purpose of the game and we did it semi test driven. We can start playing a cute little game of Tictactoe and covered a couple important features of PHPUnit. I also showed that it's not a bad thing if you modify parts of your tests to achieve new or other specifications.

The full game source code can be found on my github account (https://github.com/DragonBe/tictactoe), and as you go over the log, you can follow along with these series as well. When playing with the source code, you might think about testing edge cases: playing 9 rounds and no winner, try to place a symbol off the grid, place twice a symbol on the grid of a single player (cheating), and so on.

Another thing could be that you turn this little game into an online game. What are the things you need to concider in that situation. Are our tests still valid or do we need to modify our architecture and our tests to support that kind of game playing?

Since it's on GitHub, you can fork it and send me a pull request once you have an edge case figured out.

Quality Assurance on PHP projects - PHPUnit part 3

2011-08-28T23:30:00.000+02:00

Time for the third part on unit testing with phpunit in my Quality Assurance on PHP projects series. In part one we started writing unit tests for a simple game of tic-tac-toe. In part two we started converting our unit tests into actual code and moved our general unit test code for grids into a Grid focussed unit test. In this part, we're looking at how we can optimize the tests for our players.

When we look at our initial tests for players, we only focussed on two things: each player has a symbol and players are managed within a collection class.

    public function testGamePlayersAreSetAtStart()
    {
        $players = $this->_ttt->getPlayers();
        $this->assertInstanceOf('Players', $players);
        $this->assertEquals(2, count($players));
        $this->assertEquals(Player::PLAYER_X, $players->seek(0)->current()->getSymbol());
        $this->assertEquals(Player::PLAYER_O, $players->seek(1)->current()->getSymbol());
    }

As you can imagine, this is a very minimalistic test that cannot cope with all player related issues. We did have two classes to handle all player related issues and thus we need to move our test out of our TictactoeTest class.

A quick look at the functionality of a player should give us more fuel to creat better unit tests. Bytaking a new look at the functionality of a single player, we can optimize our tests. Since we already have some working code, let's take a quick look at the Player class to figure out what is being expected.

<?php
/**
 * TicTacToe
 * 
 * A simple game that's played with two players, each taking a turn by marking
 * a field in a grid of 3 x 3 with either an X or an O (one symbol per player).
 * Winner is the one who has 3 identical symbols in a single horizontal,
 * vertical or diagonal row.
 * 
 * @package Tictactoe
 * @license "Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)"
 * @link http://creativecommons.org/licenses/by-sa/3.0/
 */
/**
 * Player
 * 
 * This Player class is responsible to set up and maintain a single player
 * 
 * @package Tictactoe
 * @category Tictactoe
 *
 */
class Player
{
    /**
     * Defines the symbol X for a player to choose
     * 
     * @var string
     */
    const PLAYER_X = 'X';
    /**
     * Defines the symbol X for a player to choose
     * 
     * @var string
     */
    const PLAYER_O = 'O';
    /**
     * The symbol a player chooses
     * 
     * @var string
     */
    protected $_symbol;
    /**
     * Constructor for a single player, with an optional symbol (X or O) to
     * define the player's playing symbol
     * 
     * @param string $symbol
     */
    public function __construct($symbol = null)
    {
        if (null !== $symbol) {
            $this->setSymbol($symbol);
        }
    }
    /**
     * Sets a symbol for this Player
     * 
     * @param string $symbol
     * @return Player
     */
    public function setSymbol($symbol)
    {
        $this->_symbol = (string) $symbol;
        return $this;
    }
    /**
     * Retrieves the chosen symbol from this Player
     * 
     * @return string
     */
    public function getSymbol()
    {
        return $this->_symbol;
    }
}

As you can see, we only care about the symbol of the player. Apparently this is more than enough for now. But when we check our main TictactoeTest we see no specific tests for our Player class. About time to do something about it.

<?php
class PlayerTest extends PHPUnit_Framework_TestCase
{
    protected $_player;
    protected function setUp()
    {
        $this->_player = new Player();
        parent::setUp();
    }
    protected function tearDown()
    {
        $this->_player = null;
        parent::tearDown();
    }
    public function testPlayerHasNoSymbolAtStartup()
    {
        $this->assertNull($this->_player->getSymbol());
    }
    public function goodSymbolProvider()
    {
        return array (
            array ('O'),
            array ('X'),
        );
    }
    /**
     * @dataProvider goodSymbolProvider
     */
    public function testPlayerCanSetASymbol($symbol)
    {
        $this->_player->setSymbol($symbol);
        $this->assertEquals($symbol, $this->_player->getSymbol());
    }
}

In our code and in our tests we only set a symbol, but don't check if the symbol is valid. The rules of this game do specify that only a X or a O are allowed. So we need to add additional logic to our tests and code. Let's work on our test first.

    public function badSymbolProvider()
    {
        return array (
            array ('a'),
            array (123),
            array ('Hello World!'),
            array (0x123),
        );
    }
    /**
     * @dataProvider badSymbolProvider
     * @expectedException InvalidArgumentException
     */
    public function testPlayerThrowsExceptionWithBadSymbol($symbol)
    {
        $this->_player->setSymbol($symbol);
    }

By using the 'expectedException' annotation we can verify that a specific exception is thrown. For most exceptions you can often use one of the SPL exceptions. We choose 'InvalidArgumentException' as the symbol is an invalid argument for this Player class. Of course our tests will fail as we haven't forseen this feature or behaviour.

We need to modify our code so it can be throw an InvalidArgumentException when wrong arguments (read symbols) are being provided. We want our tests to succeed, right?

    /**
     * Sets a symbol for this Player
     * 
     * @param string $symbol
     * @return Player
     * @throws InvalidArgumentException
     */
    public function setSymbol($symbol)
    {
        $validSymbols = array (self::PLAYER_O, self::PLAYER_X);
        if (!in_array($symbol, $validSymbols)) {
            throw new InvalidArgumentException(
                'Player can only choose between X or O');
        }
        $this->_symbol = (string) $symbol;
        return $this;
    }

As you can see, it's just a small but significant change that ensures proper symbols are being used in our game. And our tests now succeed.

So we can increase the quality of the game by making sure only allowed symbols are used.

We also have a collection class called Players that contain both players. We could have used an array, but as we don't know yet what kind of functionality we want for all players. In our code we just created this collection that implements the SeekableIterator and Countable interfaces. Our PlayersTest should be able to add a Player object, even two Player objects but certainly not more than 2 players. In test code this becomes a simple straightforward test.

<?php
class PlayersTest extends PHPUnit_Framework_TestCase
{
    protected $_players;
    
    protected function setUp()
    {
        $this->_players = new Players();
        parent::setUp();
    }
    protected function tearDown()
    {
        parent::tearDown();
        $this->_players = null;
    }
    public function testPlayersIsEmptyAtStartUp()
    {
        $this->assertEmpty($this->_players->getPlayers());
    }
    public function testPlayerCanAddPlayer()
    {
        $this->_players->addPlayer(new Player());
        $this->assertEquals(1, count($this->_players));
    }
    public function testPlayerCanTwoPlayerObjects()
    {
        $this->_players->addPlayer(new Player())
                       ->addPlayer(new Player());
        $this->assertEquals(2, count($this->_players));
    }
    /**
     * @expectedException OverflowException
     */
    public function testPlayerCannotAddMoreThenTwoPlayerObjects()
    {
        $this->_players->addPlayer(new Player())
                       ->addPlayer(new Player())
                       ->addPlayer(new Player());
    }
}

Since we implement 2 interfaces we know the functionality of them, and therefor we should not test for it as they will throw errors if not implemented correctly. If you still doubt yourself on working with these interfaces, create a separate set of tests that just verifies your collection class is behaving as expected. Our collection class Players will look like this.

<?php
/**
 * TicTacToe
 * 
 * A simple game that's played with two players, each taking a turn by marking
 * a field in a grid of 3 x 3 with either an X or an O (one symbol per player).
 * Winner is the one who has 3 identical symbols in a single horizontal,
 * vertical or diagonal row.
 * 
 * @package Tictactoe
 * @license "Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)"
 * @link http://creativecommons.org/licenses/by-sa/3.0/
 */
/**
 * Players
 * 
 * This Players class is a collection container for both players, implementing
 * both Countable and SeekableIterator interfaces from SPL
 * 
 * @package Tictactoe
 * @category Tictactoe
 * @see SeekableIterator
 * @see Countable
 * @link http://php.net/spl
 *
 */
class Players implements SeekableIterator, Countable
{
    const MAX_PLAYERS = 2;
    /**
     * Contains Player objects
     * 
     * @var array
     */
    protected $_players = array ();
    /**
     * Specifies the position in the stack
     * 
     * @var int
     */
    protected $_position;
    /**
     * Keeps track of the count
     * 
     * @var int
     */
    protected $_count;
    /**
     * Constructor for this Players collection, allows setting players with
     * optional provided array of Player objects
     * 
     * @param array $array
     */
    public function __construct(array $array = null)
    {
        if (null !== $array) {
            foreach ($array as $player) {
                $this->addPlayer($player);
            }
        }
    }
    /**
     * Adds a Player object to the collection
     * 
     * @param Player $player
     * @return Players
     * @throw Overflow
     */
    public function addPlayer(Player $player)
    {
        if (self::MAX_PLAYERS <= $this->count()) {
            throw new OverflowException('Cannot add more Player objects');
        }
        $this->_players[] = $player;
        return $this;
    }
    /**
     * Retrieves a list of Player objects currently in the collection
     * 
     * @return array
     */
    public function getPlayers()
    {
        return $this->_players;
    }
    /**
     * Sets the internal stack pointer back to 0
     * 
     * @see SeekableIterator::rewind()
     */
    public function rewind()
    {
        $this->_position = 0;
    }
    /**
     * Sets the internal stack pointer to the next position
     * 
     * @see SeekableIterator::next()
     */
    public function next()
    {
        $this->_position++;
    }
    /**
     * Checks if the current position in the stack is still valid
     * 
     * @see SeekableIterator::valid()
     * @return boolean
     */
    public function valid()
    {
        return isset ($this->_player[$this->_position]);
    }
    /**
     * Retrieves the current object from the stack
     * 
     * @see SeekableIterator::current()
     * @return Player
     */
    public function current()
    {
        return $this->_players[$this->_position];
    }
    /**
     * Retrieves the current position from the stack
     * 
     * @see SeekableIterator::key()
     * @return int
     */
    public function key()
    {
        return $this->_position;
    }
    /**
     * Moves the position to the given stack postion
     * 
     * @see SeekableIterator::seek()
     * @throws OutOfBoundsException
     */
    public function seek($position)
    {
        if (!isset ($this->_players[$position])) {
            throw new OutOfBoundsException('No more items in this stack');
        }
        $this->_position = $position;
        return $this;
    }
    /**
     * Keeps record of the count in this collection
     * 
     * @see Countable::count()
     */
    public function count()
    {
        return count($this->_players);
    }
}

Ok, we now have our Grid and our Player objects tested. Next up is testing the game itself. Are all our tests taking care of all rules defined by the game? What are the edge cases? What is not acceptable? All this and more in the next eppisode of 'Quality Assurance on PHP projects'.

Quality Assurance on PHP projects - PHPUnit part 2

2011-08-23T00:08:00.002+02:00

I hope everyone enjoyed my first article on unit testing with phpunit where I started writing a few tests that would guide us building our little game of tictactoe. Today I'm going start with turning these tests into working code and adjusting our tests to have a clear separation of responsibility. Since we already know what the code should produce, we only have to work out the details.

Our tests tell us we have four classes:

Tictactoe: the main class that is responsible for the game and how it should be played
Grid: is the class that's responsible for setting up the playing grid
Players: a collection class containing both player objects
Player: the class defining a single player

Our first test concerns all about the grid we're going to use. Here's the test again:

    public function testGameGridIsSetAtStart()
    {
        $grid = $this->_ttt->getGrid();
        $this->assertInstanceOf('Grid', $grid);
        $this->assertEquals(3, count($grid->getRows()));
        foreach ($grid->getRows() as $row) {
            $this->assertInternalType('array', $row);
            $this->assertEquals(3, count($row));
            $this->assertNull($row[0]);
            $this->assertNull($row[1]);
            $this->assertNull($row[2]);
        }
    }

What can we learn from this test?

Grid is part of our main TicTacToe class
has a method that fetches rows of type array

and each row has columns as an array

We can also make the following assumptions:

Grid class will instantiate a grid with 3 rows and 3 columns
When calling "getRows()" we retrieve an array of 3 columns
Each field in the grid will have a null value as a default
A Player must have a way to set his "symbol" on a specific position on the grid
Must have a way to verify if a given symbol exists in either a horizontal, a vertical or a diagonal row

With this information we can start writing our Grid class

<?php
/**
 * TicTacToe
 * 
 * A simple game that's played with two players, each taking a turn by marking
 * a field in a grid of 3 x 3 with either an X or an O (one symbol per player).
 * Winner is the one who has 3 identical symbols in a single horizontal,
 * vertical or diagonal row.
 * 
 * @package Tictactoe
 * @license "Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)"
 * @link http://creativecommons.org/licenses/by-sa/3.0/
 */
/**
 * Grid
 * 
 * This Grid class is responsible to set up and maintain the playing field
 * 
 * @package Tictactoe
 * @category Tictactoe
 *
 */
class Grid
{
    /**
     * Constant to define the number of rows
     * @var int
     */
    const ROWS = 3;
    /**
     * Constant to define the number of colomns
     * @var int
     */
    const COLS = 3;
    /**
     * Container for all rows and columns
     * 
     * @var array
     */
    protected $_rows = array ();
    /**
     * Constructor for this Grid class that will set up our grid with 3 rows
     * and 3 columns while setting the value of each field to NULL
     */
    public function __construct()
    {
        for ($i = 0; $i < self::ROWS; $i++) {
            $columns = array ();
            for ($j = 0; $j < self::COLS; $j++) {
                $columns[$j] = null;
            }
            $this->addRow($columns);
        }
    }
    /**
     * Adds a row to the grid, requiring an array of 3 fields representing
     * the columns
     * 
     * @param array $row
     * @return Grid
     */
    public function addRow(array $row)
    {
        $this->_rows[] = $row;
        return $this;
    }
    /**
     * Retrieves all rows from this grid, including an array for the columns
     * for each row
     * 
     * @return array
     */
    public function getRows()
    {
        return $this->_rows;
    }
    /**
     * Sets the symbol for each field
     * 
     * @param int $row The position of the field in the row
     * @param int $column The position of the field in the column
     * @param string $symbol
     */
    public function setSymbol($row, $column, $symbol)
    {
        $this->_rows[$row][$column] = $symbol;
        return $this;
    }
    /**
     * Retrieves the current symbol from a given cordinate on the grid
     * 
     * @param int $row The postion of the field in the row
     * @param int $column The position of the field in the column
     * @return string
     */
    public function getSymbol($row, $column)
    {
        return $this->_rows[$row][$column];
    }
    /**
     * Validation method to verify if a given symbol is found 3 times in a
     * single row. If we have 3 matches, it will return TRUE. In all other
     * cases it will return FALSE.
     * 
     * @param string $symbol
     * @return boolean
     */
    public function inRow($symbol)
    {
        foreach ($this->getRows() as $row) {
            $match = 0;
            foreach ($row as $column) {
                if ($symbol === $column) {
                    $match++;
                }
            }
            if (self::ROWS === $match) {
                return true;
            }
        }
        return false;
    }
    /**
     * Validation method to verify if a given symbol is found 3 times in a
     * single column. If we have 3 matches, it will return TRUE. In all other
     * cases it will return FALSE.
     * 
     * @param string $symbol
     * @return boolean
     */
    public function inColumn($symbol)
    {
        for ($i = 0; $i < self::COLS; $i++) {
            $match = 0;
            for ($j = 0; $j < self::ROWS; $j++) {
                if ($symbol === $this->_rows[$j][$i]) {
                    $match++;
                }
            }
            if (self::COLS === $match) {
                return true;
            }
        }
        return false;
    }
    /**
     * Validation method to verify if a given symbol is found 3 times in a
     * single diagonal row. If we have 3 matches, it will return TRUE. In all 
     * other cases it will return FALSE.
     * 
     * @param string $symbol
     * @return boolean
     */
    public function inDiagonal($symbol)
    {
        $match1 = $match2 = 0;
        for ($i = 0; $i < self::ROWS; $i++) {
            if ($symbol === $this->_rows[$i][$i]) {
                $match1++;
            }
            if ($symbol === $this->_rows[$i][self::COLS - 1 - $i]) {
                $match2++;
            }
        }
        if (self::ROWS === $match1 || self::ROWS === $match2) {
            return true;
        }
        return false;
    }
}

Now we have a grid class, but we cannot test it properly as we use a Tictactoe class to validate everything. No problem, we can modify our tests as well to better serve our needs. Actually, we already have defined our test criteria. Let's list them again:

Grid is part of our main TicTacToe class (is not really relevant for our Grid functionality)
has a method that fetches rows of type array

and each row has columns as an array

Grid class will instantiate a grid with 3 rows and 3 columns
When calling "getRows()" we retrieve an array of 3 rows with each 3 columns
Each field in the grid will have a null value as a default
A Player must have a way to set his "symbol" on a specific position on the grid
Must have a way to verify if a given symbol exists in either a horizontal, a vertical or a diagonal row

The first four criterea we already addressed in our general Tictactoe test case. To separate responsibilities, we can move our test case from our main TictactoeTest class into a GridTest class.

<?php
class GridTest extends PHPUnit_Framework_TestCase
{
    const TEST_SYMBOL = 'X';
    
    protected $_grid;
    
    protected function setUp()
    {
        $this->_grid = new Grid();
        parent::setUp();
    }
    protected function tearDown()
    {
        parent::tearDown();
        $this->_grid = null;
    }
    public function testGameGridIsSetAtStart()
    {
        $this->assertEquals(Grid::ROWS, count($this->_grid->getRows()));
        foreach ($this->_grid->getRows() as $row) {
            $this->assertInternalType('array', $row);
            $this->assertEquals(Grid::COLS, count($row));
            foreach ($row as $column) {
                $this->assertNull($column);
            }
        }
    }
}

So now we have exactly the same as before, except we created a separate TestCase specifically designed for Grid related tests. This allows us to follow up on issues people might report later on (things we haven't thought of or just don't know yet), as we can write now a specific test for our Grid.

But we're not there yet, we still have 2 more things to verify: positioning of a symbol and verifying we have a 3 identical symbols in any of the three rows, columns or diagonal rows.

Let's look at our test verifying the positioning of a symbol:

    public function testGridCanPositionASymbol()
    {
        $this->_grid->setSymbol(0, 0, self::TEST_SYMBOL);
        $this->assertNotNull($this->_grid->getSymbol(0,0));
        $this->assertEquals(self::TEST_SYMBOL, $this->_grid->getSymbol(0,0));
    }

But as you see, this is not really working for us. We can only ferify just one position on the grid and if we want to test more positions, our test method would grow exponentionally. Say hello to the "dataProvider"

    public function cordinateProvider()
    {
        return array (
            array (0,0), array (0,1), array (0,2), array (1,0), array (1,1),
            array (1,2), array (2,0), array (2,1), array (2,2),
        );
    }
    /**
     * @dataProvider cordinateProvider
     */
    public function testGridCanPositionASymbol($row, $column)
    {
        $this->_grid->setSymbol($row, $column, self::TEST_SYMBOL);
        $this->assertNotNull($this->_grid->getSymbol($row, $column));
        $this->assertEquals(self::TEST_SYMBOL, $this->_grid->getSymbol($row, $column));
    }

The @dataProvider tag in your codeblock comment tells PHPUnit to use the method specified by this tag as a "provider" of data. Each row in this data provider method (as it returns an array of arrays) will be a provisioner for your test class, and for each row, your test will be executed from a clean state, so you don't have any corruption due to bad resetting of your objects.

Hey, now we can also use this to verify if we have 3 identical symbols in a horizontal, vertical or diagonal row! Let's work that out as well.

    protected function _setDataOnGrid($data)
    {
        foreach ($data as $field) {
            list ($row, $column) = $field;
            $this->_grid->setSymbol($row, $column, self::TEST_SYMBOL);
        }
    }
    public function horizontalRowProvider()
    {
        return array (
            array (array (array (0,0), array (0,1), array (0,2))),
            array (array (array (1,0), array (1,1), array (1,2))),
            array (array (array (2,0), array (2,1), array (2,2))),
        );
    }
    /**
     * @dataProvider horizontalRowProvider
     */
    public function testGridHasThreeSymbolsInARow($data)
    {
        $this->_setDataOnGrid($data);
        $this->assertTrue($this->_grid->inRow(self::TEST_SYMBOL));
    }
    public function VerticalRowProvider()
    {
        return array (
            array (array (array (0,0), array (1,0), array (2,0))),
            array (array (array (0,1), array (1,1), array (2,1))),
            array (array (array (0,2), array (1,2), array (2,2))),
        );
    }
    /**
     * @dataProvider VerticalRowProvider
     */
    public function testGridHasThreeSymbolsInAColumn($data)
    {
        $this->_setDataOnGrid($data);
        $this->assertTrue($this->_grid->inColumn(self::TEST_SYMBOL));
    }
    public function DiagonalRowProvider()
    {
        return array (
            array (array (array (0,0), array (1,1), array (2,2))),
            array (array (array (0,2), array (1,1), array (2,0))),
        );
    }
    /**
     * @dataProvider DiagonalRowProvider
     */
    public function testGridHasThreeSymbolsInADiagonal($data)
    {
        $this->_setDataOnGrid($data);
        $this->assertTrue($this->_grid->inDiagonal(self::TEST_SYMBOL));
    }

Oh, Wow! We now have a complete Grid test case that isolates all Grid related tasks and responsibilities.

<?php
class GridTest extends PHPUnit_Framework_TestCase
{
    const TEST_SYMBOL = 'X';
    
    protected $_grid;
    
    protected function setUp()
    {
        $this->_grid = new Grid();
        parent::setUp();
    }
    protected function tearDown()
    {
        parent::tearDown();
        $this->_grid = null;
    }
    public function testGameGridIsSetAtStart()
    {
        $this->assertEquals(Grid::ROWS, count($this->_grid->getRows()));
        foreach ($this->_grid->getRows() as $row) {
            $this->assertInternalType('array', $row);
            $this->assertEquals(Grid::COLS, count($row));
            foreach ($row as $column) {
                $this->assertNull($column);
            }
        }
    }
    public function cordinateProvider()
    {
        return array (
            array (0,0), array (0,1), array (0,2), array (1,0), array (1,1),
            array (1,2), array (2,0), array (2,1), array (2,2),
        );
    }
    /**
     * @dataProvider cordinateProvider
     */
    public function testGridCanPositionASymbol($row, $column)
    {
        $this->_grid->setSymbol($row, $column, self::TEST_SYMBOL);
        $this->assertNotNull($this->_grid->getSymbol($row, $column));
        $this->assertEquals(self::TEST_SYMBOL, $this->_grid->getSymbol($row, $column));
    }
    protected function _setDataOnGrid($data)
    {
        foreach ($data as $field) {
            list ($row, $column) = $field;
            $this->_grid->setSymbol($row, $column, self::TEST_SYMBOL);
        }
    }
    public function horizontalRowProvider()
    {
        return array (
            array (array (array (0,0), array (0,1), array (0,2))),
            array (array (array (1,0), array (1,1), array (1,2))),
            array (array (array (2,0), array (2,1), array (2,2))),
        );
    }
    /**
     * @dataProvider horizontalRowProvider
     */
    public function testGridHasThreeSymbolsInARow($data)
    {
        $this->_setDataOnGrid($data);
        $this->assertTrue($this->_grid->inRow(self::TEST_SYMBOL));
    }
    public function VerticalRowProvider()
    {
        return array (
            array (array (array (0,0), array (1,0), array (2,0))),
            array (array (array (0,1), array (1,1), array (2,1))),
            array (array (array (0,2), array (1,2), array (2,2))),
        );
    }
    /**
     * @dataProvider VerticalRowProvider
     */
    public function testGridHasThreeSymbolsInAColumn($data)
    {
        $this->_setDataOnGrid($data);
        $this->assertTrue($this->_grid->inColumn(self::TEST_SYMBOL));
    }
    public function DiagonalRowProvider()
    {
        return array (
            array (array (array (0,0), array (1,1), array (2,2))),
            array (array (array (0,2), array (1,1), array (2,0))),
        );
    }
    /**
     * @dataProvider DiagonalRowProvider
     */
    public function testGridHasThreeSymbolsInADiagonal($data)
    {
        $this->_setDataOnGrid($data);
        $this->assertTrue($this->_grid->inDiagonal(self::TEST_SYMBOL));
    }
}

Running this test along with our initial TictactoeTest should result in a warm, fuzzy, green feeling when you see this screen:

Next time, let's look at our Players as the need also some respect, right.

Quality Assurance on PHP projects - PHPUnit part 1

2011-08-17T02:02:00.011+02:00

Of all tools available for improving quality assurance, there's one tool that is the core tool you have to master: PHPUnit. PHPUnit is a complete testing framework crafted by Sebastian Bergmann (@s_bergmann), who ported existing xUnit frameworks to PHP. And with this testing framework you're able to test your functionality in an automated way before you push code into production.

[editorial] As I cannot summarize the whole usage of phpunit in one blogpost, this will be a sequence of several articles that will pick up a specific task you want to cover with phpunit.

Installation

Well, first of all you need to have PHPUnit installed on your system. The easiest way to accomplish this is to use the PEAR installer.

user@server: $ pear channel-discover pear.phpunit.de

user@server: $ pear channel-discover components.ez.no

user@server: $ pear channel-discover pear.symfony-project.com

Once you've got the right channels, you can install the framework:

user@server: $ pear install phpunit/PHPUnit

Configuration

You can use three methods to configure the way PHPUnit executes tests on your project:

a configuration file
command line parameters
a combination of both

Using a configuration file called "phpunit.xml" is by far the easiest way to run your unit tests in a consistent and organized way. It's a simple XML configuration file and the following works for me most of the times.

NOTE: I use phpunit with a configuration file that matches my project settings, so you might need to modify these settings if you're using a framework or have a different source code layout.

</testsuite>

</whitelist>

</filter>

</phpunit>

This simple configuration file has 3 major parts:

1. The phpunit configuration tag

This tag starts the complete configuration, but also includes a bootstrap file (for bootstrapping your application like Zend Framework's bootstrapper class) and enables colors to show green, yellow and red colored bars to indicate the status of your tests. Since I'm a fan of a warm, fuzzy feeling whenever I see green, I enable this by default.

2. Testsuite section

The testsuite is a wrapper that bundles all your tests into a single suite, so you can call it immediately at execution. You can provide it with a name and a directory.

This section is very useful if you have multiple sections in your projects that you want to separate, as you can define the test suites based on their paths on the filesystem.

3. Filtering

Filtering allows you to quickly define what needs to be tested and what needs to be excluded. In my case I need just to investigate my Zend Framework application path and my custom library path. I also want to exclude all my templates as they don't contain any logic.

You can add also a section for logging where you can define code coverage reports (requires XDebug), a testdox progress report and other kinds of reports provided by PHPUnit. But since I will transfer these tasks to another tool, I'm not going to discuss it here.

I also use a bootstrap file for phpunit called TestHelper.php that allows me to "bootstrap" my test suite. This bootstrap file sets my defined constants, include paths, timezone and error reporting levels.

This is a very minimalistic bootstrapper:

<?php

// file: tests/TestHelper.php

// set our app paths and environments

define('BASE_PATH', realpath(dirname(__FILE__) . '/../'));

define('APPLICATION_PATH', BASE_PATH . '/src');

define('TEST_PATH', BASE_PATH . '/tests');

define('APPLICATION_ENV', 'testing');

// Include path

set_include_path(

'.'

. PATH_SEPARATOR . BASE_PATH . '/src'

. PATH_SEPARATOR . get_include_path()

);

// Set the default timezone !!!

date_default_timezone_set('Europe/Brussels');

// We wanna catch all errors en strict warnings

error_reporting(E_ALL|E_STRICT);

So how do you start?

Testing is really simple but for most people the complexity of having code testing other code and just report back if it's working or not is a bit confusing for people that haven't written any tests before.

For the most part, in my professional career I get a lot of excuses like "no time", "no budget" or "no interest". If it's truly such a big problem to cope with something as simple as writing a test, a career change might be in order. And I mean it. I believe that if you're serious about your job, you have to take a little responsibility in it. And writing tests is not that hard.

Let's begin with a classic example: a tic-tac-toe game. This is a simple pen-and-paper game for two players (O and X) that uses a grid of 3 by 3. The purpose of the game is to have a row, a column or a diagonal row filled with only O's or X's. More information can be found at http://en.wikipedia.org/wiki/Tic-tac-toe.

source: http://en.wikipedia.org/wiki/File:Tic-tac-toe-game-1.png

So how do you start with this kind of a game? Very simple: define the objects, the rules and the goal of this game in a list that makes sense to you. I like to define it as follows:

objects:
- symbol X for user 1
- symbol Y for user 2
- play grid of 3 rows by 3 columns
rules:
- write your symbol once for each turn within the grid
goal:
- prevent opponent to win
- win by having 3 symbols on a single row, a single column or a single diagonal row

Since I have tendency to write my tests before I write the code, as it allows me to think about what I expect I should get from class methods. Another benefit is that you write smaller classes with methods that just do what needs to be done.

TictactoeTest

Let's define our general outline for our main class Tictactoe. We already know a few things: two players, a grid of 3 rows by 3 columns and a winner when three identical symbols are in a single row horizontal, vertical or diagonal.

In test code it would look something like this:

<?php

// file: tests/TictactoeTest.php

require_once 'Tictactoe.php';

class TictactoeTest extends PHPUnit_Framework_TestCase

{

public function testGameGridIsSetAtStart()

{

// test to see a grid is created of 3 by 3 and all fields are null

}

public function testGamePlayersAreSetAtStart()

{

// test to see players are set up at start with symbols X and O

}

public function testGameCanBePlayed()

{

// play a simple game with two players turn by turn

// returning true or false would notify us if there's a winner or not

}

We test 3 major things here: that a grid is set, that two players are created and that the game can be played. We don't worry for edge cases or exceptions now, as we can take care of that later.

When we run this test, we get a bunch of errors, basically saying that we don't have a Tictactoe class file yet. At this point, this is very normal.

user@server:/dev/ttt/tests $ phpunit

PHP Warning: require_once(Tictactoe.php): failed to open stream: No such file or directory in /dev/ttt/tests/TictactoeTest.php on line 3

Warning: require_once(Tictactoe.php): failed to open stream: No such file or directory in /dev/ttt/tests/TictactoeTest.php on line 3

PHP Fatal error: require_once(): Failed opening required 'Tictactoe.php' (include_path='.:/dev/ttt/src:.:/usr/lib/php/pear') in /dev/ttt/tests/TictactoeTest.php on line 3

Fatal error: require_once(): Failed opening required 'Tictactoe.php' (include_path='.:/dev/ttt/src:.:/usr/lib/php/pear') in /dev/ttt/tests/TictactoeTest.php on line 3

We've got are main goals set, now it's time to make some assertions to see we get the information we want.

First of all, we're going to setUp and tearDown our test case, so we know each test starts with a clean slate.

class TictactoeTest extends PHPUnit_Framework_TestCase

{

protected $_ttt;

protected function setUp()

{

parent::setUp();

$this->_ttt = new Tictactoe();

}

protected function tearDown()

{

$this->_ttt = null;

parent::tearDown();

}

Now we need to fill in the blanks regarding the test methods. Let's start with our first method:

public function testGameGridIsSetAtStart()

{

// we should be able to retrieve the grid from our Tictactoe class

$grid = $this->_ttt->getGrid();

// let's make sure we created a grid class to handle all grid related manipulations

$this->assertInstanceOf('Grid', $grid);

// we know the grid is 3 x 3, so let's count the rows

$this->assertEquals(3, count($grid->getRows()));

// and for each row, let's count the columns

// and since we're at it, let's check that their fields are empty

foreach ($grid->getRows() as $row) {

$this->assertInternalType('array', $row);

$this->assertEquals(3, count($row));

foreach ($row as $column) {

$this->assertNull($column);

}

So, what do we learn from this test? We need to have a Grid class to take care of all grid related things and we need to ensure each field is empty before we start playing. Take a note of this as we need it later!

The next step is to set up our players. We know we have two players and each player has his own symbol (X or O).

public function testGamePlayersAreSetAtStart()

{

// we should be able to retrieve all players from our Tictactoe class

$players = $this->_ttt->getPlayers();

// ensure that players have their own class to take care of all players

$this->assertInstanceOf('Players', $players);

// we know we only have two players

$this->assertEquals(2, count($players));

// we want to ensure that each player has the correct symbol

$this->assertEquals(Player::PLAYER_X, $players->seek(0)->current()->getSymbol());

$this->assertEquals(Player::PLAYER_O, $players->seek(1)->current()->getSymbol());

}

This test teaches us we need another two classes for our players. One class is acting as a collection implementing the SeekableIterator and Countable interfaces from SPL (I just love these, so I know I will use them!). The second class defines the player and the symbol it gets.

Our last test method is all about playing the game.

public function testGameCanBePlayed()

{

// let's pick just one player

$player = $this->_ttt->getPlayers()->seek(0)->current();

// and see if we can win if we created a row

$this->assertFalse($this->_ttt->play(0, 0, $player));

$this->assertFalse($this->_ttt->play(0, 1, $player));

$this->assertTrue($this->_ttt->play(0, 2, $player));

$this->_ttt->setGrid(new Grid());

// and see if we can win if we created a column

$this->assertFalse($this->_ttt->play(0, 1, $player));

$this->assertFalse($this->_ttt->play(1, 1, $player));

$this->assertTrue($this->_ttt->play(2, 1, $player));

$this->_ttt->setGrid(new Grid());

// and see if we can win if we go diagonal left to right

$this->assertFalse($this->_ttt->play(0, 0, $player));

$this->assertFalse($this->_ttt->play(1, 1, $player));

$this->assertTrue($this->_ttt->play(2, 2, $player));

$this->_ttt->setGrid(new Grid());

// and see if we can win if we go diagonal right to left

$this->assertFalse($this->_ttt->play(0, 0, $player));

$this->assertFalse($this->_ttt->play(1, 1, $player));

$this->assertTrue($this->_ttt->play(2, 2, $player));

}

In my next article we're going to set up our classes that should turn this test into a success. In the mean time, I challenge you to figure out how the code might look like. And if you want, share that code with everyone by posting it on pastebin.com, pastie.org or using github's gist.

Quality Assurance on PHP projects - PHPDocumentor feedback

2011-08-07T22:28:00.001+02:00

First of all, thank you all for the enormous feedback I got on my latest article on documentation of code. I got a lot of comments on the usage of PHPDocumentor for the following reasons:

the project seems to be no longer maintained
it's not ready for php 5.3
it uses too much resources when using it on big projects

I have to agree that these reasons are valid enough to step away from PHPDocumentor as a tool for documentation purposes and look for a better alternative. So I've investigated one tool most people have commented on or tweet-ed/facebook-ed/g+-ed on: DocBlox.

Before I start a flamewar, I'm all for investigating more tools as time permits me, but these are my first impressions on the tool that had the most buzz in my personal social zone. If your tool of preference is not listed here, write an article on it and put the link here in the comments (or ping back to this article in your own post).

DocBlox seems to be the youngest project of all the various projects suggested to me, but gets a lot of support from major players in the field of PHP and is supported by my favorite build tool Phing (a tool I'll describe in detail in another article).

Installation

You can simply use PEAR to install DocBlox.

user@server $: pear channel-discover pear.docblox-project.org

user@server $: pear channel-discover pear.michelf.com

Select a package you need, in this case docblox/DocBlox-0.12.1 as the project is still in beta (when writing this article) and version DocBlox-0.12.2 has some issues

user@server $: pear install -a docblox/DocBlox-0.12.1

Usage

DocBlox is pretty simple in it's usage and works indeed better than PHPDocumentor, although I had to contact the project lead Mike van Riel (@mvriel) regarding a dependency error on Zend Framework, but it should be fixed now or any time soon.

My dear friend Matthew Weier O'Phinney (@weierophinney) had taken up my challenge to write an article about the usage of DocBlox and I have to say, it's a very good introduction that allowed me to use it immediately.

As a result, I was able to test-run both PHPDocumentor and DocBlox using Phing resulting in a small win for DocBlox. I haven't made a true benchmark test including memory consumption, cpu usage but I think that someone with more sysadmin background knowledge can easily set it up to give a more in-depth detail on which tool performs the best.

Quality Assurance on PHP projects - PHPDocumentor

2011-07-26T23:28:00.002+02:00

It goes without saying people should document their code so that after a few weeks, months, years they still know what they did initially and why. Besides providing a mental note in the code, it also helps your IDE to figure out what your class is all about, which parameters should be used with the methods and what their return types are.

But theory is not always reality and unfortunately I've come across too many lines of code that were just lines of code, no comments or annotations provided. So, in best cases I could guess the types and parameters, but in many it was too obfuscated. I already talked about usage of a code sniffer like PHP_CodeSniffer in my previous post where you can validate the usage of comments in the code. But forcing developers (using a pre-commit checker) into writing documentation with their code is not really a good thing. Once people are forced in a corner, they tend to figure out ways to escape and your whole idea to deliver better code goes out the window.

As a consultant I face many situations where code is not documented or not documented enough, and the top 5 excuses I always get are:

writing documentation is not requested by the customer
no time, too many things need to be done between releases
too much work, and no one looks at the code anyway
why should I?
we charge extra for documentation, but the customer doesn't want to pay it

Like I said, these are mere excuses. I'm not here to judge these people, but I have to emphasize these excuses lack a real fundament to be acceptable in a professional environment. Maybe I'm taking to much pride in my "craft" as PHP developer, but don't you want to offer your customers the best you're company can provide?

Let's turn things around and imagine a new developer joins your team. Wouldn't it be great if you had documentation that could create complete documentation on the source code so it's easy to get into the flow of things? And when looking at the code in their favorite IDE whenever they access existing code, wouldn't it be great they could see instantly what parameters are used for a certain method or function with a brief explanation why it's useful? Maybe that's why I consider writing documentation part of writing code, invalidating all 5 excuses mentioned earlier.

Documentation 101

Writing documentation alongside your code is really not that much of work when you think of it. For all classes, you probably have a template that you can use that details your library of code components.

<?php
/**
 * My Awesome Library
 *
 * This library provides additional functionality and resources
 * for our standard framework [fill in your favorite framework]
 *
 * @category My
 * @license Copyright 2011 © My Company, Inc. - All rights reserved
 */

When you actually write your class components, just explain in short what they do and why they've been created.

/**
 * My_Amazing_Component_Class
 *
 * This class provides amazing functionality that extends the framework
 * that's being used by this company.
 *
 * @package My_Amazing
 * @subpackage My_Amazing_Component
 * @version $Id:$
 */
class My_Amazing_Component_Class
{
}

Once you get to the point where you write the method, you only need to provide some additional information about what it does, what the parameters are, the return types and if they throw exceptions or not

/**
 * We need to take two parameters to figure out which is the location
 * that we want to display on the map.
 *
 * @param float $latitude The latitude of the spot
 * @param float $longitude The longitude of the spot
 * @return string The link that displays the spot on a map
 * @throws OutOfBoundsException When values are invalid
 */
public function findTheSpot($latitude, $longitude)
{
}

As you can see, not really difficult to get the documentation in place and when you do it immediately you don't even waste too much time writing it.

Automated API documentation

If you have the documentation in place, there are tools out there that allow to generate API documentation quickly and easily. There are less known but very promising tools like Doxygen, DocBlox, phpdocgen and many more. But the most known is still PHPDocumentor. The tools that were mentioned here all have their pros and cons, but their usage is pretty simple and their outcome is exactly what you need to have good documentation of your source code.

PHPDocumentor is easy to use and requires just a couple of parameters to generate high quality API documentation.

user@server $: phpdoc \
  -o HTML:frames:earthli \
  -ric docs/README.txt \
  -ti "PHPDocumentor Example" \
  -dc MyCompany \
  -dn My_Amazing \
  -d application/models,application/forms,library/My \
  -i *.phtml \
  -t docs/api

Options used here:

-o HTML:frames:earthli defines the template to use, in this example we use the framed earthly HTML template
-ric docs/README.txt defines the README, INSTALL and CHANGELOG files
-ti "PHPDocumentor Example" provides the title
-dc MyCompany sets the default category if no category is being provided
-dn My_Amazing sets the default package if no package is being provided
-d application/models,application/forms,library/My defines the directories that contain the php code you want to document
-i *.phtml defines files that should be ignored when rendering
-t docs/api defines the location where the API should be generated

Running it on command line will look more or less like this

The result of it is that you get very nice documentation that can be handed out to all developers on your team, third party service providers building on top of your applications or new people on your team.

As you can see, isn't it great to have documentation with your code that requires not much of additional work? Don't forget, it's not just great to create smashing API documents, but it also helps your IDE as it will be able to give your more detail what kind of parameters and methods your classes provide and need.

Quality Assurance on PHP projects - PHP_CodeSniffer

2011-07-17T23:10:00.000+02:00

PHP_CodeSniffer is probably the most convenient tool out there to analyze your source code and to verify it complies to company policies. Although it's debatable why source code should follow strict guidelines, it's only a matter of time before you discover yourself that it pays off to have a code base that appears to be written by one developer.

The first question you have to ask is what standard are you going to implement. There are several standards already packaged with PHP_CodeSniffer, but are they useful within your company? Maybe you want to extend or override some standards with your own implementation. Do remember, the standards supplied with PHP_CodeSniffer have been negotiated over and over by the developers for ages. So if you want to define your own standards, be warned that it can be a long and tedious track before you can agree on a specific standard.

Installation

Installing PHP_CodeSniffer is easy when using the PEAR framework. Make sure you have installed and upgraded the pear libraries that come with your OS. After that all you need to do as root or Administrator is the following.

user@server: $ pear install PHP_CodeSniffer

Or you can go to the download page of PHP_CodeSniffer and download the source package yourself and install it the way you want it. In most cases, the PEAR installation is a more elegant, easy way to install the tool.

Configuration & Execution

PHP_CodeSnifferdoesn't require much configuration, but you have to decide on which coding standard you want to check the code base.

Standards provided by PHP_CodeSniffer are the following:

Zend
PEAR
PHPCS
Squiz
MySource

user@server: phpcs --standard=PEAR /path/to/php/sources

But as stated, you can also define your own standard and provide the base path of the repository on command line

user@server: phpcs --standard=/path/to/my/standards /path/to/php/sources

There are a lot of extra options provided with this tool, but let me focus here on the more important ones you might find useful in your day-to-day usage of PHP_CodeSniffer.

Ignoring files and paths

If you have a couple of external libraries or test scripts in your PHP projects, you might want to exclude them because they're not really part of your concerns. Wouldn't it be easy to just exclude them from the analysis? The following command will exclude paths you have no interest in.

user@server: phpcs --standard=PEAR --ignore=*/tests/*,*/library/Zend/*

Output options

Sometimes you require a different report than the default report that covers all information. Maybe you require a simple summary, a blame report, source report or a report formatted in XML or CSV for usage in another tool. It's only one option away.

The summary report:

user@server: phpcs --standard=PEAR --report=summary

The blame report (requires project to be checked out from a Subversion server):

user@server: phpcs --standard=PEAR --report=svnblame

More on these report formats can be found on the documentation pages of PHP_CodeSniffer.

Roundup

Running PHP_CodeSniffer on the command line is a very convenient way to investigate if the source code is following the standards everyone has agreed upon.

You can also set it as a pre-commit hook for your revision control system, but in my experience it has a negative effect on the productivity of the development team. But it never hurts to try it out and see for yourself if it's a positive step or causes frustrations. A full description on how to set it up for Subversion is explained on the SVN pre-commit page of PHP_CodeSniffer.

When you want to ensure everyone on your team follows the standard policies of your department or company, PHP_CodeSniffer is a great tool to identify where developers need to modify their code so it complies.

Quality Assurance on PHP projects - PHPLint

2011-07-14T23:13:00.002+02:00

PHP Lint
PHP Lint is probably the easiest way to validate your code on syntax errors, but it's also the most overlooked feature of PHP on command line.

Provides a convenient way to perform only a syntax check on the given PHP code. On success, the text No syntax errors detected in is written to standard output and the shell return code is 0. On failure, the text Errors parsing in addition to the internal parser error message is written to standard output and the shell return code is set to -1.

This option won't find fatal errors (like undefined functions). Use the -f to test for fatal errors too.
Quote taken from http://www.php.net/manual/en/features.commandline.options.php.

Example of detecting failures only
user@machine: $ /usr/bin/php -l /path/to/myfile.php

Example of detecting failures and fatal errors
user@machine: $ /usr/bin/php -lf /path/to/myfile.php

Since this tool also returns numeric return codes, you can use it immediately as a pre-commit hook of your favorite revision control system like Git or Subversion. And with PHP on command line, you can create your own hooks with PHP.

Example of a Git pre-commit hook taken from Travis Swicegood's article "Don't submit that error" on the PHP Advent pages.
#!/usr/bin/php

// author: Travis Swicegood
// link: http://phpadvent.org/2008/dont-commit-that-error-by-travis-swicegood

$output = array();
$return = 0;
$php = '/usr/bin/php';

exec('git rev-parse --verify HEAD 2> /dev/null', $output, $return);
$against = $return == 0 ? 'HEAD' : '4b825dc642cb6eb9a060e54bf8d69288fbee4904';

exec("git diff-index --cached --name-only {$against}", $output);

$filename_pattern = '/\.php$/';
$exit_status = 0;

foreach ($output as $file) {
    if (!preg_match($filename_pattern, $file)) {
        // don't check files that aren't PHP
        continue;
    }

    $lint_output = array();
    exec("{$php} -lf " . escapeshellarg($file), $lint_output, $return);
    if ($return == 0) {
        continue;
    }
    echo implode("\n", $lint_output), "\n";
    $exit_status = 1;
}

exit($exit_status);

Example of a SVN pre-commit hook I use myself
#!/usr/bin/php

/**
* Script that processes your code before it's committed to a Subversion
* repository.
*/

/**
* @var string Contains the path to the repository
*/
$repo = $argv[1];

/**
* @var string Contains the ID of the transaction
*/
$transaction = $argv[2];

// Define the command line tools here
define('PHP', '/usr/bin/php');
define('SVNLOOK', '/usr/bin/svnlook');
define('GREP', '/usr/bin/grep');
define('AWK', '/usr/bin/awk');

/**
* Checks for commit messages and sees if they are present. More fine
* grained validation of commit messages can be provided here. If a
* correct message was given, the function returns false. In all other
* cases it will return an error message.
*
* @param string $transaction The ID of the transaction
* @param string $repo The path to the repository
* @return bool|string
*/
function checkCommitMessage($transaction, $repo)
{
    $message = false;
    $log = SVNLOOK . " log -t {$transaction} {$repo}";
    $commitMessage = null;
    exec($log, $commitMessage);
    if ('' === (string) $commitMessage[0]) {
        $message = 'Required commit message is missing' . PHP_EOL;
    }
    return $message;
}

/**
* Checks the syntax of PHP Code with PHP Lint. If no errors where
* detected, it will return false. In all other cases, it will
* return the error messages
*
* @param string $transaction The ID of the transaction
* @param string $repo The path to the repository
* @return bool|string
*/
function checkSyntax($transaction, $repo)
{
    $messages = array ();
    $result = null;
    $return = false;
    $changed = SVNLOOK . " changed -t {$transaction} {$repo}|"
             . GREP . " \"^[UA]\"|"
             . GREP . " \"\\.php\$\"|"
             . AWK . " '{print \$2}'";
    exec ($changed, $result);
    foreach ($result as $file) {
       $phpLint = array ();
       $lint = SVNLOOK . " cat -t {$transaction} {$repo} {$file}|"
             . PHP . " -l 2>&1";
       $error = exec ($lint);
       if ('No syntax errors detected in -' === $error) continue;
       $messages[] = "{$file} contains PHP syntax errors";
    }
    if (!empty ($messages)) {
        $return = implode(PHP_EOL, $messages);
    }
    return $return;
}

/**
* Checks return values of these pre-commit functions and returns
* the return code: 0 for no messages and 1 in any other case.
*
* @param bool|string The message output of pre-commit functions
* @return int The exit code
*/
function getExitCodes($message)
{
    if (false !== $message) {
        file_put_contents('php://stderr', $message);
        return 1;
    }
    return 0;
}

$exitCodes = array ();
$exitCodes[] = getExitCodes(checkCommitMessage($transaction, $repo));
$exitCodes[] = getExitCodes(checkSyntax($transaction, $repo));

if (in_array(1, $exitCodes)) {
    exit(1);
}
exit(0);

Once you have a pre-commit hook in place, you don't have to worry that you commit code contains errors and might cause a failure for other developers in your team. The revision control system will notify you about any failures.

Quality Assurance on PHP projects - Introduction

2011-07-14T12:56:00.000+02:00

Quality Assurance has become an increasing important part of web application development, especially with PHP applications. When I look back in history it was common people just deployed web apps and tested it with a browser on the production server. We all know this process couldn't cover all possible user interactions and many bugs were reported back by end users the days after the deployment of a new release.

Luckily there are a lot of tools available that allows you to increase quality of these web applications, and the best part is they are all based on PHP! Let's have a quick look at what tools are interesting to start improving quality assurance on your PHP projects.

These series will cover most of the tools that will allow you to ensure your PHP projects will have an increased quality and your developers become more confident in their work.

If you want to know more about increased quality and better code, I can recommend reading the PHP QA Book, written by Stefan Priebsch and Sebastian Bergmann. It's official title is "Real-World Solutions for Developing High-Quality PHP Frameworks and Applications" published by Wrox Press (ISBN 978-0-470-87249-9).

In these series I do want to dig a little deeper in tools you might have heard of or concepts you agree are important, but are too high-level to comprehend. I also would like to open up a discussion to see if these tools are giving you the expected results or not.

book review: php development in the cloud

2011-05-25T17:12:00.001+02:00

Cloud computing is no longer a buzz word, a hype that's been shouted at many technical conferences. No, it has turned into a real business model many people make a living off. And in that perspective I started exploring the world of cloud computing about a year ago. I also teamed up with Microsoft to promote and explore their new Windows Azure platform and even co-organized a contest deploying PHP applications on the Microsoft cloud solution.

A couple of weeks ago, my dear friend Cal Evans asked me to review the book "PHP Development in the Cloud" written by "Ivo Jansch" and "Vito Chin". I accepted as I was very interesting in exploring more of the cloudy world I just found myself in the middle of. Another reason was that both authors were fellow co-workers at Ibuildings back in the day. I promised this would be an objective review seen through the eyes of a developer just started exploring the mystifying world of cloud solutions.

The book
Let me say the book is a fun read. You can take it up to your bedroom as late-night read, read during lunch or even in the garden when the kids are playing about. It all evolves around an photo managing application that uses the power of the cloud to process uploaded images and manage them in a new distribute way. Both Ivo and Vito build up the story where they take one feature at the time and use one of the provided cloud platforms to facilitate or expand the application's functionality.

They also explain in plain words the different cloud solutions that are being offered these days and throw terms at you like IaaS, PaaS and SaaS with a detailed description why you would choose this specific cloud architecture followed by code examples. And this little extra attention to detail is something I could really appreciate as I was exploring these architectures but couldn't tie it to useful use cases why I should choose architecture A for this, but B for that. I'm glad Ivo and Vito cleared this fog for me.

At the end of the book you have a functional photo managing application that uses cloud solutions from different cloud suppliers, each with it's specific usefulness. I think that working out the example code and playing with it was what I needed to get the clue as I'm more focussed on hacking code.

The good
Like I already explained in my introduction, this book is well written and the order of chapters make it very easy to expand functionality step-by-step. If you're already familiar with cloud solutions, this book gives you some hands-on examples you can try out on different cloud platform architectures so you can decide which vendor provides the best solution for your needs.

I also enjoy seeing various references to other open-source tools that allow you to fine-tune and optimize your application, infrastructure or platform you want to run your application or feature on.

The bad
Although the book was well written and examples were clear and understandable, I found it hard to get some of the examples deployed on cloud solutions I haven't played with before. Luckily the internet is a good resource finding solutions to issues that crosses your path in the book. But I do want to state a small warning that if you're absolutely new to cloud development, the exercises in the book might frustrate you as you have to do additional searches to get it all working.

The ugly
Although this book is complete in describing all features of cloud architectures and solutions, I do miss a little disclaimer that indicates the examples are written by technology experts and require some knowledge on some of the implementations they use. Even for me some things I had to reread as I have no degree in Computer Science and some of the concepts were unknown to me. In my case, Google was my friendly teacher to bring me back up to speed.

Conclusion
If you're doing PHP and you're deploying apps on cloud technology, you'll find this book very interesting as it gives you some specific usages for each of the cloud solution providers. If either PHP or cloud technology is new to you, I'd recommend to get up to speed first before you jump into the dark.

Twitter and wrong business decisions

2011-03-16T17:42:00.000+01:00

You've must have been on a trip to Mars if you haven't heard about the ordeal of Twitter, saying they close down their services to give it's customers (???) a consistent user experience. In short, they don't want external developers to further develop applications on their API.

This blog article is not about bashing some more on decisions made by Twitter's management and VC's, but to open up a discussion to see if there's no better value to be found for the company to make money without killing innovation. I'd like to know your points of view on this discussion, maybe not to save Twitter, but the next best thing that comes along feeling pressure of VC's wanting to see money for their hard invested money.

If I was a VC or a major stockholder of Twitter company, I'd think twice on killing competitive client developers! [Editorial: I'm no VC nor stockholder, but I do run a business]

First of all you don't have the world geniuses working at Twitter, so you might kill innovation that could bring your service on the next level. I love how CoTweet allows teams to share one twitter resource and delegate tasks to each other. This is just one of the many innovations that sprung out of nowhere just because of the existence of Twitter.

Adds, good to have them but the revenue you earn on adds is still peanuts compared to other solutions, although in the case of Twitter those are a lot of peanuts. Don't use a stupid bar that annoys people (because it's intrusive and unwanted). Inject an add in between every five or ten tweets, like commercials do on TV or in the newspaper. Twitter is the source, so it's easy to implement it. You can even have trending, profiled or geolocated ads send to individual users as Twitter has all that data. Bang! There's some real money to be found.

The added value for Twitter can also be found in it's eco-system, as "to tweet" is generally recognized as a verb. Take a look at GitHub's business model! They've a free platform to share code with the world, but charge for private use. I am sure there's a lot of potential right there, as more and more people are so familiar with sending out a tweet, it can co-exists within companies as their own private twitter flow. Even more, for enterprizes like newsmedia it can also be a business model to have a "sticky" tweet to give them extra attention when major events occur (like we see now in Japan). Even give international aid services a "place" to show where people can contribute, but I suggest to make that a free service.

One thing I do want to say to the folks over at Twitter is this: you have a huge user base and you might keep it for a very long time. But don't forget, it can all be over when someone comes up with the next best thing. You've provided a service that's been used to provide event coverage as it happened, crumbled governments in North Africa, witnessed thousands of reunions of people being at the same spot and so much more. Developers are building new tools on top of that for giving people an added experience on top of what you've originally set up. Closing the doors now on those developers is not just acting as a jerk, but is also a motivation for developers to come up with the next best thing a whole lot quicker.

Let's talk and see how you can become again the hero you used to be.

Book review: CMS Design Using PHP and JQuery

2011-02-23T14:31:00.000+01:00

A couple of weeks ago I got a request from Packt Publishing to review the book "CMS Design Using PHP and JQuery". I accepted the offer because we're using more and more JQuery in our applications these days and I thought this book would give me a better insight in how to best use JQuery.

After receiving the book I started reading it. But right from the start the author displayed bad practices and mis-use of PHP. Reading the book from front to back, the author Kae Verens (@kae_verens) has confronted me with bad use of variables (like $a, $b, $c), bad use of PHP structures and a complete wrong approach of using JavaScript, where JavaScript should enrich an application instead of incorporating business logic.

The good:
It was nice to see JQuery has a variety of plugins to get things done, most of the plugins discussed in the book were developed by the author himself.
I do like the way Kae Verens (@kae_verens) breaks up a CMS basic functionality and targets it one by one to describe it's functionality and purpose. Without the code samples, this book is a good guide for anyone who wants to build a home-grown CMS.

The bad:
It's not bad, it's worse!

The ugly:
As already stated in the introduction, this book is a complete contradiction to the things we try to promote. Clear separation of business logic and presentation layers (where JavaScript is another presentation layer) has gone out of the window in this book.

Since the audience for this book are beginner to intermediate PHP developers, I can only curse at the author to be more responsible. Never use meaningless variables like $a, $b, $c!!!

Filtering and Validation of received data was something I missed in the code.

Another thing, if you use SPL functions like DirectoryIterator to traverse a directory on your filesystem, use the SPL methods that come with it (e.g. $dir->isDot() to verify if it's a "." or "..").

At the end of the book the author says this application only works on a *NIX platform. I think this statement reflects how this application is build: poor design.

Conclusion:
After reading this book, I should advice Packt Publishing to put a sticker on it "Warning: explicit content - bad coding practices" as this book is dangerous in the hands of novice PHP developers.

I'm very sorry for the authors and Packt Publishing as the topic of this book is very promising and could be a good read for everyone, but at this point with this type of coding I strongly advice people NOT to buy this book. Maybe a next edition…

DragonBe's PHP blog

UA Testing with Selenium and PHPUnit

What is Selenium?

Why are they important?

Disclaimer

Setting things up

Overview of what we're doing here

Step 1: Verify an issue from bug tracker

Step 2: Fix the reported issue and test again

Step 3: Convert to PHPUnit test

Step 5: Set up Selenium Server

Step 6: Modifying your PHPUnit Selenium Test

Step 7: Testing with multiple browsers

Closing Remarks

Authentication

Multi platform setup

Dom changes

Recommended reading

Survived php tek 2013

Look mama, no databases

Route default is not defined

Learning lessons at ZendUncon

ZendCon 2012

Returning from PHPNW12

Tutorial Day

Hackathon evening

Conference

Conclusion

Microsoft Hackathon at PHPBenelux Conference 2012

Configuring Zend Framework apps for Windows Azure

Databases

Sessions

Caching

Storage

Next

Windows Azure for PHP developers

Introduction

Windows Azure

Developing for cloud

Operating System

Data Storage

Other considerations

Next

Related links

PHPBenelux Conference 2012 Announcement

Pfcongres 2011 wrap up

Quality Assurance on PHP projects - PHPUnit lessons learned

Quality Assurance on PHP projects - PHPUnit part 4

Quality Assurance on PHP projects - PHPUnit part 3

Quality Assurance on PHP projects - PHPUnit part 2

Quality Assurance on PHP projects - PHPUnit part 1

Quality Assurance on PHP projects - PHPDocumentor feedback

Quality Assurance on PHP projects - PHPDocumentor

Documentation 101

Automated API documentation

Quality Assurance on PHP projects - PHP_CodeSniffer

Quality Assurance on PHP projects - PHPLint

Quality Assurance on PHP projects - Introduction

book review: php development in the cloud

Twitter and wrong business decisions

Book review: CMS Design Using PHP and JQuery