[PHP/MYSQL] TMFDataFetcher v1.3b

This is the place where you can find everything related to the dedicated server, control scripts and community tools.

Moderators: Pit Crew, TM-Patrol

Post Reply
User avatar
f*ckfish
Pit Crew
Pit Crew
Posts: 1302
Joined: 15 Jun 2007 07:59
Owned TM-games: TMNF, TMUF
Location: Dresden, Germany
Contact:

[PHP/MYSQL] TMFDataFetcher v1.3b

Post by f*ckfish » 06 Dec 2008 17:43

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'];
inactive, sorry

s0xen
happy cruiser
happy cruiser
Posts: 115
Joined: 11 Nov 2007 20:31
Owned TM-games: TMN

Re: [PHP/MYSQL] TMFDataFetcher

Post by s0xen » 06 Dec 2008 20:45

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

User avatar
MISI
sunday driver
sunday driver
Posts: 54
Joined: 29 Oct 2006 20:46
Owned TM-games: TMO, TMN, TMUF
Location: Bydgoszcz, Poland
Contact:

Re: [PHP/MYSQL] TMFDataFetcher

Post by MISI » 06 Dec 2008 21:11

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

Thanks for it. ;-)
Image
Image

Gekko
speedy pilot
speedy pilot
Posts: 550
Joined: 03 Sep 2006 18:20
Owned TM-games: ALL
Location: Naples - Italy
Contact:

Re: [PHP/MYSQL] TMFDataFetcher

Post by Gekko » 07 Dec 2008 10:16

Great Fish!!!!

Great Work!! :gobananas:

Yorkshire
smooth traffic navigator
smooth traffic navigator
Posts: 192
Joined: 21 May 2008 08:39
Owned TM-games: TMUF

Re: [PHP/MYSQL] TMFDataFetcher

Post by Yorkshire » 07 Dec 2008 12:12

Thanks for all the hard work once again :)

Regards,

Nick.

User avatar
SmashingDeluXe
sunday driver
sunday driver
Posts: 58
Joined: 04 Dec 2007 20:38
Owned TM-games: All
Manialink(s): NO
Location: Germany
Contact:

Re: [PHP/MYSQL] TMFDataFetcher

Post by SmashingDeluXe » 07 Dec 2008 14:19

superb!!! :thumbsup:
Intel Core Duo Quad Q6600 4x 2.4 Ghz / Gainward NVidia GeForce 8800 GT 1024MB / 4GigRAM DDR2 1066Mhz
Gigabyte P35-DS3P / Win7 Ultimate

JOIN OUR SERVER!
Tech&Mini.ne
http://www.tm-creative.org

wilameta
speedy pilot
speedy pilot
Posts: 371
Joined: 09 May 2008 01:08
Owned TM-games: TMNF, TMUF
Location: Columbus, Ohio, Usa

Re: [PHP/MYSQL] TMFDataFetcher

Post by wilameta » 07 Dec 2008 15:30

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:

User avatar
f*ckfish
Pit Crew
Pit Crew
Posts: 1302
Joined: 15 Jun 2007 07:59
Owned TM-games: TMNF, TMUF
Location: Dresden, Germany
Contact:

Re: [PHP/MYSQL] TMFDataFetcher

Post by f*ckfish » 07 Dec 2008 17:00

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.
inactive, sorry

nocturne
solid chaser
solid chaser
Posts: 1390
Joined: 08 Jun 2007 18:48
Owned TM-games: all
Contact:

Re: [PHP/MYSQL] TMFDataFetcher

Post by nocturne » 08 Dec 2008 03:13

Awesome! Good job, Fish! :thumbsup:

v000nix
happy cruiser
happy cruiser
Posts: 138
Joined: 09 Jan 2008 19:26
Owned TM-games: TMN, TMU, TMUF
Manialink(s): v000nix, TManiacs
Location: Germany
Contact:

Re: [PHP/MYSQL] TMFDataFetcher

Post by v000nix » 09 Dec 2008 15:27

Awesome work! :thumbsup:

Yorkshire
smooth traffic navigator
smooth traffic navigator
Posts: 192
Joined: 21 May 2008 08:39
Owned TM-games: TMUF

Re: [PHP/MYSQL] TMFDataFetcher

Post by Yorkshire » 12 Dec 2008 16:42

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.

User avatar
f*ckfish
Pit Crew
Pit Crew
Posts: 1302
Joined: 15 Jun 2007 07:59
Owned TM-games: TMNF, TMUF
Location: Dresden, Germany
Contact:

Re: [PHP/MYSQL] TMFDataFetcher v1.1

Post by f*ckfish » 13 Dec 2008 05:18

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
inactive, sorry

Yorkshire
smooth traffic navigator
smooth traffic navigator
Posts: 192
Joined: 21 May 2008 08:39
Owned TM-games: TMUF

Re: [PHP/MYSQL] TMFDataFetcher v1.1

Post by Yorkshire » 13 Dec 2008 08:15

Top stuff, thanks FF :)

Yorkshire
smooth traffic navigator
smooth traffic navigator
Posts: 192
Joined: 21 May 2008 08:39
Owned TM-games: TMUF

Re: [PHP/MYSQL] TMFDataFetcher v1.1

Post by Yorkshire » 15 Dec 2008 07:44

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.

User avatar
f*ckfish
Pit Crew
Pit Crew
Posts: 1302
Joined: 15 Jun 2007 07:59
Owned TM-games: TMNF, TMUF
Location: Dresden, Germany
Contact:

Re: [PHP/MYSQL] TMFDataFetcher v1.2

Post by f*ckfish » 15 Dec 2008 10:53

Thanks again, this is fixed now =)
inactive, sorry

Post Reply