by oorf I f*ckfish aka Alexander P.
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.
TMFDataFetcher All Versions
- Replaced all shorttags with standard tags
- 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
- If the nation was equal to the homezone, it was not recognized - fixed
- XML specific characters in nicknames or zonepaths caused the script to crash - fixed
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)
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 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 =)
To get the TMFDataFetcher to work, you'll have to do the following steps:
- Copy the contents of the archive into your project folder
- include the file into your php source:
Code: Select all
- Instantiate the class with a login
Code: Select all
$info = new TMFDataFetcher($login);
With the $info variable you can now do lots of stuff which will be described now.
- $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)
You can access the public fields like this:
Code: Select all
$info = new TMFDataFetcher('fufi'); echo $info->zonepath;
- 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
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.
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.
- $Bay, $Coast, $Desert, $Island, $Rally, $Snow, $Stadium - Environment specific ladder objects
- $Merge - Overall ladder object
- getFullArray() - returns an array with all ladder data in it, use print_r() on the result to see its structure
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;
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:
- $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)
- getFullRankingArray() - just returns the $ranking field, so it is quite redundant
- getSpecificZoneRanking($zonepath) - returns the ranking for a spezific zone
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'];