[PHP/MYSQL] TMFDataFetcher v1.3b

[f*ckfish]

TMFDataFetcher (PHP5, MySQL 5 tested)
by oorf I f*ckfish aka Alexander P.
http://fish.stabb.de

The TMFDataFetcher is a php class that represents a wrapper for the Trackmania Ladder API. It queries the NADEO stats server for a given login and gets all the available information about that player. It then provides this information in a fairly easy to use manner (be sure to read the other sections as well for multiple usage examples).
I also built in a caching system which has to be used (see 'caching' section).
Last but not least be sure to read the "Configuration" part which also includes the requirements.

Download

TMFDataFetcher All Versions

Update v1.3b

• Replaced all shorttags with standard tags

Update v1.3

• Added error messages for the upper case login problem
• Added a sample script that generates a list of stats for multiple logins and also circumvents the error 125
• removed all global variables (although I still don't think, that they would cause any problems)
• Added an option to specify the fetching method (Automatic, cURL, fopen)
• Added another caching method (see "Caching" section for this one)
• fixed a few homezone flag links (w1lla, yours should work now )
• fixed a bug that created empty database entries for logins resulting in a "Player Unknown" error on the next access

Update v1.2

• If the nation was equal to the homezone, it was not recognized - fixed

Update v1.1

• XML specific characters in nicknames or zonepaths caused the script to crash - fixed

Configuration

In order for the DataFetcher to work, you'll need the following things:

• a stats server login, which has to be obtained from NADEO, to get that, kindly ask Request ( )
• a webserver running PHP 5 and mySQL 5
• in php the "openSSL" library has to be installed and enabled
• the php "cURL" library should be installed (if it does not exist, the class automatically reverts to standard fopen functions, which can cause problems with remote URLs)

Open the tmfdatafetcher.config.php and fill in the settings by editing the lines:

Code: Select all

$fetcherSettings['stats_user']     = 'yourstatsserverlogin';
$fetcherSettings['stats_password'] = 'yourstatsserverpassword';
$fetcherSettings['mysql_server']   = 'mysqlhost';
$fetcherSettings['mysql_login']    = 'mysqlusername';
$fetcherSettings['mysql_password'] = 'mysqlpassword';
$fetcherSettings['mysql_database'] = 'mysqldatabase';

$fetcherSettings['fetch_method'] = 0;
$fetcherSettings['refresh_after_midnight'] = false;

The database is needed for the caching. The other settings are described in the config file itself.

Caching

The TMFDataFetcher includes caching for various reasons. First of all, the access to the stats server is restricted and you will notice that querying it too often will result in a 'permission denied' error. On the other hand, it makes no sense to query it too often since the data is only updated once a day. Therefore this is the hardcoded caching timespan.

And this is how it works:
Everytime you use the datafetcher, the class will first look at the saved data in the database and see, if it has to be refreshed. If not, the DataFetcher will just load everything from the database. If the data is too old, the DataFetcher will query the stats server for new information, gather it and then save it to the database automatically.
There are two different methods that can be used. Per default, the DataFetcher only gathers new stats if the last query to the stats server was more than 24 hours ago, but you can also set the DataFetcher to always gather new data on the first access of the day which could be a good method if you use a nightly cronjob to update your stats.

The whole caching is totally transparent. You will not have to set up the database tables and you won't have to execute any methods to handle the database stuff. For you it's just instantianting a TMFDataFetcher object with a login and you'll get your data. I just love that caching stuff =)

Usage

To get the TMFDataFetcher to work, you'll have to do the following steps:

1. Copy the contents of the archive into your project folder
2. include the file into your php source:

   Code: Select all

   require_once('./classes/tmfdatafetcher.inc.php');

3. Instantiate the class with a login

   Code: Select all

   $info = new TMFDataFetcher($login);

The download includes a working example as well as the ColorParser, which can also be downloaded seperately.

With the $info variable you can now do lots of stuff which will be described now.


Public fields

• $id - The unique player id given by NADEO
• $nickname - the color coded nickname
• $freeaccount - true for a Nations account, false for an United account
• $accounttype - 'Nations' or 'United'
• $idzone - The unique id for the players home zone
• $zonepath - The complete zone path (like 'World/Germany/Saxony/Dresden')
• $maniastars - currently and probably forever unused by NADEO^^
• $lastmovedate - don't know what that indicates, but it's a Unix timestamp
• $skillpoints - United only, skillpoints in solo mode
• $skillrank - United only, skillrank in solo mode
• $ladder - a complex object that represents the ladder rank and points (see 'Ladder' section)
• $worldrank - a shortcut to the overall world ranking
• $ladderpoints - a shortcut to the overall ladder points
• $nationrank - a shortcut to the overall nation ranking
• $homezonerank - a shortcut to the overall homezone ranking
• $nation - The full name of the player's nation
• $homezone - The full name of the player's home zone
• $nationshort - The official short form of the player's nation
• $nationiconURL - a URL to the Nation icon (taken from ManiaZones)
• $nationflagURL - a URL to the Nation flag (taken from ManiaZones)
• $homezoneflagURL - a URL to the Homezone flag (taken from ManiaZones)

(please keep in mind that some of the flags may not work or exist, this is just experimental)

You can access the public fields like this:

Code: Select all

	$info = new TMFDataFetcher('fufi');
	echo $info->zonepath;

Public methods

• responseIsError() - returns a boolean, that indicates whether or not an error occured during the execution
• getError() - returns an array containing information about the error (error code and message)
• outputError() - directly prints out the error

Errors

The errors that can occur are either errors that come directly from NADEO (positive error number) or are generated inside the DataFetcher (negative error number). The following is a list of all possible errors:

• -8: HTTPS Authorization failed: Your login or password seem to be invalid. If you used capitals in the login, try writing it all lower case.
• -7: Neither the cURL module nor URL file access are enabled on your server.
• -6: The cURL module is not enabled on your server.
• -5: URL file access is not enabled on your server ("allow_url_fopen"). Enable it or try the cURL module.
• -4: Database not found. Please create it.
• -3: Could not connect to MySQL server. Please check your configuration file.
• -2: You need to install and enable the OpenSSL php extension.
• 7: Invalid "login" parameter.
• 14: Player unknown.
• 24: Challenge unknown.
• 26: Invalid "idchallenge" parameter.
• 9: Invalid "ccode" parameter.
• 41: Parent zone unknown.
• 57: Environment unknown.
• 62: Invalid "parentzonepath" parameter.
• 82: Code unknown.
• 125: Permission denied. You cannot use this request or you call it too often.
• 157: There is a missing parameter.
• 154: Wrong community code.
• 161: Invalid "first" parameter.
• 162: Invalid "count" parameter.

You'll probably see error 125 a few times

Ladder

There are multiple ways to access the ladder information of a player. The public field $ladder is your weapon of choice if you want to obtain the full environment specific ladder data. $ladder itself is a complex object which got its own fields and methods.

Public fields

• $Bay, $Coast, $Desert, $Island, $Rally, $Snow, $Stadium - Environment specific ladder objects
• $Merge - Overall ladder object

For the usage of these objects see the section 'Environment Ladders'.


Public methods

• getFullArray() - returns an array with all ladder data in it, use print_r() on the result to see its structure

You can access the public fields like this:

Code: Select all

	$info = new TMFDataFetcher('fufi');
	print_r($info->ladder->getFullArray()); //Display the structure and content of the ladder array
	$bayladder = $info->ladder->Bay;

Environment Ladders

The environment ladders are also objects with public fields and objects. I know this sounds all quite confusing, but if you get the hold of it, it's fairly easy to use. So here we go:


Public fields

• $wins - Number of wins
• $draws - Number of draws
• $losses - Number of losses
• $name - Name of the environment
• $ladderpoints - Number of LadderPoints for this specific environment
• $ranking - An associative array with ranking information for all zones (best use print_r() to see the structure)

Public methods

• getFullRankingArray() - just returns the $ranking field, so it is quite redundant
• getSpecificZoneRanking($zonepath) - returns the ranking for a spezific zone

Usage

Code: Select all

	$info = new TMFDataFetcher('fufi');
	$mergeRanking = $info->ladder->Merge->ranking;
	print_r($mergeRanking); //Display structure and content of the ranking array
	$stadiumWorldRanking = $info->ladder->Stadium->getSpecificZoneRanking('World');
	$stadiumWorldRank = $stadiumWorldRanking['rank'];

[s0xen]

Yeah Fish you did it.
Great job.
Going to use it!!

[MISI]

I send you a PM with question when it be released, but finally it is! :D

Thanks for it. ;-)

[Gekko]

Great Fish!!!!

Great Work!!

[Yorkshire]

Thanks for all the hard work once again

Regards,

Nick.

[SmashingDeluXe]

superb!!!

[wilameta]

I have no idea what this would be used for or how to use it (which means I most likely don't need to know) but you have obviously put a lot of work into it (not to mention all the other stuff you've made).
Just wanted to say thanks and let you know it is much apreciated.

[f*ckfish]

Just as a quick usage example. Say you got a clan website and want to display the ladder statistics of your clan members on your site, you can use the DataFetcher to get all the ladder information (and nickname, zone information etc.) from the NADEO stats server without having to bother about how this is done in detail. You can also use the data to create customized signature pics like the ones smurf provides on TM-Ladder.com. This class does everything automatically including connecting to the stats server, querying for player details, evaluating the xml reply and saving the data into easy-to-use variables.

[nocturne]

Awesome! Good job, Fish!

[v000nix]

Awesome work!

[Yorkshire]

Hi FF,

The script is failing when there are certain characters in players nicknames.

Try it with my login (Nick_W) and let me know if it fails for you also. It's OK when the data isn't cached, but after the first access when it's trying to use the local DB it fails! I'm just using your example.php at the moment.

TIA,

Nick.

[f*ckfish]

Thank you very much! Nice catch =) Actually the problem was not your nick but the & in your zonepath. Anyways, it works now in v1.1

[Yorkshire]

Top stuff, thanks FF

[Yorkshire]

Hi FF,

Another issue: If the player's country doesn't have any home zones, like Sweden, there doesn't seem to be a small flag and the country appears as the home zone! Try it with 'yellowcar11'.

Regards,

Nick.

[f*ckfish]

Thanks again, this is fixed now =)