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.

0.4.2 – “Fishing Extravaganza” – Dec 17, 2008

This release should fix issues with character that could not be retrieved from the armory due to special characters in realm or character names.

Bugs squashed

• phpArmory5Cache: the setCachedData(…) function was called without prior checks if there was any valid data to cache. This has been fixed.
• phpArmory5: Strings used in URLs do not need a manual replacement of the space character. urlencode() handles this for us already.
• phpArmory5: fixed an issue in __construct, where required PHP extension have not been checked properly. Thanks to Gizzmo for the hint.

Features added

• phpArmory5: added getAnyData($searchType = NULL, $objectName = NULL, $filter = NULL). $searchType can be any of “arenateams”, “characters”, “guilds”, “items”. $filter needs to be an associative array of filter properties. For now, try out the armory item search page to see valid filter options.

• phpArmory5: added a third parameter to getCharacterData for retrieving only the basic character data. Defaults to false. Use the following to get basic character data only:

  $character = $phpArmory->getCharacterData($characterName = "Char", $realmName = "Realm", $onlyBasicData = true)
  

Download

Enjoy the 0.4.2 release, and either grab phparmory-0.4.2.zip or phparmory-0.4.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. phparmory-042tar

First, let us check what we currently have in store:

• Characters: Retrieve full character details including stats, equipped items, skills, reputation, buffs,
• Items: With complete stats, reagent details, related quests,
• Guilds: List of members,
• Caching: Caches results of requests to improve performance
• Localisation: Results returned in the armory’s supported languages from localised servers.

This seems like the basics done. Personally I would love to add the following stuff:

• Arena teams: it’s on the TODO list, and will be released after December 17th, 2008. Why? Because arena season 5 will start then, and only then I can get arena team data from the armory to test and implement this.
• Searching: Query the armory for any kind of data.
• Guild banks and calendars: You have guessed by the name, don’t you?

Searching is pretty simple to implement, as we can base upon getXmlData( ..) and search for arena teams, characters, guilds, and items easily. We can even filter the results by any desired parameter.

Now when it comes to guild banks and calendars, things get a bit spooky. Both features can be implemented, but you would have to trust phpArmory to not do bad things with your account data, as the class would need to authenticate using your account data on the armory site in order to retrieve the guild bank contents, or your calendar.

Here is your chance, to influence future releases. Raise your voice, and share your thoughts.

0.4.1 – “Call to Arms” – Nov 26, 2008

The World of Warcraft armory has received quite a few improvements, making it feature complete with the added character data from the “Wrath of the Lich King” expansion.

Features added

• getCharacterData($characterName, $realmName) will now return an array which contains character achievements and statistics.

  $character = Array
  (
      [characterinfo] => Array
          (
                  ...
          )
  
      [reputationtab] => Array
          (
                  ...
          )
  
      [skilltab] => Array
          (
                  ...
          )
  
      [talenttab] => Array
          (
                  ...
          )
  
      [achievements] => Array
          (
                  ...
          )
  
      [statistics] => Array
          (
                  ...
          )
  
      [armorypatchlevel] => 030003
  )
  

Download

Enjoy the 0.4.1 release, and either grab phparmory-0.4.1.zip or phparmory-0.4.1.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.

0.4.0 – “Jack-o’-Lantern” – Nov 20, 2008

phpArmory has been rewritten for PHP5 and the new OOP class syntax. The class interfaces have been changed to use getFunction() and setFunction() syntax, and class variables have been adjusted to use private, protected, and public states. Please consult the doc/ folder for updated API documentation.

NOTE: arena team handling has been postponed to release 0.5.0, as with the recent release of Wrath of the Lich King, all arena teams have been wiped and no sample data was available to develop the feature.

Bugs squashed

• all functions have received input checking, now all functions will properly return FALSE when something goes wrong.

Features added

• phpArmory5 and phpArmory5Cache will now make use of trigger_error provided by PHP5 to raise notices (E_USER_NOTICE), warnings (E_USER_WARNING), and errors (E_USER_ERROR). Please note that warnings and notices will only be raised when you use phpArmory from the command line. If you use it on your web server, only errors will be raised.
• you can now use getArea / setArea to make changes to the armory area.
• you can now use getLocale / setLocale to set the language in which you want to query data from the armory.
• you can retrieve talent definitions for all classes, including the recently added Death Knight using getTalentData().

Features changed

• the phpArmory class API has been changed. All functions now use get… and set… for their names. The current API documentation is available online
• character icons will now be properly display for characters up to level 80. We have shiny WotLK character icons.

Download

Enjoy the 0.4.0 release, and either grab phparmory-0.4.0.zip or phparmory-0.4.0.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.

On Aug 27, 2008 the PHP team has released the final release of PHP4, and thus it is time to make the switch to PHP5 in phpArmory, too.

As some may know, PHP5 introduced quite a few features to enhance the OOP features for classes, and make them feel like real classes. Among the changes, there are real class constructors and destructors, plus private, protected, and public keywords became available for class variables and functions. Cheers for this! I have waited for this quite some time, being a C++ developer it just felt wrong to have no real classes in PHP4.

This means, most variables and functions of phpArmory / phpArmoryCache will be changed. For most class variables, their status will become private to prevent their usage from outside the class. All variables have been intended for internal use anyway. If you did use them, stop now. Class functions will be changed to private or protected. Only two functions will become private, as they are intended to be used only inside phpArmory / phpArmoryCache. The remaining functions will become protected (not public!). What does this mean? Simply spoken, protected functions may only be used from inherited classes.

Along these changes the class documentation will be rewritten from scratch, using the phpDoc syntax. I also plan to add new usage examples.

One change yet is not decided on, but you can raise your voice to help me. I am considering to switch the phpArmoryCache class to use PHP data objects instead of using the MySQL extension directly. In common this does sound good, but in reality I am not sure if it would be worth the effort. Does anyone want to use PostgreSQL, SQLite or other database backends for phpArmory? If yes, raise your voice and tell me. If not, this change will probably become a task for phpArmory 0.5.0.

If you want to see what I am working on currently, I have added a issue tracker. The issue tracker is updated weekly and shows the progress with fixing bugs, implementing features, and how planned releases progress.

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.