Beyond Frameworks: The Page

Posted by Stuart Herbert on March 26th, 2011 in Toolbox.

I’ve put together a page on my blog to collate my Beyond Frameworks series of articles about building PHP components into one convenient place. If you’re enjoying the series, you might find it a handy reference page to bookmark.

And if you missed the beginning of the series, why not head on over and see what I’m up to? :)

PS: Thank you to everyone who has left comments or pinged me on Twitter so far. The feedback is excellent to have – more please :)

Comments Off

In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I’m going to look at how to go about creating and working with components.

Earlier today, I created some very basic unit tests for my repustateApi component. Unit tests are an essential part of developing your component, but how do you run them?

Running Your Component’s Code From The Command-Line

Many old-skool developers choose to work largely from the command-line. You can happily run PHPUnit by hand from the command line yourself each time, but if you’re taking advantage of the extra data that PHPUnit can report back on, that soon gets to be a lot of typing! This is where the build.xml file in our skeleton comes in handy …

To run your unit tests from the command line, all you need to do is run the command phing test:

stuart:~/Devel/sental/repustateApi$ phing test
Buildfile: /home/stuart/Devel/sental/repustateApi/build.xml
 [property] Loading /home/stuart/Devel/sental/repustateApi/build.properties

 > lint:

  [phplint] /home/stuart/Devel/sental/repustateApi/src/php/Gradwell/Repustate
Api/Client.php: No syntax errors detected

 > run-unittests:

   [delete] Deleting directory /home/stuart/Devel/sental/repustateApi/review/
code-coverage
    [mkdir] Created dir: /home/stuart/Devel/sental/repustateApi/review/code-c
overage
    [exec] Executing command: phpunit --bootstrap=/home/stuart/Devel/sental/
repustateApi/src/tests/unit-tests/bootstrap.php --coverage-html /home/stuart/
Devel/sental/repustateApi/review/code-coverage --coverage-clover /home/stuart
/Devel/sental/repustateApi/review/logs/phpunit.xml /home/stuart/Devel/sental/
repustateApi/src/tests/unit-tests 2>&1
     [exec] PHPUnit 3.5.3 by Sebastian Bergmann.
     [exec]
     [exec] .EE
     [exec]
     [exec] Time: 0 seconds, Memory: 4.00Mb
     [exec]
     [exec] There were 2 errors:
     [exec]
     [exec] 1) Gradwell\RepustateApi\ClientTest::testCanRetrieveSentimentScor
eForTextByJson
     [exec] Exception: oh dear
     [exec]
     [exec] /home/stuart/Devel/sental/repustateApi/src/php/Gradwell/Repustate
Api/Client.php:209
     [exec] /home/stuart/Devel/sental/repustateApi/src/php/Gradwell/Repustate
Api/Client.php:151
     [exec] /home/stuart/Devel/sental/repustateApi/src/php/Gradwell/Repustate
Api/Client.php:90
     [exec] /home/stuart/Devel/sental/repustateApi/src/tests/unit-tests/php/G
radwell/RepustateApi/ClientTest.php:70
     [exec]
     [exec] 2) Gradwell\RepustateApi\ClientTest::testCanRetrieveSentimentScor
eForUrlByJson
     [exec] Exception: oh dear
     [exec]
     [exec] /home/stuart/Devel/sental/repustateApi/src/php/Gradwell/Repustate
Api/Client.php:209
     [exec] /home/stuart/Devel/sental/repustateApi/src/php/Gradwell/Repustate
Api/Client.php:151
     [exec] /home/stuart/Devel/sental/repustateApi/src/php/Gradwell/Repustate
Api/Client.php:116
     [exec] /home/stuart/Devel/sental/repustateApi/src/tests/unit-tests/php/G
radwell/RepustateApi/ClientTest.php:83
     [exec]
     [exec] FAILURES!
     [exec] Tests: 3, Assertions: 1, Errors: 2.
     [exec]
     [exec] Writing code coverage data to XML file, this may take a moment.
     [exec]
     [exec] Generating code coverage report, this may take a moment.
Execution of target "run-unittests" failed for the following reason: /home/st
uart/Devel/sental/repustateApi/build.xml:108:40: Task exited with code 2

BUILD FAILED
/home/stuart/Devel/sental/repustateApi/build.xml:108:40: Task exited with cod
e 2
Total time: 0.5951 seconds

That went bang in a spectacular way! At this stage, where we have tests but don’t yet have a working Repustate API client, that’s exactly what should happen. As I work through the code, and satisfy the tests, we should quickly get to the point where we have more tests, and that they all pass.

Here’s an example of another component – our CommandLineLib – which has many tests that all succeed, just so that you can see what a successful test run should look like:

Buildfile: /home/stuart/Devel/GWC/CommandLineLib/build.xml
 [property] Loading /home/stuart/Devel/GWC/CommandLineLib/build.properties

 > lint:

  [phplint] /home/stuart/Devel/GWC/CommandLineLib/src/php/Phix_Project/Comman
dLineLib/CommandLineParser.php: No syntax errors detected
  [phplint] /home/stuart/Devel/GWC/CommandLineLib/src/php/Phix_Project/Comman
dLineLib/ParsedSwitches.php: No syntax errors detected
  [phplint] /home/stuart/Devel/GWC/CommandLineLib/src/php/Phix_Project/Comman
dLineLib/DefinedArg.php: No syntax errors detected
  [phplint] /home/stuart/Devel/GWC/CommandLineLib/src/php/Phix_Project/Comman
dLineLib/DefinedSwitch.php: No syntax errors detected
  [phplint] /home/stuart/Devel/GWC/CommandLineLib/src/php/Phix_Project/Comman
dLineLib/DefinedSwitches.php: No syntax errors detected
  [phplint] /home/stuart/Devel/GWC/CommandLineLib/src/php/Phix_Project/Comman
dLineLib/ParsedSwitch.php: No syntax errors detected

 > run-unittests:

   [delete] Deleting directory /home/stuart/Devel/GWC/CommandLineLib/review/c
ode-coverage
    [mkdir] Created dir: /home/stuart/Devel/GWC/CommandLineLib/review/code-co
verage
     [exec] Executing command: phpunit --bootstrap=/home/stuart/Devel/GWC/Com
mandLineLib/src/tests/unit-tests/bootstrap.php --coverage-html /home/stuart/D
evel/GWC/CommandLineLib/review/code-coverage --coverage-clover /home/stuart/D
evel/GWC/CommandLineLib/review/logs/phpunit.xml /home/stuart/Devel/GWC/Comman
dLineLib/src/tests/unit-tests 2>&1
     [exec] PHPUnit 3.5.3 by Sebastian Bergmann.
     [exec]
     [exec] ............................................................ 60 /
 78
     [exec] ..................
     [exec]
     [exec] Time: 1 second, Memory: 5.75Mb
     [exec]
     [exec] OK (78 tests, 407 assertions)
     [exec]
     [exec] Writing code coverage data to XML file, this may take a moment.
     [exec]
     [exec] Generating code coverage report, this may take a moment.
     [echo]
     [echo] The code coverage report is in /home/stuart/Devel/GWC/CommandLine
Lib/review/code-coverage

 > test:

BUILD FINISHED

Total time: 3.7912 seconds

Command-Line Test Run Explained

The component’s build.xml file contains targets – sequences of instructions that you can invoke by using phing. When you run the command phing test, here’s what happens:

  • phing loads the build.xml file in the current working directory. So make sure you’re in your component’s top-level folder when you run phing!
  • build.xml sucks in the build.properties file where we set the component’s name and version number. These properties are in a separate file so that it’s safe to replace build.xml with new versions as we improve the component’s skeleton files in the future (via the phix php-library:upgrade command).
  • phing runs the ‘test’ target in build.xml, which tells it to actually run the ‘lint’ and ‘run-unittests’ targets.
  • The ‘lint’ target does a syntax check on all of your PHP files. As your component grows, and the time it takes to run your unit tests grows too, a quick syntax check can save a developer wasting a surprising amount of time.
  • If the syntax check is successful, the ‘run-unittests’ target runs next.
  • The ‘run-unittests’ target invokes PHPUnit, telling it to use the skeleton’s bootstrap file, and to write out the results in XML format to feed into other tools later on. It also tells PHPUnit to write out code coverage data as HTML. We’ll look at that in a later blog post.

Running Your Unit Tests From Netbeans

If the command-line isn’t for you, don’t worry … the component skeleton is also designed to make it very easy to run your unit tests from inside Netbeans. I’m assuming that it will be just as easy to do this from other IDEs that support PHPUnit, but I haven’t tested any myself.

First of all, you need to setup your project in Netbeans to tell it where your tests are. Open the project’s properties dialog box:

and then set the Test Folder to be your ‘unit-tests’ folder:

Next, open the PHPUnit settings in the project’s properties dialog box, and tick the ‘Use Bootstrap’ box:

and then, tell Netbeans to use the bootstrap file inside the ‘unit-tests’ folder:

so that the PHPUnit settings look like this:

Now we’re all set to run the tests from inside Netbeans. In the project browser, simply right-click on the Client.php file, and select ‘Test’ from the popup menu. Netbeans will run the tests for you, and tell you exactly where they broke:


I hope you find these tools useful, and time-saving!

I’m going to beaver away over the weekend getting several components completed, and will be back on Monday to go through more of the things you need to know if you’re going to successfully go Beyond Frameworks and shift to a component-based architecture. Have a great weekend!

5 comments »

In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I’m going to look at how to go about creating and working with components.

I’ve started work on creating the components for my simple app. The first component is repustateApi, which will be a PHP client for Repustate.com’s semantic analysis API. With the component’s metadata all done, and the decision made to start with unit tests, let’s get the unit tests written and running.

The First Unit Tests

Repustate’s API is extremely simple to use, making it the ideal choice for my first semantic analysis client. It’s very low risk to knock up a client and see if their API does the job; if the API isn’t suitable under heavy testing, and I’m forced to try someone else’s semantic analysis API, I haven’t lost much time in the attempt.

As a result, my initial unit tests can be extremely simple:

namespace Gradwell\RepustateApi;

class ClientTest extends \PHPUnit_Framework_TestCase
{
        public function setUp()
        {
                $this->_apiKey = '';
        }

        public function testCanCreateClient()
        {
                // create the client with a valid key
                $client = new Client($this->_apiKey);

                // did it work?
                $this->assertTrue($client instanceof Client);
        }

        public function testCanRetrieveSentimentScoreForTextByJson()
        {
                // setup
                $client = new Client($this->_apiKey);
                $text = "this is a happy piece of text";

                // do the test
                $score = $client->callScoreForText($text, 'json');

                // evaluate result here
                $this->assertTrue ($score !== false);
        }

        public function testCanRetrieveSentimentScoreForUrlByJson()
        {
                // setup
                $client = new Client($this->_apiKey);
                $url = "http://www.stuartherbert.com";

                // do the test
                $score = $client->callScoreForUrl($url, 'json');

                //evaluate result here
                $this->assertTrue ($score !== false);
        }
}

… and the skeleton class needed to execute those tests is just as simple:

namespace Gradwell\RepustateApi;

class Client
{
        protected $apiKey = null;

        public function __construct($apiKey)
        {
                $this->setApiKey($apiKey);
        }

        public function setApiKey($apiKey)
        {
                $this->validateApiKey($apiKey);
                $this->apiKey = $apiKey;
        }

        public function validateApiKey($apiKey)
        {
                // @TODO
        }

        public function callScoreForText($text, $format = 'json')
        {
                // placeholder
                return false;
        }

        public function callScoreForUrl($url, $format = 'json')
        {
                // placeholder
                return false;
        }
}

Remember, at this stage, all I need to do is create unit tests that

  • can be executed, and
  • will fail

to allow me to model the API that this component will provide to the outside world. By the time I’m finished, both the unit tests and the Gradwell\RepustateApi\Client class will look quite different :)

Where The Unit Tests And PHP Code Goes

In our skeleton, tests go into the src/tests/unit-tests folder, and the PHP code that the component will install into /usr/share/php does into the src/php folder.

Because we’re using a PSR0-compliant autoloader for all components, it’s extremely easy to translate the name of a class into its full filename on disk.

  • Gradwell\RepustateApi\Client goes into the file src/php/Gradwell/RepustateApi/Client.php
  • Gradwell\RepustateApi\ClientTest goes into the file src/tests/unit-tests/Gradwell/RepustateApi/ClientTest.php

This approach means that, if needed, we can scale to hundreds of components inside a single app, and still only need the one autoloader.

The Component’s Folder Structure So Far

If I take the component structure, and dump it out using the ‘tree’ command, here’s a list of which files have gone where:

├── build.properties
├── build.xml
├── dist
│   └── repustateApi-0.1.0.tgz
├── LICENSE.txt
├── package.xml
├── README.md
├── src
│   ├── bin
│   ├── data
│   ├── php
│   │   └── Gradwell
│   │       └── RepustateApi
│   │           └── Client.php
│   ├── tests
│   │   ├── functional-tests
│   │   ├── integration-tests
│   │   └── unit-tests
│   │       ├── bin
│   │       ├── bootstrap.php
│   │       ├── php
│   │       │   └── Gradwell
│   │       │       └── RepustateApi
│   │       │           └── ClientTest.php
│   │       └── www
│   └── www
└── vendor
    └── php
        └── gwc.autoloader.php

In the next blog post later this evening, I’ll show you have to run the tests in your component, both from the command-line, and from inside Netbeans.

1 comment »

In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I’m going to look at how to go about creating and working with components.

In my last article, I finished editing the metadata for my component, and then used the component’s package.xml file to download its dependencies and automatically install them into the vendor/ folder – a local sandbox that we can recreate and destroy at any time.

We can now get stuck into what we all love doing the most: writing code, and that means starting with our unit tests. Why does it?

Why You Should Unit Test Your Component

There are many good reasons for ensuring your component has good unit tests:

  • Components are written to be used by many other developers. Good tests ensure that your components will behave well in the hands of others, which will save them time and enhance their trust in your future releases.
  • Good tests can serve as the best reference documentation for your code. They can show others how your code was intended to be used, in a way that they should be able to easily understand.
  • If you find yourself changing your tests in future releases, it’s a good way of making you pause and just have a think about whether you are actually breaking backwards compatibility without realising it.
  • As bugs are reported and fixed, you can add additional tests for each bug, to make sure that the bug doesn’t sneak back into any future releases (this is regression testing).
  • You can plug your unit tests into a Continuous Integration environment such as Jenkins, to make sure no-one in your team breaks your component with their next code check-in.

These are all reasons that you have probably come across before, and I’m sure you’ll come across them again before too long from many other bloggers. You can watch Sebastian Bergmann, creator of PHPUnit, talk about this at #phpuk2011 if you need further convincing. (Do watch the video, especially if you’re a World of Warcraft fan. His talk at #phpuk2011 was a big hit).

But there is another reason why components in particular need tests, which you might not have seen before, and it’s all to do with how a component is different to hacking on a webapp.

TDD: Unit Tests Come First

Components are well-suited to test-driven design (or test-driven development, if you prefer) because they are standalone little chunks of code. There’s no website for you to point your browser at to test the components by hand. The code inside your component only gets executed when someone writes some code of their own to call your code.

If you don’t write the unit tests, that means the first time your code runs will be when another developer downloads the code and tries it for himself. What do you think is likely to happen? Your code is likely to fail. Is he going to fix your code, or is he going to move on and look somewhere else for another solution?

Seeing as you need to write the tests anyway, why not embrace test-driven design, and write the tests first? Writing the tests first means that you’re already starting to define the API that other developers are going to use. It get you designing right from the very beginning with the end in mind – how your code will be reused.

In this afternoon’s blog post, I’ll show you where to put your tests, and how to run them both from the command-line and from within Netbeans.

Comments Off

In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I’m going to look at how to go about creating and working with components.

In the last article, I edited the build.properties file to set the component’s name and version number. I need to finish setting up the component’s metadata by editing package.xml.

Introducing package.xml

Every PEAR-compatible component needs to ship with a manifest file called package.xml. You can see the the unedited version on GitHub that we’re about to change.

package.xml contains the following useful information:

  • The component’s name, channel, version number, and description.
  • A list of the component’s authors.
  • The component’s license.
  • A list of the component’s contents.
  • A list of the component’s dependencies, including PHP version, PHP extensions, and other components.

(package.xml can hold other information too, but I’ve yet to see them being put to practical use, so we’ll leave them for today and come back to them if needed later on).

In our component skeleton, we need to add some of this data to package.xml, and the rest will be added automatically by the tools when we build a PEAR-compatible package, to save us the trouble of doing it by hand.

Setting Up The Component’s Name And Channel

All PEAR-compatible packages have a fully-qualified name of the form <channel>/<name>. In this skeleton, our tools will automatically inject project.name from the build.properties file into package.xml’s <name> tag when we build the PEAR-compatible package. We just need to edit the <channel> tag in package.xml to point to our server.

As I’m going to publish these packages via our public PEAR channel, I’ve set <channel> to be “pear.gradwell.com”. Don’t worry if you don’t have your own PEAR channel yet; they’re very easy to create, and I’ll look at exactly how to set one up and publish it later in this series.

Setting Up The Component’s Version Number, And Description

All PEAR-compatible packages have a version number. We’ve already set this in build.properties; our tools will automatically inject this into package.xml. (We could have put this directly into package.xml, but the version number is duplicated in a couple of places, and it seems much easier to let the tools deal with that so that we don’t forget to update all the version numbers when we make a new release).

For the description, edit the &lt:summary> and <description> tags. The descriptions get used in the human-friendly HTML page that each PEAR channel has, so they’re worth the trouble of filling in.

Setting Up The Component’s Author

There’s a few tags inside package.xml that tell anyone who is interested who the current author of the component is. This information gets used in the human-friendly HTML page that each PEAR channel has. I’ve set these tags as follows:

<name>Stuart Herbert</name>
<user>stuartherbert</user>
<email>stuart@stuartherbert.com</email>
<active>yes</active>

Setting Up The Component’s License

The <license> tag contains text to say under what license the component has been released. By default, the skeleton sets this to be “All rights reserved.” Whilst I’d love you to opensource all of your components, I wouldn’t like to presume ;)

For our component, I’ve set this tag to say “New BSD license.”.

Setting The List Of The Component’s Contents

The <contents> tag is where the PEAR installer expects to find a file-by-file list of all of the files that need to be installed, along with instructions on where to install them. Each file is flagged as being a specific ‘role’ – script, php code, data file, unit test, website page – and the PEAR installer then decides for you where it will put them. Don’t try fighting it; it has some built-in assumptions that aren’t worth trying to work around.

We don’t need to edit this tag at all. When we build our PEAR-compatible package later on, the tools will manage this section for us. It saves a lot of time and effort, and debugging!

Setting Up The Component’s Dependencies

Finally, we get to the bit that makes it all worthwhile: the list of what this component needs in order to work. By getting these right, we can reliably re-create the entire environment that our app needs with just a single command.

A practical demonstration is needed, I think, because this is probably something you’ve never had the opportunity to do before now.

stuart:~/Devel/sental/repustateApi: phing build-vendor

When I run that command, our tools will download all of the dependencies listed in package.xml, and install them into a folder called ‘vendor’. This gives us a reproducible sandbox, where we can find the correct versions of all the code needed to unit test our component. We don’t have to ensure the right version is installed on the computer; we get our own copy of everything needed. If you develop on shared servers, or even if you end up maintaining a lot of components, this is a real time saver.

If you run that command locally, and look inside the ‘vendor’ folder it creates, you should see that our tools have downloaded and installed the Autoloader package that’s listed in package.xml’s list of dependencies. As we add more PEAR-compatible packages to the package.xml’s dependency list, we can rebuild the vendor folder and install all of the dependencies side by side. I’ve picked the repustateApi component because it will allow me to demonstrate that as we go along.

Please ignore the errors that you will see scroll up the screen when you run ‘phing build-vendor’ at this stage. Unfortunately, the PEAR installer doesn’t seem to have a command to install just the dependencies (i.e. pear install –onlydeps) listed. It’s also trying to install our component’s PEAR-compatible package, which doesn’t exist yet.

The Final package.xml File

You can see the final package.xml file, containing all of the edits listed in this blog post, on Github.

As we work on the component and then release it, we will need to come back and edit package.xml a little more. But we’ve done what we need to, for now, and can get started on creating some code.

My apologies if it seems like a lot of work just to create an empty component and then sort out the component’s metadata. In all honesty, after you’ve done it a few times, you can create a new component in a matter of minutes, and this is work you only have to do the once.

In the next blog post, we’re going to start creating the initial tests for this component.

4 comments »
Page 10 of 17« First...89101112...Last »

This Month

October 2014
S M T W T F S
« Jan    
 1234
567891011
12131415161718
19202122232425
262728293031  

Recent Comments