Home

Thomas Andersen

PHP WoW Battle.net Armory API

For news on latest release, add me on G+ (http://gplus.to/acoon)
For more information about me, visit http://www.acoon.dk

Disclaimer: This is my first time with a project on sourceforge, so if I'm doing anything wrong please let me know so I can fix it.

[Changelog]

Intro

Ever since the World of Warcraft armory moved to battle.net it's been easier to extract information. The armory is under constant development, and some areas are still in beta or not created yet, which is why they will be missing from this API.

DONATIONS: Someone has actually asked me where to donate for the work. Using PayPal, you can just use my email address acoon(at)acoon.dk

Features

  • Extract all information from Battle.net armory
  • Handles guilds, characters and items.
  • WoW Head integration for extracting remaining information like achievement names
  • WoW Head integration for easy tool tip links
  • Full cache to limit connections and ensure speedy information
  • Generates emblems based on guild tabard design
  • Add your guild level to the emblem
  • Built in sorting and filtering
  • and much much more..

Requirements

  • PHP 5.x
  • MySQL 5.x
  • Programming knowledge
  • Internet connection

Installation

  • Download the latest package
  • Unpack the files where you may need them.
  • Make sure the webserver has write permission in the cache folder
  • Setup the database

Usage

Where ever you want to use this api you will need to include BattlenetArmory.class.php. This is the primary class, and it will include the rest of the class files.

<?php
    $GLOBALS['wowarmory']['db']['driver'] = 'mysql'; // Dont change. Only mysql supported so far.
    $GLOBALS['wowarmory']['db']['hostname'] = '127.0.0.1'; // Hostname of server. 
    $GLOBALS['wowarmory']['db']['dbname'] = ''; //Name of your database
    $GLOBALS['wowarmory']['db']['username'] = ''; //Insert your database username
    $GLOBALS['wowarmory']['db']['password'] = ''; //Insert your database password
    // Only use the two below if you have received API keys from Blizzard.
    $GLOBALS['wowarmory']['keys']['api'] = ''; // You need the api key from Blizzard. dev.battle.net
    $GLOBALS['wowarmory']['keys']['share'] = ''; // Currently unused
    include('BattlenetArmory.class.php'); //include the main class 
?>

After you include that file you better use it. :) The best way is to show a small example code. This will show all the possible functions that are available.

<?php
    // Load the class and define the realm and region 
    $armory = new BattlenetArmory('EU','Defias Brotherhood'); 

    // Use below if emblem doesn't work but you don't get any
    // usable information on what the problem is.
    // $armory->debug('emblem',TRUE)

    // Enable this is if toons with special characters break the API.
    // $armory->UTF8(TRUE);

    // Set the locale. Will default back to region default if not defined. English normally.
    // us.battle.net: en_US, es_MX
    // eu.battle.net: en_GB, es_ES, fr_FR, ru_RU, de_DE
    // kr.battle.net: ko_KR
    // tw.battle.net: zh_TW
    // battlenet.com.cn: zh_CN
    $armory->setLocale('ru_RU');

    // To reset back to default server locale
    $armory->setLocale(FALSE);

    // To exclude some fields from characters to load.
    $armory->characterExcludeFields(array('achievements','quests')); 
    // To reset the exclude list to not exclude anymore
    $armory->characterExcludeFields(FALSE); 

    // Load all the guild data into an object. This is NOT an array 
    $guild = $armory->getGuild('Shadowsong'); 

    // Load all the character data into an object. This is NOT an array 
    $character = $armory->getCharacter('Growar'); 
?>

This will give you two objects: guild and character. Within these you will find different functions to call, that will mainly return an array with the information you need.

Guild Object

Load the guild

<?php
    // Initialize the guild object
    $guild = $armory->getGuild('Shadowsong');

    // Adding guild rank names to all members.
    // Supply a valid array starting with key 0. Remember to add enough ranks.
    $guild_ranks = array(0=>'Guild Master',
                         1=>'Rank 1',
                         2=>'Rank 1',
                         3=>'Rank 1'
                         );
    $guild->setGuildRankTitles($guild_ranks);

    // Get an array with all members and basic information
    $members = $guild->getMembers();

    // Get an array with all members and basic information sorted
    // sort can be name|class|race|gender|level|rank
    // sortflag can be asc | desc
    $members = $guild->getMembers('name','asc');

    // Get array the guild achievements.
    // Also includes wowhead urls and names for easy integration with wowhead tooltip
    // Include this to get tooltip on URLS:
    // <script type="text/javascript" src="http://static.wowhead.com/widgets/power.js"></script>
    $achievements = $guild->getAchievements();

    // Get array the guild achievements sorted
    // sort can be timestamp|id|name
    // sortflag can be asc | desc
    $achievements = $guild->getAchievements('timestamp','desc');

    // Get the achieved perks of the guild
    $perks = $guild->getPerks();

    // Get the next perk to achieve. Returns FALSE if there is no more.
    $nextPerk = $guild->getNextPerk();

    // Generate and output a guild emblem png. This sohuld be run from a separate php file.
    // Read more below this section
    $guild->showEmblem();

    // Generate and output a guild emblem png. This sohuld be run from a separate php file.
    // showlevel can be TRUE|FALSE. It is TRUE by default.
    // width can be 1-215
    $guild->showEmblem(FALSE,'175');

    // Save the generated emblem at a specific location
    $guild->saveEmblem($destination);

    // Test if the guild data is loaded. Returns TRUE|FALSE
    $guild->test();

    // Force to delete cached emblem
    $guild->deleteEmblem();

    // Get all data function where it will just dump it all to you in an array
    $data = $guild->getData();
?>

As a cool side feature you can make your own guild emblem with just a few lines. This will respond with an image meaning this is all that should be in the php file.
There may be NO whitespaces before or after the php tags

<?php
    include('BattlenetArmory.class.php');
    $armory = new BattlenetArmory('EU','Defias Brotherhood');
    $guild = $armory->getGuild('Shadowsong');
    // Takes two parameters to disable level and resize. 
    // $guild->showEmblem(FALSE,125);
    $guild->showEmblem();
?>

Character Object

<?php
    // Get the character object. Will return FALSE if the
    // character could not be found or character is frozen.
    $character = $armory->getCharacter('Growar');

    // Return character news feed. New bosses killed, new items won, etc.
    $feed = $character->getFeed();

    // Return basic guild information of the guild which the character is member of.
    $guild = $character->getGuild();

    // Return the amount of achievement points for the loaded character
    $achievementpoints = $character->getAchievementPoints();

    // Return all achievements completed for the character.
    $achievements = $character->getAchievements();
    // Return all achievements completed for the character sorted.
    // sort can be timestamp|id|name
    // sortFlag Can be asc|desc
    $achievements = $character->getAchievements('timestamp','desc');

    // If the character is not member of any team, this will return FALSE
    // Else it will return an array with 1-3 teams.
    $arenateams = $character->getArenaTeams();

    // Get the rated battleground personal rating
    $battlegroundPersonalrating = $character->getBattlegroundRating();

    // Get stats on all the character rated battlegrounds
    $battlegrounds = $character->getBattlegrounds();

    // Get a list of the completed achievements by the guild
    // WARNING: Since this will make separate lookup for EACH quest, it can be very slow.
    // However it will cache for 20 days per default.
    $completedquests = $character->getCompletedQuests();
    // sort defines what the list should be sorted by: id|name
    // sortFlag can be asc|desc
    $completedquests = $character->getCompletedQuests('name','asc');

    // Get the number of quests completed by the character
    $completedquestsAmount = $character->getCompletedQuestsAmount();

    // Get the full currently used title
    $title = getCurrentTitle();
    // withName Set to FALSE if you want to use the %s instead of name
    // Will replace name with %s
    $title = getCurrentTitle(FALSE);

    // Get all talent trees
    $talents = $character->getTalents();

    // Get active talent tree
    $activetalents = $character->getActiveTalents();

    // Get inactive talent tree
    $inactivetalents = $character->getInactiveTalents();

    // Get character faction. Returns 1 for alliance and 2 for horde
    $faction = $character->getFaction();

    // Get character faction name. alliance or horde
    $factionname = $character->getFactionName();

    // Get character gender. 1 for male, 2 for female
    $gender = $character->getGender();

    // Test if character is male. Return true if male, false if female
    $character->isMale();

    // Test if character is female. Return true if female, false if male
    $character->isFemale();

    // Get the race name of the character
    $racename = $character->getRaceName();

    // Get the class name of the character
    $classname = $character->getClassName();

    // Return an array with equipped gear and itemlevel stats.
    $gear = $character->getGear();

    // Check if there is anything equipped in the specific slot.
    // Returns TRUE or FALSE
    // Valid values are head|neck|shoulder|back|chest|shirt|tabard
    //                      wrist|hands|waist|legs|feet|finger1|finger2
    //                      trinket1|trinket2|mainHand|offHand|ranged
    $character->checkItemSlot('head');

    // Get the basic item information of a specific slot
    // Returns an array with information or FALSE if slot is empty
    // Valid values are same as checkItemSlot()
    $headslot = $character->getItemSlot('head');

    // Get the amount of honor kills
    $honorkills = $character->getHonorKills();

    // Get the character level
    $level = $character->getLevel();

    // Retrieve the characters mounts
    $mounts = $character->getMounts();

    // Get the character professions
    $professions = $character->getProfessions();

    // Get the character primary professions based on wowhead. Can be slow.
    $professions = $character->getPrimaryProfessions();

    // Get the character combat pet (array), or FALSE if not valid for character class
    $combatPets = $character->getCombatPets()

    // Get the character audit. An array with list of missing slots, missing enchants etc.
    $audit = $character->getAudit()

    // Get the character pet slot information
    $petSlots = $character->getPetSlots()

    // Retrieve the raid kills from the character
    $raidprogress = $character->getRaidStats();
    // sort Can be asc | desc. Default is asc
    $raidprogress = $character->getRaidStats('desc');

    // Get character reputations
    $reputation = $character->getReputation();
    // sort Use to enable sorting
    // sortfield Define the field you want to sort by - Values are: id | name | standing
    // order Define the order of the sorting - Values are: desc | asc
    $reputation = $character->getReputation(TRUE,'standing','desc');

    // Retrieve stats such as HP,mana,AP,AGIhit,parry etc.
    $stats = $character->getStats();

    // Returns the complete URL for a character thumbnail
    $thumbnailurl = $character->getThumbnailURL();

    // Returns the complete URL for a character profile image
    $profileurl => $character->getProfilePicURL();

    // Returns the complete URL for a character inset image
    $profileinseturl => $character->getProfileInsetURL();

    // Get all the titles held by the character
    $titles = $character->getTitles();

    // Check if the character has been loaded correctly
    $validcharacter = $character->isValid();
?>

AuctionHouse Object

<?php
    $auctionhouse = $armory->getAuctionHouse();
    $auctions = $auctionhouse->getData();
?>

Realms Object

<?php
    // Load the realms. Since it's the same request to get one or all realms,
    // all is cached.
    $realms = $armory->getRealms();

    // Return the specific realm you want. Will take it from cache when object was created.
    $myrealm = $realms->getRealm('Defias Brotherhood');
?>

Quest Object

<?php
    // Load the quest based in quest ID
    $quest = $armory->getQuest(24779);

    // Return the title of the quest
    $quest_title = $quest->getTitle();

    // Retrieve all available quest data for that specific quest
    $quest_data = $quest->getData();

?>

Item Object

<?php
    // Load the realms. Since it's the same request to get one or all realms,
    // all is cached. This will load weapon 'Legacy'
    $item = $armory->getItem(28587);

    // Get the name of the item.
    $itemname = $item->getName();

    // Get icon URL for the item
    $itemurl = $item->getIcon();
    // Get icon URL for the item at the size 36 px.
    // Valid values are 18 | 36 | 56. 56 is default.
    $itemurl = $item->getIcon(36);

    // Get a IMG tag with alot of inline style for adding icon
    // border, light etc. Unfinished.
    $itemIMG = $item->getIconIMGtag();
    // Same, but for Firefox and a different size. Same sizes as getIcon().
    // Browser can be 'ie' or 'moz'
    $itemIMG = $item->getIconIMGtag(36,'moz');

?>

Arena Team Object

<?php
    // $team = $armory-getArenaTam($teamsize, $teamname,$realm)
    // $realm is optional if it's defined when making $armory.
    $team = $armory->getArenaTeam('2v2', 'Probably Drunk');

    // Get date of team creation
    $teamcreated = $team->getCreated();

    // Get games won
    $gameswon = $team->getGamesWon();

    // Get games lost
    $gameslost = $team->getGamesLost();

    // Get games played
    $gamesplayed = $team->getGamesPlayed();

    // Gets the team name as it's supposed to be
    $teamname = $team->getName();

    // Get the faction side. Alliance or Horde
    $factionside = $team->getSide();

    // Get all team members
    $members = $team->getAllMembers();

    // Get a member by name
    $member = $team->getMember($name);
?>

Cache Control

Made a switch to MySQL in version 3.0

<?php
    // Turn off cache. Using this you dont have to define MySQL user/pass/etc,
    // but will generate quite a few calls to blizzard if you are not careful.
    // Added it because some users had their own cache to control
    $armory->useCache(FALSE)

    // Use these to change the time cahce is valid.
    // Remember that lower numbers means more requests to Blizzard.
    $armory->setArenaTeamsCacheTTL(6000);
    $armory->setAchievementsCacheTTL(100600);
    $armory->setItemsCacheTTL(86000);
    $armory->setGuildsCacheTTL(600);
    $armory->setCharactersCacheTTL(600);
    $armory->setAuctionHouseCacheTTL(6000);
?>

Page still in progress

Related

Home: Changelog