BF2S MyLeaderBoard API

Updated! 11-14-05 The XML feed now returns more information in the XML feed itself and this API has been updated to properly deal with the new data. You lose nothing, and gain a few more fields of commonly requested data! Also added a little bit more comment documentation and split out the date formatting function so it is easier to overwrite in extended classes.

The provided script will allow you to easily add a Battlefield 2 Leader board to you own home page. See some output examples.

Installation takes a few, simple steps:

Upload the files
CHMOD (set permissions) the "cache" folder to 777. (This folder is where leader board XML files are stored, and PHP needs to be able to write to that directory.)
Add the code to your PHP file where you want the leader board to show up. Done!

Ok, so it's not that many steps, honestly. There are a few things you'll want to be aware of, however.

First of all, USE CACHING. This API uses a built in caching mechanism -- in fact, it requires it to work. But if you make your own API, you'd better use some kinda of caching mechanism because the BF2S.com server will block your requests for XML leader boards if you request more than 3 per 6 hours. This is to keep my server, data, and bandwidth safe.

Second, this API is pretty smart. You are not limited to using just the standard table output for the results. You can choose to format the output anyway you see fit. You can even sort the data as you see fit. The important function, in this case is showList(). But first, let's get a basic setup going...

Basic Usage

After everything is uploaded and CHMOD'ed correctly, open up your the PHP file you want the leader board to appear in. Start by importing the bf2s-mlb.php class:

<?php
require('./bf2s-mlb.php');
?>

Then, proceed to call for the leader board you wish to run on your site:

<?php
$mlb->get('43917103,45507687,45138378,43485335,39709471,44260977');
?>

When calling a leader board be VERY aware of a few things:

You may only pull up to 3 xml feeds every 6 hours -- no exceptions. I highly recommend that you test your PID lists on the BF2S.com My Leader Board page before using them here.
You may query up to 64 players per feed. My system will not 'error out' if you request 100, you'll simply only get the first 64 of them back.
Only PID numbers will be accepted. If you query by a nick, the API will kindly tell you to revise your query string. (This query won't count towards your query limit because it never actually gets to the query part.) Technically, my system can handle query by name, PID, or mixed, but things are much, much simpler if you stick to the PID numbers. Thus, this API requires that you do so.
This API uses a cache file. It will be written to the cache directory. It will automatically refresh this cache file every 6 hours.
The players you request will be requeued for a stats update automatically. (Even those not in the system.)

Now that the leader board is either loaded from BF2S, or from your local cache, you will be ready to display it. The most important function here is showList which can be used to sort and apply custom formatting, to the leader board. It looks a little like this:

<ul><?php $mlb->showList('rank','<li>{NICK}, {RANK}</li>'); ?></ul>

The above code would produce a list of players showing name and rank, sorted by their rank. So, here's the juicy details for the showList function...

showList($sort, $format)

$sort: Use this to change what column of data the leader board is sorted on. You can choose any of the columns. Default: Score
$format: Pass a custom string, with replaceable elements, that will be output for each player in the leader board. Default: Simple table with table html wrappers

Available Columns:

NICK: The player's nick
PID: The player's PID number
RANK: The player's rank (numerical)
SCORE: The player's score
SPM: The player's SPM (float, rounded to 2 places)
TIME: The player's total time played in Seconds (will be displayed in hours, two decimal places)
LINK: A link to the players full profile
COUNTRY: The player's home country (two character code)
KDR: The player'sKill to Death Ratio
KILLS: The player's total kills
DEATHS: The player's total deaths
WLR: The player's win to loss ratio
WINS: The player's total wins
LOSSES: The player's total losses

You can sort on any of those columns, and you may use any of those columns in the format parameter. When used in the format parameter, the column should be wrapped by curly braces eg: {SCORE}. For a good number of examples, it would be wise to peruse the examples.php file which details many ways of using the API's showList() function.

Note: If you specify a custom $format parameter, the function will no longer automatically wrap the output in <table /> tags -- you'll need to do that yourself.

Custom Parsing

While the XML feed provides data in a raw format, this API will convert certain elements into more human readable information. If you wish to custom parse this information, you may do so by using the lower level function getList()

getList() will accept 0 or 1 parameters - a "sort by" variable. This is the same as it is in showList(). However, this function does not directly echo the data. Additionally, it does not parse the raw data into "human readable" formats. This will return a raw, ready to be manipulated array of information sorted by a column, or not sorted at all.

Debugging

We all hate it, but sometimes things just don't work. The API comes with a fairly extensive debugger built into it. In order to collect and display the debugging output, you'll need to:

Activate the debugger
and
Display the debugging results

This is, however, very simple. As an example:

A normal MLB code setup:

<?php
require('./bf2s-mlb.php');
$mlb->get('43917103,45507687,45138378,43485335,39709471,44260977');
$mlb->showList();
?>

Compared to the API with the debugger turned on and its output printed:

<?php
require('./bf2s-mlb.php');
$mlb->debug = true;
$mlb->get('43917103,45507687,45138378,43485335,39709471,44260977');
$mlb->showList();

echo '<pre>';
$mlb->printLog();
echo '</pre>';
?>

Pretty easy. Of course, if there are errors, they are always available in the $mlb->errors variable, regardless of whether debugging is activated or not.

Aight, take it easy and enjoy. :D

- Jeff