Fun with Travis CI and PHP projects

I know I should have done this a long time ago, but I finally got my hands dirty with Travis CI.  I wanted to set up a php project on github to use Travis CI to monitor the status, in case I forgot to run the tests prior to pushing.  Unfortunately it was not as easy as it’s made out to be.  But now that I’ve done it once, it’ll be easier next time.  So, here is how I tackled it.

First, creating an account and getting started was easy.  I simply clicked the “sign in” link on the Travis CI site and entered my github credentials which authorized Travis CI to connect to my account. (the site informs you exactly what Travis CI will have access to)  Once that’s done Travis gets all my repos, so I can then activate them for Travis CI.  If that doesn’t happen automatically there is a handy “sync now” button to coax Travis CI.

NOTE: To connect public repos you would use https://travis-ci.org, while for private repos you would use https://travis-ci.com.  While pubic repos are free private ones cost money, though you do get 100 pushes free to get you started.

Second, it’s now time to click the + and add a new repo to be tracked by Travis CI.  After clicking you will be presented with a list of your repos to choose from.  It is simply a matter of turning the repo ON by clicking the switch.  I also clicked the wrench to select the option to “Built only if .travis.yml is present”.

Travis CI add repo

The structure of the app I added looks like this: (including all files needed for travis and unit testing) https://github.com/adamculp/api-consumer

Application structure

Third, I needed to create the .travis.yml file with the directives needed to make it all work.  Here is what my file looked like.

travis.yml file

Pretty simple.  Here is what it all means: I specified what language to use (php), and what versions of the language to test with (5.3, 5.4, and 5.5), I also instructed to have Composer install prior to any other scripts run (needed to ensure there was an autoloader, created by Composer), and finally I add the phpunit command and tell it where to find the phpunit.xml file (in this case it was in the tests directory).

Fourth, ensure that PHPUnit runs as expected locally.  Yes, you will need unit tests on your code.  That’s like one of the main reasons to do this in the first place.  Here is what my phpunit.xml and bootstrap.php look like:

phpunit.xml file

The phpunit.xml file is fairly simple.  It informs where PHPUnit can find the bootstrap.php file (same directory as a the phpunit.xml), and sets a whitelist of directory where code can be found (some use a blacklist and specify not to use the /vendor directory), and what directory to find tests in (the current directory).

phpunit bootstrap.php file

The bootstrap.php file specified by the phpunit.xml file is even simpler, as it only specifies where to find the autoload.php file created by the Composer install.

Fifth, take a quick peek at the settings for the repo on github and you will notice that Travis CI should be already set up and ready for something to be pushed.

github settings

Final, that’s it!  That is everything needed for Travis CI.  Of course this example is very simplistic, since the repo and tests are only on a single wrapper class I created.  But it’s good enough for a start, and if you need more the documentation is pretty good.  With these files created, all that remains is for me to commit changes to git, then do a push to origin at github.  Once the push to origin happens a Travis CI trigger at github fires and informs Travis CI to create a new build on a VM (virtual machine) then run the tests on the newest code.  After Travis CI finishes it lets you know with an email, and through the site. (green = good)

Travis CI feedback

One last thing you may want to do is add the Travis CI image to your README.md at github.  This will allow you and others to see whether the current master branch had a successful build, or if it failed.

[![Build Status](https://travis-ci.org/adamculp/api-consumer.svg?branch=master)](https://travis-ci.org/adamculp/api-consumer)

Travis CI build status indicator

Enjoy!

PHPUnit, Composer, PHPStorm, Oh my!

Installing PHPUnit within a project via Composer, then running tests through PHPStorm is not an intuitive process. However, with the right steps it’s actually pretty simple. Here is my story:

To launch the call for papers for the SunshinePHP Developer Conference it was a pleasure to use the OpenCFP project as a starting point rather than creating the entire thing from scratch.  While the project is still a “beta” with a few wrinkles to get ironed out, it’s still a pretty nice effort. (I have a pull requests pending, and another to submit.  Love open source!)

For my CFP I wanted a few more fields of information than the “out of the box” setup, so I quickly added them to the app.  However, doing this meant the included unit tests would fail.  But wait, I hadn’t run the unit tests yet!  I realized immediately how spoiled I had become with today’s modern frameworks with a testing method built in.  This little project did not have that luxury, so I would need to run the tests the old fashioned way, or let an IDE do it for me.  I decided to configure PHPStorm do it. (I’ll do the same for Zend Studio in another post later.)

The way OpenCFP was set up, using Composer, meant that PHPUnit was already placed in the /vendor directory as a requirement in the composer.json.  So rather than taking the lazy way out and using the PHPUnit already installed globally on my system, I wanted to use the latest PHPUnit within the project.  This requires 2 setup steps in PHPStorm.

Step 1

To start I needed to inform the IDE where to find the Composer autoload file and leverage the awesome PSR-0 goodness to autoload PHPUnit in the /vendor directory.  To do this I open the Settings via the icon on the toolbar, or by using the File->Settings menu item, or hitting the Ctrl+Alt+S keyboard shortcut.  Then in the Project Settings (top section) I expanded PHP to get the PHPUnit dialog.

PHPUnit setup in PHPStorm

Step 2

Now I had to add a Run/Debug Configuration for the project.  I did this by clicking on the toolbar dropdown and selecting Edit Configurations.

Edit Configuration

Once the dialog opened I clicked the “+” to add a run configuration, and select the PHPUnit type.

Choose configuration type

Now it was just a matter of adding the directory where the tests reside. (Name the configuration to your taste.)

Location of tests

All done!!!  Now I was able to run the tests simply by selecting the new run configuration defined in the dropdown, and clicking the Run button in the toolbar.

Good luck, and happy testing!

My experience at Code Retreat Miami 2012

This past weekend (Dec. 8th, 2013) I had the great opportunity to experience my first Code Retreat in Miami, for the Global Day of Code Retreat, here is a post about it to help inform others about this wonderful event.  If you have a chance in the future to get to one, it is a “must do”.

The Crowd

I was very surprised there was a large group of Rails developers, and it was nice to see there were a few PHP people from the South Florida PHP Users Group (SoFloPHP) because I had posted the event on the group page.  It’s comical how the Rails folks (I do not refer to them as Ruby developers, because generally they do not know Ruby.) seem to feel their framework makes it the best tool for everything, and completely disregard every other language and framework on the planet to blindly evangelize.  I say “blindly” because Rails users seem to feel the need to push the framework on me by selling wonderful features, as if no other language/framework in the world has it.  (But I digress, that is another subject for another post.)

It was nice to see all of the programming languages represented.  There was PHP, Ruby on Rails, Java, Smalltalk, C#, and even some Python.  This made for a nice mix to view other languages, and how developers of those languages operate.

Overall everyone was friendly and it made for a great day of learning and fun.

What is Code Retreat?

Code Retreat is a single day pair-programming workshop giving a chance to practice Test Driven Development (TDD) while trying to solve a pretty challenging sample application, and follow the 4 rules of simple design.  The sample application is to build Conway’s Game of Life.  I will not try to explain the Game of Life here, so if you are curious you can click the link and learn of it on your own.

For many, the sample application is not an easy one to grasp. I found that all of my pairs kept trying to pre-define the game board size at the beginning of the process, though one of the criteria of the game is to have infinite size. (Even the moderator seemed to be stuck on the concept as well, and claimed that predefining a size was OK, because it is how he did it.  I found this disturbing, but overlooked it.)

Others found that forcing ourselves to write the tests first (TDD) was the hardest part of the event, and that is what it was all about.  The event is all about learning TDD, so it was justifiable that it was the challenging part.  I, for one, was up for the challenge and forced myself to NOT WRITE A SINGLE LINE OF CODE WITHOUT A TEST WRITTEN FIRST TO COVER IT.  Because of this I had 100% code coverage the entire day.

The day is broken down into 45 minute sessions where pairs work together and get as far as they can.  Usually the first 5 minutes are spent as each member of the pair explains how they envision the logic to work out.  Following that the initial tests are built to test the game board, then code is written to satisfy the tests.  Then more tests to populate the board, then more code to satisfy tests.  Then tests to makes sure the 4 rules of the game work, then code to carry them out.  Finally, if you got this far, tests to ensure a new turn is executed, and code to satisfy the test.

One of the parts of the interesting parts of the challenge is that prior to each 45 minutes pairing session the pairs were changed.  Which required that the pairs started over by explaining their vision.  Then at the end of each 45 minute session ALL code was deleted to ensure you start from scratch again.  This included any hand-written notes you took during previous pairings.

Of course, due to the 45 minutes restriction I don’t believe that anyone could truly get the completed application running.  But that is OK.  The purpose of the event is achieved by showing the benefits of pair-programming, using TDD (Test Driven Development), and bringing the various communities together.

Additional requirements

In addition to the rules and steps defined above, there was additional criteria placed upon the teams for each iteration.  The first round had no additional criteria, but each additional round carried a new requirement to follow.  For this event we had the following criteria set for each round respectively:

  1. Team with someone using a different programming language.
  2. 5 lines or less per method/function.
  3. No usage of mouse.  All keyboard shortcuts.
  4. No talking.

The additional requirements made it fun and forced attendees out of their comfort zone, in most cases.  It was interesting to see how, when faced with the difficulties of the additional requirements, it brought the pairs closer together to tackle the obstacle.

Possible Tweaks

While I did find the event awesome, and enabled developers from across the board to experience new things, I would love to do such an event where everyone used the same technologies.  This would enable to see how other developers in our own area of expertise have adjusted their workflow, and allow further learning.

By having a group using the same technologies it would allow juniors and seniors to learn from each other and grow the individual communities.

My Take-away

For me this was an awesome way to force myself to use TDD to develop.  Too often I get in a hurry and just skip right to the code, then come back and write tests later…maybe.  However, I found that by writing tests first during this event I actually got more coding done and ended up with less code overall.  And it also led me to do less back and forth refactoring during coding, that is normally a HUGE time waster.

I also found that pair-programming was very enjoyable, and led to time savings.  The person at the keyboard tended to get more done while the second person was free to think a bit more, rather than being occupied with the manual tasks of writing the code.

In Closing

I enjoyed the event thoroughly, and would love to do it again….today!  If you get a chance to attend one of these events in the future, I highly recommend it.