|
| 0 Comments / Subscribe To Comments |
| Posted: Sep.14.2007 @ 6:35 am | Lasted edited: Sep.14.2007 @ 6:39 am |
Having a solid build process in place is generally viewed as a must for an application of any decent size, with any number of developers, to be a success. The process generally entails multiple steps, such as retrieving the code from the source repository of choice, compiling the code, executing unit tests, and generating documentation via comments found in the code. When setting up this process for a project written in PHP, there is no code compilation, meaning that all errors are found at run time. Personally I feel this makes unit testing even more important. While the end goal for this side project for the Eddy Framework is a completely automated build process, currently there is only a manual build process in place. This works quite well actually, and in this post I will describe how I set up a manual build process for PHP using PHPUnit and PHPDoc.
Getting PEAR Working With XAMPP
I wanted to use PEAR to retrieve both PHPUnit and PHPDoc, so after some very short googling I came across this blog article that describes the processing of getting PEAR and XAMPP working together properly.
Setting Up PHPDoc
The earlier in your project that you can start commenting your code, especially in a standard format such as that recognized by PHPDoc the easier it will be to reap the full benefit of documentation generators. By starting early, properly commenting your code will become second nature, and with each change to method signatures, each new clss that is added, your programs documentation can be automatically updated.
If you find yourself knee, waist or even neck deep in code that is not properly commented, it is still not too late. You can always start by commenting all new methods, or any method that you update, refactor, step through, you name it. Generally I find that when starting to comment an existing code base, it is also good practice to start with documenting your public interfaces, classes, methods and properties. The reason for this is two fold. For starters, this is the code that is more than likely being called from consumers of your application. The second reason is that this will allow you to take another look at your public access points, and really consider whether or not they actually need to be public. That however, is a topic for another posting.
For information on installing PHPDoc, there is an excellent quick start tutorial which can be found on the offical PHPDoc site. The installation process is a breeze, and the command line interface is very easy to use. PHPDoc is documented extremely well, after all how good would a documentation tool be if it was not properly documented? For more information on PHPDoc, the how to tutorial can be found here, also on the offical PHPDoc site.
Unit Testing with PHPUnit
Like proper code comments, the sooner you can start unit testing your application the better. Die hard unit testers live by the motto of "never write a line of code until you have a failing unit test first". Performing a deep dive into Unit Testing methodology is also a topic for another article, but in short you start off by writing a unit test. When the unit tests are run the new test will fail, since there is no corresponding code. At this point you write the code to fix the unit tests. Once the unit test pass, its time to write a new unit test for the next piece of functionality, the test fails, you implement the code, repeat. Don't forget to refactor the whole time.
Getting PHPUnit up and running was a little more difficult than PHPDoc. The actual installation was simple, as it is covered well on the PHPUnit site. The examples however seemed to be a little simplistic. They all assume that you will be running PHPUnit from within the same folder as the unit test. While this may be the case, it did not fit in well with my needs. After poking around in the documentation, I was able to resolve this issue, but it was not explained in the examples. This however is not a big deal, a little RTFM never hurt nobody.
After I had written by first unit test that passed, it was time to tie the unit tests and documentation together.
Creating build.php
The build.php file that ships with the Eddy Framework performs three main steps when run from the command line. First it executes the unit tests that ship with log4php, an excellent logging provider from apache. While the port from log4j is still an incubation project, log4php works very well, with 13 passing unit tests and 7 that are ignored at the time of writing.
The second step is to execute the unit tests for the individual pieces of the Eddy Framework. If build.php is run often and frequently, it will report when a unit test either passes or fails, which will let the developer know if a change they made broke any existing functionality. With a solid suite of unit tests, you can feel comfortable about making a change in the code, since you will know what was impacted as soon as build.php is run.
The last step in the manual build process is to kick of PHPDoc, which runs through the code base and generates full documentation for your program. Command line options are passed to PHPDoc to tell it what folders or files to ignore, what format to generate the documentation in (html with frames, html without frames, xml, chm, pdf are all supported), and finally where to place the generated files. For the Eddy Framework I chose HTML, and place the documentation on the public site. For me to real benefit to this is the generated documentation serves as the API Docs for the framework. No longer do I need to go back and constantly update static documentation with each change I make - PHPDoc handles that for me.
Calling build.php
Now that build.php is set up, all a developer needs to do is run the PHP script from the command line. The script takes one optional argument, which is the path that PHPDoc and PHPUnit were installed into by PEAR. If the folder is not in your PATH, then you can specify it to the build script. Once the build script runs, you will easily be able to tell if you latest change broke and existing unit tests, if your new unit tests ran successfull, and finally your documentation will be generated.
The full code to the most current version of build.php can be found here.
Conclusion
Having a build process, even if a manual one for starters can really bring a huge benefit to your project. With out much extra work you can catch bugs early and keep your documentation up to date. I always think of the analogy of carrying the food or carrying the trash on a 90 day hike. When you carry the food, sure you have a little more work up front, but as the hike goes on your job gets easier and easier. If you carry the trash, you can blaze down the trail for the first part of the hike, but as you get toward the end your job really gets hard when you are already tired and exhausted. Using unit tests and properly commenting your code is just like carrying the food - you do have to perform a little more work up front, but once the procedures are in place your job gets easier and easier. Without unit tests and code comments, you crank more code initially, but weeks or months into your project when you forget what a certain method does, or what the upstream and downstream consumers are - all the sudden you find yourself carrying the trash. You are never going to be quite sure of what your change is actually going to impact, and worse months later you will have even a greater risk of introducing a breaking change. |
| 0 Comments / Subscribe To Comments |
| Posted: Sep.11.2007 @ 6:12 pm | Lasted edited: Sep.11.2007 @ 8:48 pm |
There has been about a four to five month hiatus since the last drop of the Eddy Framework, and for good, albeit personal reasons. However about two weeks ago I found myself with ample free time again, and was eager to say the least to get started back with the Eddy Framework.
Starting to Code Again
As I started to code the Eddy Framework some more, I quickly remembered several snags that at certain points tended to hinder development. For a little background information, I develop the Eddy Framework using XAMPP, which is a truly amazing product by Apache Friends. For those that have never used XAMPP, I strongly recommend, especially if developing LAMP oriented applications on Windows - which leads me to my second point.
My Linux box died and frankly I have not had the time to get a new one up and running, so I have been using my Windows XP laptop. Since I develop on Windows, host my project on Linux, and the code base is currently written in Perl, I am constantly changing shebang lines when moving the code between environments. This in and of itself is a constant hassle, since either right before a subversion commit, or right after a subversion update, I have to run through each file and change the shebang line to point to the appropriate path to Perl.
The other hassle which I constantly faced with the current code base was the server side XSL processor which was used internally in the framework. The Perl add on for XAMPP comes with XML::XSLT, which is fine for extremely simple XSL transformations, but you will very quickly hit brick walls when using it. Ideally I want to use XML::LibXML and XML::LibXSLT - which are Perl wrappers around the very powerful and quick LibXML parser, an XML library from GNOME. These wrappers are available on my Linux host, but I could not get them to work locally. Once again, more code that had to be modified either right before a subversion commit, or right after a subversion update.
The Search For Alternatives
After about 3 hours of working in the current code base, I grew tired and wondered why I even put up with this nightmare to begin with. The very idea of changing code just to move from environment to environment is bush league, and I knew in order for my product to be successful it had to be nipped in the bud so to speak. I began to search for alternatives, namely Ruby, Python, PHP, C and C++. After about two days of testing out my other avenues, here are the results of my investigations.
Ruby and Python are all in the same boat as Perl, the need for shebang lines, as well as the need for wrappers around LibXML to be installed locally. While I consider both to be good languages, it seemed that neither would work for me given my current requirements. C had no object oriented syntax at all. Both C and C++ would require a lot of code to me either hand written (interacting with cookies, file uploads, etc.) or the downloading and linking of one of several outdated and old CGI frameworks. It seems that no one is really concerned with C/C++ CGI applications anymore. With this being said, it seemed like creating a framework for web applications in C/C++ would have been a waste of time and energy, unless only for an academic practice.
Enter PHP
Once I had marked the other languages off my list, PHP seemed to be the only remaining option. Since it was the last language I had to look at, I really wanted to give it a hard comparison against the current language of choice, Perl. With all the development issues that I did have with Perl, the current code base is fully Perl, which would mean changing languages would require a port before any new code could be introduced. Since this would naturally slow down development time, at least initially, I knew the change would have to be worth it.
I initially chose Perl for several factors. For starters, CPAN is amazing. The sheer number of add ons available to Perl is literally stunning. This also makes Perl itself a smaller language, which has many benefits as well. Secondly, Perl is well documented. A new or even seasoned Perl programmer can find a wealth of documentation by going to PerlDoc, PerlMonks, etc. Perl's inherent use of Regular Expressions was also a huge win for me, as they are used extensively within the Eddy Framework.
With these things in mind, I began to look at PHP. PEAR is the equivalent to CPAN in the PHP world, and right off the bat I was able to download add ons via a command line the same way I am able to do from CPAN. PHP is also very well documented, both online at php.net, and via downloadable help files. The downloadable help files were extremely nice for offline development, especially since the user comments are included.
Another minor win for PHP is that PHP was basically designed for the web, where as Perl is more of an all purpose language. While this is not that big of a deal, it does bear mentioning. One short coming however was that PHP has no namespaces, something which is vital for code separation, preventing class name conflicts, etc. While some might agree that Perl's implementation of namespaces was nothing more than an after thought, at least you can put your code into packages.
With all that being said, PHP did win in two major categories. First, no shebang line at all. Not even a mention. Secondly, LibXML and LibXSL are compiled into PHP5 proper, meaning they work right out of the box. As soon as this was realized the scales instantly turned to favor PHP. Why I did not move in this direction initially almost seemed foolish. With using PHP I am able to move code directly into subversion from Windows, and update my Linux host without any code modifications. I have been porting the Eddy Framework from Perl to PHP over the last week roughly, and so far the processes is at least twice, if not three times as smooth. There have been slight hiccups due to knocking the rust of my PHP knowledge, but that is not too much of an issue really. As a side note, PHP seems to have pretty decent Regular Expression support.
It is also worth mentioning that currently PHP seems to have a higher adoption rate than Perl, which at the end of the day will hopefully lead to a higher number of developing whom choose to use the Eddy Framework.
Conclusion
At least for me, PHP seems to be a better solution than Perl as the language of choose for development of the Eddy Framework. v0.3.0.1 will mark the first release of the PHP version, and all future releases will be in PHP as well.
I would also like to note that this is not a Perl, Ruby, Python, C/C++ or any other language bash post, this is instead just an account of the factors that lead to my decision to switch languages for what I consider to be a worthwhile framework for creating dynamic web based applications.
|
| 0 Comments / Subscribe To Comments |
| Posted: May.04.2007 @ 3:38 pm |
Continuing on with the coding for v0.3 of the Eddy Framework, another enhancement has been added in time for the drop scheduled for this weekend. This feature solve one of the major issues with Web 2.0 programming - what happens when a remote Data Source goes down?
We all have seen the issue before, you integrate a new API, or consume an RSS feed on your site - only to find out your site is rendered useless for a couple hours because the remote server supplying the data has gone down. In an effort to fix this, if caching is used for any Data Source (as it should be whenever possible for performance reasons), the cache will not be dumped until a response has been received from the remote server. In simple terms, you will be safe guarded against a remote supplier of data which is suffering some downtime.
It is also important to know that this new feature can also be applied to other avenues, such as allowing you to upload new data files, or switch out databases behind the scenes. Since during the switch over process these Data Sources will not be available, the old versions in the cache will be used until they come back online.
Special thanks to John Lovell from CodeValve.com for the idea behind this new enhancement. |
| 0 Comments / Subscribe To Comments |
| Posted: May.03.2007 @ 9:12 pm |
As v0.3 development continues, default values have now been added to the Eddy Framework, and is currently in a live beta testing on LeftTurnSolutions.com.
Default values received the second highest ratings during the vote for the order in which v0.3 requirements should be completed. The poll was open and available to all members of the Eddy Framework News Group.
This new addition to the framework allows users to specify a default value for placeholders specified in a Data Source's paydirt. If this is greek to you, please refer to the Placeholder Tutorial. We are looking to make a v0.2.1 drop some time this weekend which will contain default values and standard/cascading Data Sources. |
| 0 Comments / Subscribe To Comments |
| Posted: May.02.2007 @ 1:51 pm |
Today marked the beginning of development for version 0.3 of the Eddy Framework. A special thanks to those who are members of the Eddy Framework News Group and voted on the order for which the new requirements will be implemented. The first requirement, implementing Cascading Data Sources, also called Standard Data Sources has been completed, and is currently being beta tested live on our site.
Standard Data Sources allow for common Data Sources to be defined in a single location, and used in pages at the same level, or child levels of your site (hence the original term Cascading Data Sources). This new addition to the Eddy Framework allows the DataSourcesConfiguration.xml configuration file to greatly reduce in size, which not only eases maintenance of the file, but brings a performance boost as well.
We plan to make new drop of the Eddy Framework later in the week, or this weekend, once the default values requirement has been implemented in the framework. |
| 0 Comments / Subscribe To Comments |
| Posted: May.01.2007 @ 6:55 am | Lasted edited: May.01.2007 @ 7:22 am |
As the month draws to an end, those at LeftTurnSolutions.com wanted to share with you the stats from our most successful month ever. Granted on the large scale of things our successes are smaller than others, we are still very excited about the traffic and downloads we received.
For the month of April, LeftTurnSolutions.com got 4,289 hits, averaging 143 hits per day. The Eddy Framework, our flag ship product for creating web based applications in a matter of minutes, was downloaded 17 times. This breaks down to 10 for the Windows version and 7 for the Linux version.
Our biggest referrers for the month were our page on the Yahoo Gallery, PageFlakes.com, the Yahoo JavaScript news group, and the Official Left Turn Solutions Development Blog.
We also received many visitors via searches on Google (Yahoo and MSN searches are still no were to be found). Our most popular search terms were eddy framework, eddy framework folder structure and eddy install xampp. The biggest plus about these search terms, is that they are a good indication that people are starting to search for the Eddy Framework by name.
Thanks to everyone who visited LeftTurnSolutions.com and downloaded the Eddy Framework last month. Development has begun on version 0.3 of the framework, which will bring many exciting new features. As always please post any comments to the Eddy Framework News Group. |
| 0 Comments / Subscribe To Comments |
| Posted: Apr.24.2007 @ 10:20 am | Lasted edited: Apr.24.2007 @ 10:29 am |
Over the past week, two applications written with a combination of the Eddy Framework and the Yahoo User Interface library have been published to the Yahoo Application Gallery. LeftTurnSolutions.com and TechNews have both been added to the gallery, and tagged with eddy. In order to submit an application to the Yahoo Gallery, the application must make some use of the YUI or Yahoo APIs. Both applications were developed using YUI, mainly grids, fonts, menu, tabs and tooltips. Of course the server side portion is driven by the Eddy Framework.
Please help support the Eddy Framework by visiting the LeftTurnSolutions.com Yahoo Gallery Profile and vote for one or both of the applications.
Also, if you have created an application using the Eddy Framework and YUI or Yahoo APIs, please add it to the gallery and include the tag eddy. This will allow for your application to be grouped properly, and available in RSS format, which will soon be displayed on LeftTurnSolutions.com and our development blog. |
| 0 Comments / Subscribe To Comments |
| Posted: Apr.20.2007 @ 3:35 pm | Lasted edited: Apr.20.2007 @ 3:46 pm |
After spending the last couple days digging through log files and statistics for LeftTurnSolutions.com, a startling statistic was realized. Of the hundreds of users a day we receive, only about 12 percent move on past our home page, which contains the latest news for the Eddy Framework. This naturally made us realize that the current homepage needs some re-work, in order to give new users a better sense of what the Eddy Framework is, and what it has to offer.
To help us achieve a more Web 2.0 look and feel, we contacted the design specialists at CodeValve.com, who have been working with us over the last week to revamp our existing site. We have been extremely pleased with the new intro page that is currently being designed. To get an idea as to the new look and feel that will be implemented soon, please take a look at the beta version of the main page.
We will be implementing this new look through out the site over the next couple weeks. Please excuse any temporary inconsistencies while the overhaul is taking place. Also, to any new users visiting the site, please realize that we understand our current introduction page does not provide the level of information that we intended. In the mean time, please visit the Eddy Framework landing page to learn more about our exciting new framework. |
| 0 Comments / Subscribe To Comments |
| Posted: Apr.18.2007 @ 8:44 am | Lasted edited: Apr.18.2007 @ 8:59 am |
With our documentation phase deadline of April 25th quickly coming around the corner, we have been busy cranking out the remaining tutorials. Last night four new tutorials, written by Jon Herron for LeftTurnSolutions.com were uploaded to the site. These new tutorials are:
Creating Custom Plug-ins for the Eddy Framework
Adding Entries to XslConfiguration.xml
Adding Keys to DatabaseConnections.xml
Using Placeholders for Dynamic Data Source Retrieval
We hope you find them helpful. If you have any questions, comments, etc. please post them to the Eddy Framework News Group |
| 0 Comments / Subscribe To Comments |
| Posted: Apr.13.2007 @ 5:41 pm |
The week has taken its toll, and as a welcome to the weekend from LeftTurnSolutions.com, a new tutorial has been posted to the site. Entitled Creating the TechNews Sample Site, this tutorial walks you step by step through creating a simple mash-up with the Eddy Framework. TechNews is the sample site that currently ships with the Eddy Framework, and is on online RSS feed aggregator that pulls technology headlines from PC Magazine, The BBC, HowStuffWorks and MajorGeeks. TechNews was created in under 10 minutes with 0 lines of server side code outside of the framework. We hope you enjoy the article, and if you have any questions please post them to the Eddy Framework News Group. |
|
|