In the last article we have discovered that our application is at a dead end: PHP 4 has officially been declared dead, we are facing an increasing number of issues with running our application and our code is cluttered. Maintaining – and probably extending – our application is becoming a task that wastes resources and decreases our teams’ motivation to continue this piece of software.

Now we are facing a simple question: what are we supposed to do to keep our application running and our customer(s) happy?

Rewriting our application

If you have been facing the above issues for a while it may seem appealing to start from scratch and rewrite your application. A fresh start, based upon current approaches, throwing away everything we have. There even is the chance to redefine the application specification.

While this may sound good from a developers’ point of view (don’t developers love challenges), it does not smell good from a business point of view.

• Rewrites are expensive: the teams’ resources will be bound to rebuilding everything from zero, and this is expensive. Man-hours are not cheap these days, and it will be hardly possible to convince the boss(es) to invest more money compared to the current maintenance costs of your application.
• Rewrites are a waste of investments: if your application ran for a few years, there is a huge investment involved. Consider a team of three or four developers and a designer in charge for maintaining an application. It is quite an impressive number of man-hours invested, and the Euros or Dollars (or whatever you are paid in) are not earned easy. After all, throwing investments into the thrash is no Good Thing.
• Rewrites ignore existing achievements: over the years the code in your application will have matured, as you very likely faced most issues that could raise during the application lifetime. This is of value, and should not be left behind. After all it is knowledge you gained.

Refactoring your application

Refacto-what? Code refactoring describes the process of “cleaning up” your applications’ code. By refactoring we refer to modifying our existing code without touching the functionality or any defined API.

Refactoring an application comes with a few requirements for your teams’ knowledge:

• refactoring usually is tied to test-driven development. This means for every functionality you refactor, there will have to be a test defined and executed in order to verify the functionality of the refactored code. It has to deliver identical results, even though coded with a different approach.
• refactoring forces you to revisit all skeletons in the closet. All the pieces of code giving you goose bumps will make a return in your teams’ code editor of choice.
• refactoring code and authoring test cases is different. If your team is used to procedural development, test-driven development may scare your team. Probably they read about unit testing in Java, C++, C#, etc. but unit testing in PHP?

Refining your application

Porting is the most lightweight process to refine your applications. While rewriting and refactoring will include lot of code changes, porting only comes with a few changes.

If your application has been developed with PHP 4 and MySQL 4, you might make the jump and switch to PHP 5 and MySQL 5. Both versions only require minor changes to your code, and the manuals of both applications contain hints:

• Migrating from PHP 4 to PHP 5: the PHP 4 to 5 migration will only require a few code changes. It is recommended to work through the list of backward incompatible changes first.
• Upgrading MySQL to MySQL 5: upgrading from 4.x to 5.x mostly consists of updates for table storage engines, and might require a change of engines, and rebuilding indexes.

Making the changes listed in the manual will require low effort, and can keep your application running for a few more years but it will not give you any benefits if you do not use new features introduced in PHP 5 and MySQL 5.

Summary

As we have seen there are a few options and the difference in effort and cost is huge. Before you decide on an option you will have to evaluate carefully what works best for you. Which option you chose will be different for every application, as no application will evolve equal to another.

In part three of our series we will develop a project plan for breathing new life into your legacy app.

Stay tuned for upcoming articles in “Porting legacy PHP apps ~ The Series.

Comments and feedback is more than welcome, of course.

As you read through the series, you might see code that could be written differently or improved. At least I do expect you to do so and comment on the articles to refine what I wrote or just tell me that I suck. After all this is intended to help commercial PHP developers, and there are a lot of us out there who would all benefit from this.

What actually is that thing you name “legacy app”?

Speaking of “legacy applications” or “legacy code” as some might say, there comes Wikipedia to the rescue with a broad definition of what we can consider to be a legacy in terms of code:

Legacy code is source code that relates to a no-longer supported or manufactured operating system or other computer technology. The term can also mean code inserted into modern software for the purpose of maintaining an older or previously supported feature.

Simply said, PHP is such a computer technology, and PHP scripts are source code after all, even though some may have considered PHP to be no real development language for commercial applications.

If you’re developing PHP application for a few years now, chances are good that you will have quite a few legacy applications in your companies portfolio and even a few that are still running on servers for your clients. As an example I have picked a PHP application developed for a commercial project which is dated back to mid-2000 when most of the PHP installations still were running a 3.x version of PHP and only a few early adopters made the switch to PHP4. The application is still running on a PHP 4.3.2 installation.

What about your projects?

If you are developing PHP applications for companies which sell services to consumers, chances are good that your application is still running. This is our first checkpoint for a legacy application.

What is the lifetime of your application?

Considering that PHP 4 was released in 2000, any PHP application older than five years can safely be stamped as legacy code. PHP 4.3.0 was released in December 2002, and it marked a point where the 4.x branch of PHP started to replace PHP3 installations in larger numbers.

How large is your application?

If you are using a Linux or Apple server, you can find out how many lines of code your application has pretty quickly. Open a console and enter

wc -l `find . -name *.php4 -print`

Of course, adapt the line for the file extension you used. In my case we had to use .php4 as .php still was pointing to an old PHP 3 installation. In my case this resulted in 312374 lines of code for an application that handles a few GB of user data, and ~300K users per month.

Now if I compare this with an application – written half a year ago – that comes with stuff like unit testing, UTF8 support, full i18n localization, separation of code and views and run the above command line again, I end up with whopping 116229 lines of code. This application does leverage what PHP 5 has to offer and leaves behind functions and language features from PHP 4 which have a replacement with a different approach in PHP 5.

They say, size does not matter. I say: size matters. It’s a combination of technique and size that wins the deal. After all size should be a sign for maintainability. Even if your code is well written, the larger the code, the larger the number of maintenance tasks will become as the years pass by.

Do you see an increasing number of issue reports?

As application get older, you may start to see strange errors happening, and the number of issue reports for errors that are hard or even impossible to track will rise. PHP has gone through quite an evolution since PHP 4 was released and with PHP 5 the number of errors may grow silently.

Is your application documented?

If your application is four or five years old, it is very unlikely that you will have documented your code in a style that will be helpful today. Documentation tools like phpDoc were not broadly used and while there may have been a specification for your application, commented code will be rather rare.

Missing documentation or aged documentation may be an issue, especially when you are tasked with updating the application.

Does your application make use of libraries / frameworks?

Most likely not. PEAR was not very popular back then, and for most applications there was no defined set of libraries used. From my own backlog it seems like the focus was more on which PHP extensions were used than what libraries one may use. E.g. extensions like GD and Freetype for dynamic image creation have been on the list.

This also may be a reason for large line counts for such an application. Code had to be written in multiple places even though it was identical. Personally the only “framework” I have seen in use back then was Smarty for templates.

Does you application have style?

Even in larger teams with source code control as part of the work-flow style guides for authoring PHP code have been a rare thing on the task list. It is very likely that the team was working on one large application, where each developer was assigned to a specific part of the application, e.g. one handled templates and views, the other one handled database usage, another one was assigned to the administration system.

While this may result in code styles being adapted and used, chances are good that there will be one code style for each part of the application. If you add team changes to this, code styles will start to turn into something that lacks style aka. spaghetti code.

Does your application separate code from views?

In the early days of PHP 4 application used to mix code to implement functions with code to display output. While this may seem strange from todays’ perspective it was perfectly fine back then. PHP development was mostly done in procedural fashion, and thus application logic and user interfaces were not isolated.

Today PHP and especially PHP 5 are used more in classical fashion of software engineering, applying architectural patterns like Model-View-Controller to PHP projects.

Deprecation and your application

Within five years of time a lot of progress and evolution happens in Free Software, and PHP was no exception. Language features have changed, new features have been added, experimental PHP extensions turned into mainline extensions which are available by default. On top of that you will see a lot of PHP functions which are considered to be security risks, and have been replaced with safer functions in PHP 5.

If you are using PHP 5, there is a chapter available in the PHP manual which describes potential issues when migrating from PHP 4.

Last but not least

By now you should have an idea what the signs are to spot a legacy PHP application, and with by looking at your application’s code you should know if it is legacy or not.

In part two of our series we will continue with exploring available options for breathing new life into your legacy app.

Stay tuned for upcoming articles in “Porting legacy PHP apps ~ The Series.

Comments and feedback is more than welcome, of course.

Introducing “Porting legacy PHP apps”, an eight part series of how-to’s, rules and recommendations, and a few bits and pieces of good advice to be published in the next weeks, with the first part of the series debuting this week. The term “legacy” in the title refers to code developed for PHP when PHP version 3 was common on most servers, and PHP4 was right around the corner, mostly used by “early adopters”. Wikipedia of course offers a definition of legacy code for us to read, and you will probably discover a few of those common criteria in this series.

Here is what you can expect to see:

• Part One: Spotting legacy apps. The first part of the series will briefly discuss what a legacy PHP application actually is, and how you can run a quick check on your own applications to see if they qualify for being “dinosaurs”.
• Part Two: Rewrite, refactor, refine. Since we identified what apps are considered legacy apps, it is time to consider the available options. What’s worth the effort, and what not?
• Part Three: How to move your app forward. Now that we know more about the available options for making changes to our beloved app, we can take a close look at the type of code which needs to be updated.
• Part Four: It’s all in the process. Making changes to your app should not be done without a plan. Part four will supply the tools and tasks for you to make your plan.
• Part Five: The foundation. With PHP5 and future versions you do have the unique option to apply common development methods to your workflow. Test-driven, agile development is not restricted to Ruby and Ruby on Rails, it’s an option for PHP5, too. We’ll explore available options, both available frameworks, and building your own framework.
• Part Six: Breathing new life into the beast. This is all about Getting Real. By now you should have a plan, and the tools to start refreshing you app, and we’ll make the initial steps together.
• Part Seven: Are you prepared? Now that our app has made its’ steps into the future, we will take a look at the tasks we will face, once PHP5 leaves the stage, and makes room for PHP6. of course, assuming your customers still love your refreshed app.
• Part Eight: Final thoughts. This is it. The last part of the series will feature a few recommendations and probably wise words by me featuring insights gathered during my own endeavors with legacy PHP apps.

Code examples of legacy code and new code will be supplied with each part, and some will probably be taken from a few legacy apps that I currently work on as part of my contracted work.

See you back in a couple of days for part one of our series.

There has been a 0.3.1 release which never made it into the open, due to a last minute issue discovered during testing. The Changelog has all the details on what was changed in 0.3.1 and 0.3.2, and why it changed.

0.3.2 – Oct 02, 2008

Bugs squashed

• phpArmory.class.php: Class will not be instantiated if the Curl or XML extension is missing from your PHP installation.
• examples/character.php: Updated to use setArea. Properly dumps character data as XML. Please note that characterFetch() will now return the armory patchlevel, too.
• examples/guildroster.php: Updated to use setArea. Properly dumps the full guild roster as plain table.

0.3.1 – Sep 28, 2008

Features added

• Patchlevel detection*: getCurrentPatchlevel() will return the current patch version for the armory region you use.
• Talent definitions: TalentDefinitionFetch() will retrieve talent definition for all classes from the World of Warcraft website.
• WoW armory lockout prevention: with previous phpArmory versions, it could happen that your applications would be temporarily locked out from the armory. To prevent this, you can now limit the number of retries for XML pulling. To do this inherit your own classes by specifying the `$retries’ parameter with the number of retries to perform.

Features changed

• *Armory region and locales: this has been simplified, to only supply a setArea function to define which armory region we use.

Download

Enjoy the 0.3.2 release, and either grab phparmory-0.3.2.zip or phparmory-0.3.2.tar.gz. Please note that all PHP files are formatted with Unix line endings, as I am mostly a Linux / Mac geek.

Feel free to leave a comment if you should end up having trouble with the classes.

If you happen to be curious like I am, you will have very likely noticed that those nice PHP classes have not received much love and maintenance or bug fixing since then. Thus I decided to jump in, tasking myself with streamlining the classes and fixing any bugs I might find in there. Both the base class for grabbing and parsing XML data, and the database / file caching class had bugs and missing features, which I added.

phpArmory.class.php

Below follows the list of changes and additions.

• Added: language support. You now can use the setLanguage ($language) and getLanguage() methods to set and retrieve the language in which you want to query armory data.
• Added: the characterIconURL method now has a matching sister for items, named itemIconURL($itemRef). E.g. if you have the icon name from a character item slot, you can pass that and receive the full URL to the matching icon in JPG format.
• Fixed: the xmlToArray method was not properly checking if a children of the XML object really was an array. Checks added, thus warning message gone.

phpArmoryCache.class.php

Below follows the list of changes and additions.

• Added: the phpArmoryCache class now has a new optional parameters for its’ constructur. Using the following example you can now define the MySQL connection settings instead of having to hack the PHP class to enter your settings.

  $armory = new phpArmoryCache($armory = "http://www.wowarmory.com/", $dataStore = "mysql", $dataConn = "mysql://arthas:frostmourne@localhost/northrend", $dataTable = "frozen_throne"", $updateInterval = 14400
  

• Fixed: XML caching will now work again.
• Fixed: corrected storing of MySQL results. The cacheSave() method was not properly checking if a XML result already was stored. Now old data will be updated in case it exists instead of giving back a duplicated key error.

Download

Enjoy the unofficial 0.3 release, and either grab phparmory-0.3.0.tar.gz or phparmory-0.3.0.zip. Please note that all PHP files are formatted with Unix line endings, as I am mostly a Linux / Mac geek.

Feel free to leave a comment if you should end up having trouble with the classes.

Update: I have re-uploaded the archives and included the updated phpDoc code documentation.