GitHub finally added issue handling to their service, and I’d like to say: report your issues with phpArmory at GitHub.

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

The database client

While I am currently using .NET 2.0 / C# to prototype a client which takes care for downloading and updating the WoW addon for data gathering, I am of course aware that .NET 2.0 is not available on every platform where you can play World of Warcraft. There is Windows in various incarnations, and there is Mac OS X for us to play the game on, and some people even use Linux to play. I probably have not mentioned this, but I am using all of these platforms to play the game, and thus I am very interested in making the database client work on all of these platforms.

My current plan is to finish my .NET prototype, as I need some quick test tool, to define and build a proper web interface for managing the WoW addon, and to test the client updater. Once this is done, and the web interface works, I plan to turn the whole client functionality into a plain C++ library, which can be build and used on Windows, Mac OS X and Linux.

For now the library is supposed to contain the following features:

• Parsing the WDB cache: as many players know, the game client uses a simple data cache for books you have read, creatures you saw, game objects seen and used, items seen, and quests done. This data will be required for several reasons. E.g. if we want to display rendered views, we need the data from the WDB cache files.
• Detecting WoW: of course, the library needs to find WoW on your system, and there are various different methods to do so. WoW is e.g. installed in different ways for 32-bit and 64-bit operating systems.
• Parsing the addon Lua data: while this is not necessary it would be beneficial to embed Lua into the library. This would allow us to validate the saved Lua data, and it might provide options for blocking invalid data, too. Why should we upload broken data?
• Authentication: I would love to have the database site requiring a login. Why? Because it would be great to give credits where they are due. If someone contributes to the database, it should be recorded and visible in some place.
• Update management: we need to keep up-to-date, and this includes both the database client, and our WoW addon. The game client changes with every release, and bugs are everywhere. There is no development method that results in zero bugs.

On top of the library custom GUI clients can be used for each platform. On Windows, we could use plain C++ with MFC or a .NET GUI, on Mac OS X we can use Carbon API to integrate into the system.

Of course, suggestions are welcome.

The database server

Once of the things I have considered over the last few days was to turn the server into something that could run in a distributed fashion, much like the version control system Git which I use for my own projects at home and at work. Concerns have been raised that the current databases are commercial because you will have large hosting bills.

But what if the database server would have a central server somewhere, and all available installations would connect to this server for data sharing? Thus every installation (e.g. on guild sites) could contribute their data even without knowing the main server, and every installation would benefit from uploads.

Anyway, the only thing I have decided on yet is that the database server will be developed using a model-view-controller pattern. This may be done with ASP.NET, on PHP using the Zend Framework, or on Python using Django, or on Ruby using the famous Ruby on Rails.

Personally I would prefer a Python or Ruby based solution. But still, for my prototyping I will stick to using PHP and the Zend Framework for one simple reason: this solution works on most hosted environments. You will not depend on owning a root server (which not everyone can afford).

The code

There already is a bit of code, and I am working hard to get this in a readable state and documented. It will appear in my GitHub account in a few days.

Contributions are welcome, in the beginning I would be very interested to hear what addon developers need. E.g. what would systems like QuestHelper, TourGuide, or LightHeaded need? After all, quest guides are the simplest form of giving data back to the community, thus you would want to have it done right from the beginning.

For now, I am considering XML output in a format similar to the armory format, but would that work for addon developers?

The database contestants

Ever since World of Warcraft became public there have been websites out there, which gathered game data by using a Lua addon and some sort of data uploader. In the beginning there was one database site and nowadays there are many.

• Thottbot: Probably the father of all WoW database websites. Thottbot.com started somewhere during the World of Warcraft Closed Beta and has been a primary source of information for many players. Quests, Items, Maps, NPCs, Spells, and more await the curious player, and closely coupled with Thottbot comes Cosmos, a User Interface modifcation pack, to which players were drawn in the early days of WoW aka. the days when World of Warcraft was not available in any localization.
• Allakhazam: Allakhazam entered the market of WoW databases a bit later. They already had experience with this thing, as they started with an Everquest database. Their WoW site has gone through various iterations, and AFAIK was the first database site to offer support for the various localizations in which WoW was made available. Another feature spearheaded by them was the monitoring of Auction House prices for items. Yay for that!
• Wowguru: Another side project of an MMO database site, and one that initially had some success. WoWguru.com entered the scene in Summer 2005, and later spearheaded with features like honor tracking, and most prominently with monitoring the individual realm status during the Ahn’Qiraj War Effort.
• Wowhead: Here comes an impressive contestant. Ever since their launch Wowhead impressed with an information-centred design that helped users in finding the information needed very quick. Wowhead comes with a well made Lua addon, and a sleek uploader. Once of their primal bonusses was that they had been very active with making their Lua addon work for the Public Test Realms, and soon this resulted in Wowhead leading the WoW databases. Features like a well-designed commenting system, their item and character preview, and others still remain on top of the list.
• WoWDB: The latest entry in the list of contestants. Made by the MMO portal site Curse (which alos provides hosting for most WoW Lua addons), WoWDB entered the scene with some features that Wowhead could not offer: item comparison, wishlists, and a look more oriented on the WoW look. AFAIK their character preview was first, and Wowhead added that a bit after them.

What do all these databases share?

As it seems, the market for World of Warcraft databases is a hot one. Even four years after WoW made its’ initial release. And as we can see by the release of new and different databases, none of the contestants listed above yet has managed to reach a state where WoW players are satisfied.

If we compare the features of all available WoW databases we can see that it’s not all about features, but about design and usability, too. Some features did not really make it into the market, as players did not seem to accept them.

• Auction House monitoring: Yes, it is there, and some people might use it, but apparently this is not interesting or good enough to be used anywhere else than on Allakhazam. Apparently using spreadsheets still is superior. Also, there is Auctioneer which works in-game and automates a lot of the process.
• Crafting requirements: Wowguru introduced this quite some time ago, and I thought it was a great feature. When displaying a crafted item, you could see all the items required to create it, summing up the total vendor price for all needed materials. Nice, but oviously not needed. Gold seems to be an irrelevant factor, and thus only material lists survived.

This leaves us with a list of features that seem mandatory for a mature World of Warcraft content database.

• Searching: Of course, searching is mandatory. Every site has it, and the only difference to be found is in the way search results are returned. Older sites just take an argument to look for and return an result page with any matching object, Wowhead and WoWDB sport a bit more elegance and make use of AJAX to return drop down lists with matching data instead of requiring you to wait for a result page.
• Filtering: Even though the official forums are full of people demanding more content because the existing content would not be sufficient, a look at a database of your choice proves the opposite. There is lots of game content, and there is much to be seen. Even after four years, I am sure you will find content that you have not seen yet, even if you started your character in February 2005. Thus most database allow you to filter for various parameters, and most important: you can apply multiple filters to any kind of data. Sleak and useful.

And why would you want that Open Source’d?

It’s simple. Many people contribute data to these databases, and only with your or my contributions of data gathered while playing the game, those databases exist. It’s a community effort, just like the game itself is meant to be some sort of social community. But why are all of these databases closed, or commercial? Some even want you to buy premium subscriptions to access guides or more data.

Now what if there was an Open Source database for World of Warcraft? Where you could not only contribute data you gathered while playing, but also access that data or even download it to your computer and do something with it? Or where you could see what you have gathered while playing?

So I have decided to give myself a new pet project to work on, and it will become Open Source very soon, once I have ironed out the basic details. Work already begun, and a very basic implementation is there. The tools I have used are:

• Visual C# 2008 Express Edition to build a .NET 2.0 client application which handles uploads,
• Lua to write a WoW addon which gathers data while you play,
• Zend Framework and Doctrine ORM to write the server-side backend which accepts uploads.

The process for now is very simple:

• the .NET client will parse the WoW data cache (which you will find in your WoW installation directory under WDB/your-locale/*.wdb),
• it can show you the contents of your WDB files, e.g. you can see which NPCs you have seen, or what books you have read,
• it will parse the saved Lua data generated by the addon, and can show what data besides your WDB cache is there,
• and it can convert both WDB and Lua data to XML,
• and finally it can upload the data to my server (GZipped of course, to reduce bandwidth usage).

Parsing the data is something that will be done next. For now my server-side application only handles storing the uploaded data, and manages updates of the client. Not very much, but at least my data is stored. Parsing will be a bit more work since I have to make a modular parser that can deal e.g. with different data formats, as the data formats may and surely will change with every WoW client update.

What do you think? Would you use an Open Source World of Warcraft database, where you have full access to the data you contributed? Would you like to download contributed data in a parsed format, perhaps as XML files to reuse them on your guild website or your blog?

More on the project soon, after the finishing touches have been put on the data client. Screenshots coming soon.

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.

General macros

The following macros can be used for all classes, and only serve a purpose out of combat. It is not required to have these on any keybindings. You might want to put them on an actionbar for less used stuff, e.g. bar 5.

Consume conjured food and water

/use [nocombat] (name of conjured food)
/use [nocombat] (name of conjured water)

Focus

This macro will use the group leader’s target and assign focus to it.

/assist party1
/focus

In order to clear the focus, the following macro is required, too.

/clearfocus [targetfocus, dead]

Mounting

The following macro will mount a character using either a land mount or a flight mount, depending on the zone a character is in. If the zone allows flying mounts, the macro will always use the flying mount, otherwise the land mount.

If you are currently mounted, you will be dismounted.

#showtooltip 
/cast [outdoors,nomounted,flyable] (name of flying mount)
/cast [outdoors,nomounted] (name of land mount)
/dismount [mounted]

Spell casting

The following macro can be used to assist the group leader, and assist him in order to attack his target.

#showtooltip
/target [targetparty1,nodead]
/assist
/cast [exists,harm,nodead] (spell name)

Class specific macros

The following macros will only work for specific classes, and some might need a counterpart on another character.

Mage macros

Conjure / Consume food and water

/use [nocombat] (name of conjured food)
/use [nocombat] (name of conjured water)
/use [combat] (name of conjured mana gem)
/cast [mod:ctrl] Conjure Food
/cast [mod:alt] Conjure Water
/cast [mod:shift] (name of Conjure Mana Gem)

Polymorph focus

This macro will sheep the current focus.

#showtooltip Polymorph
/cast [targetfocus] Polymorph

Portal creation

This macro allows an Alliance mage to cast any portal to the Alliance towns with just one key. It uses modifiers in order to select the actual portal to be used.

#showtooltip
/cast Portal: Exodar
/cast [mod:lshift] Portal: Ironforge
/cast [mod:lalt] Portal: Stormwind
/cast [mod:lctrl] Portal: Darnassus
/cast [mod:ralt] Portal: Shattrath

Teleport

This macro allows an Alliance mage to teleport to the Alliance towns with just one key. It uses modifiers in order to select the actual teleport to be used.

#showtooltip
/cast Teleport: Exodar
/cast [mod:lshift] Teleport: Ironforge
/cast [mod:lalt] Teleport: Stormwind
/cast [mod:lctrl] Teleport: Darnassus
/cast [mod:ralt] Teleport: Shattrath

Paladin macros

Divine Intervention

This macro will cycle through a list of characters which are alive and friendly, and will cast Divine Intervention on the first target that fulfills these two conditions, in order to save a class with a resurrection spell.

#showtooltip Divine Intervention
/cast [targetBrista,help,nodead][targetPriswa,help,nodead] Divine Intervention

Righteous Defense

One little secret that while in a regular group (not raid) the [raid] returns true for your group members but NOT for you. This way you will never try to cast Blessing of Protection on yourself. If the mob targets you, the macro will do nothing.

The castsequence effectively gives you a “backup” taunt. If your first one gets resisted or you need to re-taunt before the cooldown is up it will use Blessing of Protection.

#showtooltip Righteous Defense
/castsequence [targettargettarget,help,raid] reset15 Righteous Defense,Blessing of Protection

Priest macros

Multi-purpose healing / debuffing

/cast [modifier:lctrl, targetparty1, exists,party,nodead] Renew; [modifier:lshift, targetparty1, exists,party,nodead] Flash Heal; [modifier:rctrl, targetparty1, exists,party,nodead] Resurrection; [targetparty1, exists,party,nodead] Heal

Shackle focus

This macro will shackle the current focus.

/cast [targetfocus] Shackle Undead

Shaman macros

Totems

Repeatedly executing this macro will stomp the listed totems one by one. If you wait longer than 7 seconds, the macro will reset and start from zero with the first totem listed.

/castsequence [nomod] reset7 Healing Stream Totem,Strength of Earth Totem,Windfury Totem,Searing Totem

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.