PHP_CodeSniffer Plugin For Sublime Text 2

Posted on by

On the heels of the DocBlox Plugin for Sublime Text 2 I’ve knocked up another plugin, this time for PHP_CodeSniffer.

This plugin is a little more integrated and intelligent than the last one. This can run the code sniffer over the current file and produce markers in the gutter to show errors, but also use the quick panel to show you a list of clickable errors, which will then take you to that line.

To run the Plugin, right click in the editor (on a php file) and select “PHP CodeSniffer” > “Sniff this file…”

This will then (depending on the settings), produce a list in the quick panel and also markers in the gutter to show where the errors are:

Should you want to see the original report you can look into the console:

As with the other plugins you can configure certain options by clicking through the following menus:

You can configure:

  • phpcs_additional_args - This is the extra information you want to pass to the phpcs command. For example which “standard” you want to run, and if you want to show warnings or not
  • phpcs_execute_on_save - Do you want the code sniffer plugin to run on file save for php files?
  • phpcs_show_gutter_marks - Do you want the errors to be displayed in the gutter?
  • phpcs_show_quick_panel - Do you want the errors to be displayed in the quick panel?

My settings are as follows:

You can install this in one of two ways:

  • Package Control
  • Git – simply checkout the git repo into “~/Library/Application Support/Sublime Text 2/Packages/Phpcs” or the equivalent folder on Windows or Linux.

DocBlox Plugin For Sublime Text 2

Posted on by

It seems that the editor of the moment is Sublime Text 2 and sadly I have to tip my hat to Gary Rockett for showing it off to me one day.. Since that day, I’ve been a 100% convert. I started to create snippets for our internal codebase at work, as I was fed up of searching for examples for common tasks I could never remember to do, but then I saw this tweet from Stuart Herbert about creating general PHP snippets.

One thing led to another and Stuart set the pace by creating:

These are fantastic plugins which I recommend you install. So, I decided to peak into the PHPUnit one to see if I could create a DocBlox Plugin. It turns out you have to write Plugins in Python, which is interesting, since I know very little python. There seemed to be enough code there to get me going, so I now have a working DocBlox Plugin.

Once installed, you simply right click in the side bar menu on items you want documentation for. It can do single files and directories..

DocBlox Plugin Side Bar Menu

And once you click “Generate documentation…” you get the console showing the output:

DocBlox Plugin For Sublime Text 2 Console Output

You can configure where the target documentation should be published via the preferences:

DocBlox menu in Sublime Text 2

and simply update the following options:

DocBlox preferences in Sublime Text 2

There are a few things to point out at this stage:

  • My python skills are not great!! But stick with me, I should be able to fix issues if they arise.
  • Ideally it would be great to then load the documentation in a browser, but I need to do some more reading to see how to do this on all OS’s using Python.

You can install this in one of two ways:

  • Package Control and select “DocBlox”
  • Git – simply checkout the git repo into “~/Library/Application Support/Sublime Text 2/Packages/DocBlox” or the equivalent folder on Windows or Linux.

Don’t just fix the unit tests!

Posted on by

I’m not sure if other people have had the same issue, but I see more and more developers “fixing the unit tests”, rather than understanding why they are broken and the business requirement they were originally testing.

The problem use to be no-one wanted to write unit tests. 18 months on, and now most developers in our department are writing unit tests, however we have this new problem now.

So, a release has gone into production, and all of a sudden we have a broken build. Let’s assume for this post, that sadly, this project (named: Project Oh Dear) didn’t follow all the processes we have in place, such as unit testing and continuous integration using our Jenkins build platform. It happens!

So, what needs to be done? We need to “fix the unit tests”. However, this statement can be taken literally, where the sole aim now is to make the unit tests pass.. Not really understand why they are broken per se, but get them green again so all is well.

To take an arbitrary situation, let’s say that we had an object that kept an internal array of errors that has occurred during an execution of a script and it was fully unit tested to make sure, on error, the internal array is updated to mark such an event. The requirement here being that the errors are ultimately persisted to some datastore somewhere for later interrogation. OK, so the new project, Project Oh Dear, comes along, and the developers aren’t unit testing for one reason or another, and we now have a requirement to on error, log the information to the terminal. Let’s assume there is a misunderstanding and the developers now believe that the original requirement is defunkt, and we now only care about logging to the terminal. I know, I know, maybe someone should have checked, but you know, everyone’s busy!

Project Oh Dear kicks off and this requirement is started.. We no longer need the internal array to persist the errors, so that’s removed, and the on error event now logs to the terminal.. This feature, along with all the other features enters normal human QA processes and passes, and then rolls live.

Broken Unit Tests!

Fix the Unit Tests the magagement say!

OK, so we update the original unit tests to make sure they capture output, and that the output is what we expect.

Committed to version control and that’s it.

Later down the line however, the orignal developers look over the code and realise that at several stages, Project Oh Dear has subtly changed behaviour, and simply removed/changed valid unit tests.

It's time to ditch dial-up. Get up to 20Mb broadband from PlusNet. Free setup now available - terms apply. PlusNet broadband.

The orignal requirement of persisting errors to the datastore was valid, the unit tests failed (quite rightly), but instead of understanding why they failed, the developers “fixed the unit tests” to capture the behaviour that is now in production, therefore ignoring the fact that the broken tests were validly broken!

This is a very simplistic arbitrary example of what is occurring, but the principle is the same. Fixing the unit tests, is very much more than simply make them go green. If you are in the situation of “fixing unit tests”, then you probably have a fundamental issue somewhere else in your processes. If you are the developer assigned to fix broken unit tests, please make sure you fully understand what they were testing, what the business requirements were, and why they are now breaking. I imagine that it is very rare that the unit tests are broken, more so that the production code is somewhat broken.

MongoDB PHPUnit Test Listener

Posted on by

I’ve wanted to look into MongoDB for some time now, but never got the chance until this week. I decided to write a PHPUnit Test listener that could persist some of the test executions I was running locally so I could see progress being made. We have a full Jenkins CI platform at work, however:

  • I wanted to do something with MongoDB
  • I wanted to see progress before I was checking in code
  • I was going to write a front end on top of the MongoDB collection so I have even more exposure to MongoDB

The last point hasn’t been started yet, but it is still my intention to write a little front end to sit on top of the MongoDB data set that has been accruing whilst I run my PHPUnit tests.

This is what the output can produce:

$ phpunit
PHPUnit 3.6.10 by Sebastian Bergmann.

Configuration read from /Users/bselby/git/modules/aRepo/phpunit.xml.dist

............................................................

Execution count stored: 5

Execution Time: 2 seconds @ 2012-02-02 20:51:18
 Suites: 3
 Tests:          60
  - Errors:      0
  - Failures:    0
  - Incomplete:  0
  - Skipped:     0

Execution Time: 1 seconds @ 2012-02-02 20:50:58
 Suites: 3
 Tests:          60
  - Errors:      0
  - Failures:    1
  - Incomplete:  0
  - Skipped:     0

Time: 2 seconds, Memory: 20.50Mb

OK (60 tests, 167 assertions)

Generating code coverage report, this may take a moment.

It isn’t anything special by a long stretch but it did give me a chance to play around with MongoDB, which was ultimately my goal.

You can define the listener in your phpunit.xml file like:

    <listeners>
        <listener class="PHPUnit_Util_Log_Mongo" file="/Users/bselby/git/external/phpunit-testlistener-mongo/PHPUnit/Util/Log/Mongo.php">
            <arguments>
                <array>
                    <element key="mongoConnectionString">
                        <string>mongodb://localhost</string>
                    </element>
                    <element key="mongoDatabase">
                        <string>phpunit</string>
                    </element>
                    <element key="mongoCollection">
                        <string>collection</string>
                    </element>
                    <element key="mongoDocumentCount">
                        <string>5</string>
                    </element>
                    <element key="mongoDocumentDisplay">
                        <string>2</string>
                    </element>
                </array>
            </arguments>
        </listener>
     </listeners>

Obviously you can set the values for all of the above to whatever you want the configuration to be.

The code is here should you be interested in using it.

References

Use version control commit messages correctly

Posted on by

This post represents a conversation I’ve had multiple times with the dev teams I am involved with, and it doesn’t seem to get any better. I’ve “vented” at my wife, who has to listen (It said so in the vows!) but she just beams a beautiful smile back (something that the dev teams don’t do I may add!).

Commit messages really should be meaningful to all who view it.. It might be funny to put messages such as:

commit ce87f8b133f6047ded002d69bd1b2ccf27ab691a
Author: Funny Developer <fail@localhost>
Date: Fri Jan 13 Stupid O’clock 2012 +0000

;-)

But, seriously, is that going to help me try to understand how to unpick the mess you have now got the project into? Does that link to the work you were doing, so I can now try to figure out how to fix it correctly? Does that actually do anything other than bring deep resentment to the developer who wrote it?

Another favourite is 4 commit messages for one piece of work that goes something like:

commit ce87f8b133f6047ded002d69bd1b2ccf27ab691d
Author: Funny Developer <fail@localhost>
Date: Fri Jan 13 Stupid O’clock 2012 +0000

More code review feedback

 

commit ce87f8b133f6047ded002d69bd1b2ccf27ab691c
Author: Funny Developer <fail@localhost>
Date: Fri Jan 13 Stupid O’clock 2012 +0000

Code review feedback

 

commit ce87f8b133f6047ded002d69bd1b2ccf27ab691b
Author: Funny Developer <fail@localhost>
Date: Fri Jan 13 Stupid O’clock 2012 +0000

Small tweak to make it actually work

 

commit ce87f8b133f6047ded002d69bd1b2ccf27ab691a
Author: Funny Developer <fail@localhost>
Date: Fri Jan 13 Stupid O’clock 2012 +0000

Made it work as per requirement

I really don’t need to see that it took 2 code reviews to finally get this onto the project branch, nor do I need to know you needed to make a “small tweak” that included all the original files to make it work.

What would be smashing:

commit ce87f8b133f6047ded002d69bd1b2ccf27ab691f
Author: Mr Committer <winning@localhost>
Date: Fri Jan 20 17:00:00 2012 +0000

Make sure the customer can view all recent invoices, not just the last 5.

 

http://internal.tracking-system.net/TICKET-ID

Fabulous, a message that makes sense, I know what you wanted to achieve and for pure historical value a link to why you were doing the work, so I can track things should I need to. How excellent is that?

I think I know the reason why people don’t understand why this is important – It’s because they have never been put into a situation where they have to solve a version control issue at the last minute, where the buck stops with them, and they have to sort it before the project goes into production. If they ever had to do it, they would have this same conversation with other developers who don’t write decent commit messages.