Page 1 of 9

[PHP/MYSQL] TMFDataFetcher v1.3b

Posted: 06 Dec 2008 17:43
by 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 ( Image )
  • 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'];

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 06 Dec 2008 20:45
by s0xen
Yeah Fish you did it.
Great job.
Going to use it!!

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 06 Dec 2008 21:11
by MISI
I send you a PM with question when it be released, but finally it is! :D

Thanks for it. ;-)

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 07 Dec 2008 10:16
by Gekko
Great Fish!!!!

Great Work!! :gobananas:

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 07 Dec 2008 12:12
by Yorkshire
Thanks for all the hard work once again :)

Regards,

Nick.

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 07 Dec 2008 14:19
by SmashingDeluXe
superb!!! :thumbsup:

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 07 Dec 2008 15:30
by 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. :thumbsup:

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 07 Dec 2008 17:00
by 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.

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 08 Dec 2008 03:13
by nocturne
Awesome! Good job, Fish! :thumbsup:

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 09 Dec 2008 15:27
by v000nix
Awesome work! :thumbsup:

Re: [PHP/MYSQL] TMFDataFetcher

Posted: 12 Dec 2008 16:42
by 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.

Re: [PHP/MYSQL] TMFDataFetcher v1.1

Posted: 13 Dec 2008 05:18
by 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

Re: [PHP/MYSQL] TMFDataFetcher v1.1

Posted: 13 Dec 2008 08:15
by Yorkshire
Top stuff, thanks FF :)

Re: [PHP/MYSQL] TMFDataFetcher v1.1

Posted: 15 Dec 2008 07:44
by 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.

Re: [PHP/MYSQL] TMFDataFetcher v1.2

Posted: 15 Dec 2008 10:53
by f*ckfish
Thanks again, this is fixed now =)