[MP4][Tutorial] Basic setup - getting the example run

Maniaplanet public API, ManiaConnect system and the open source PHP SDK.

Moderator: NADEO

Post Reply
User avatar
askuri
Posts: 284
Joined: 18 Oct 2011, 15:01
Location: Germany

[MP4][Tutorial] Basic setup - getting the example run

Post by askuri » 20 Mar 2018, 19:13

With the introduction of MP4, the whole Webservices API has been reworked and most of the old documentation can be considered obsolete. Unfortunately, after soon one year, we still don’t have an easily understandable introduction to it.
This tutorial is meant for the newbies, who have never used composer before, but are familiar with PHP.

Install composer
getcomposer.org wrote:Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
You might have noticed that the new WS "SDK" client has shrinked to only two tiny files, when you look at the source code. When trying to run them together with the example, you will see that more files are missing.
This is because the dev’s at Nadeo made use of the library "league/oauth2-client”, instead of writing their whole one client/server software. This library in turn, also depends on many other libraries, which have also their dependencies. You might see where it is leading: a big dependency tree. Theoretically speaking, you could try to download all the libraries which depend on each other and make our Webservices Client work that way. I guarantee you, it will take you more than one hour.
Alternatively, you simply install composer and let it do the job for you, just within seconds. This is why composer is awesome.

You’ll find instructions on how to install composer here. In this tutorial I assume you installed it globally, means you can use it from anywhere with the "composer” command. Because that process depends on your OS and might change over time, I'll not describe it here.

Get the webservices SDK
In the topic where magnetik announced the new library, he gave us a github link, and a link to Packagist. Packagist is the official public repository for composer packages. We click the second link to Packagist, where we find the following line at the very top:

Code: Select all

composer require maniaplanet/oauth2-maniaplanet
That is the command we use to download the library to our current working directory. So open CMD (Windows) or your terminal (Linux), navigate to the folder where you want to start your project and execute the command above. If it gives you something like "unkown file or command”, it means you didn’t install composer globally.
After latest one minute composer should have finished downloading. Now you’ll find a folder called vendor, and two files called composer.json and composer.lock. If you take a look into the folder, you’ll find all the dependencies (packages/libraries) of the WS SDK, with the SDK located in vendor/maniaplanet/oauth2-maniaplanet. In that folder, you will also find some examples. Apart from that, you can leave the vendor folder untouched.

Creating an account
Just like in MP3, it is necessary to create your own webservices account(s). The process has changed since, though.
Open http://maniaplanet.com and login with your username and password, just like you log in the game client. After that, you’ll find the "Manage" button. Hover/click on it and navigate to webservices. On the left, create a new application and fill the form. The validation code is a five letters code, which only you should know. Then submit.
Unfortunately, we have to go back to existing applications to edit the one we just created. The form looks almost the same, except we have a button called "Add a redirect URL". We click that and in the field that just appeared, we enter the URL where the OAuth server should redirect us back. In our example it is the same as the homepage URL, so simply http://example.org/myproject for example. If you are working on localhost, that’s fine.

Setup the example
Back to the project folder, we copy the example file (index.php) of the SDK from the vendor folder to the document root of our project, next to the vendor folder. Open it with an editor.
In one of the first lines of the example, a file called autoload.php is being required. It is generated by composer and saves us the work of requiring every single library file. So because we moved the example, we have to alter it to require("vendor/autoload.php");
Next step is to enter your credentials (clientID, clientSecret) as well as the redirectUri. You find all of them on the website, where we just created the account. Make sure the redirectUri is exactly the same, as the one you have entered on the website. If it is not the same, you’ll end up with an error after login.
Save the file.
Open your browser and navigate to your project. If you open the site, you will be immediately redirected to the Maniaplanet login. Log in and you will be redirected back to your site. If all went fine, you will see a lot of debug information. That means, you are successfully logged in.
The last section of the page is the dump of all information you have received. You should cache it in a database, in order to reduce the API requests.
Like in MP3, there is different "scopes". They are like the categories of data, of which you ask the users to give you access to. In the example they used the scopes basic and maps. You can find more scopes here: https://doc.maniaplanet.com/web-services/oauth2#scopes


I hope this was helpful to someone. It is still a work in progress, I will (hopefully) extend it later.
Last edited by askuri on 21 Mar 2018, 05:06, edited 2 times in total.
ManiaCDN.net: the new free hoster for your custom content

Specs: i5 6600K; MSI Z170A Gaming Pro; 2x8GB Crucial DDR4 2133MHz; Intel HD Graphics 530; Linux Mint & Windows 10 Home

User avatar
Xymph
Posts: 1340
Joined: 15 Jun 2010, 20:35
Contact:

Re: [MP4][Tutorial] Basic setup - getting the example run

Post by Xymph » 20 Mar 2018, 20:03

Your url tags do need http(s):// prefixes. ;)
Developer of XASECO for TMF/TMN ESWC & XASECO2 for TM²: see XAseco.org
Find your way around the Mania community from the TMN ESWC hub, TMF hub, TM² hub, and SM hub

User avatar
askuri
Posts: 284
Joined: 18 Oct 2011, 15:01
Location: Germany

Re: [MP4][Tutorial] Basic setup - getting the example run

Post by askuri » 20 Mar 2018, 20:57

I think you talk about the redirectUri and homepage URL? Can't remember I forgot http(s) in the initial post.

@TMark: thanks for making the post sticky.
ManiaCDN.net: the new free hoster for your custom content

Specs: i5 6600K; MSI Z170A Gaming Pro; 2x8GB Crucial DDR4 2133MHz; Intel HD Graphics 530; Linux Mint & Windows 10 Home

User avatar
Xymph
Posts: 1340
Joined: 15 Jun 2010, 20:35
Contact:

Re: [MP4][Tutorial] Basic setup - getting the example run

Post by Xymph » 20 Mar 2018, 22:10

askuri wrote:
20 Mar 2018, 20:57
I think you talk about the redirectUri and homepage URL? Can't remember I forgot http(s) in the initial post.
You did with the getcomposer.org and maniaplanet.com links. They are currently local to the forum, and thus Not Found.
Developer of XASECO for TMF/TMN ESWC & XASECO2 for TM²: see XAseco.org
Find your way around the Mania community from the TMN ESWC hub, TMF hub, TM² hub, and SM hub

User avatar
askuri
Posts: 284
Joined: 18 Oct 2011, 15:01
Location: Germany

Re: [MP4][Tutorial] Basic setup - getting the example run

Post by askuri » 21 Mar 2018, 05:08

Fixed it. Thank you very much xymph!
ManiaCDN.net: the new free hoster for your custom content

Specs: i5 6600K; MSI Z170A Gaming Pro; 2x8GB Crucial DDR4 2133MHz; Intel HD Graphics 530; Linux Mint & Windows 10 Home

Post Reply

Return to “Maniaplanet Web Services”

Who is online

Users browsing this forum: No registered users and 2 guests