Download the PHP package paquettg/leaguewrap without Composer

LeagueWrap

Version 0.6.4

[DEPRECATED] This repo is no longer maintained. Migrate to LeaguePHP/LeagueWrap.

LeagueWrap is a League of Legends API wrapper. The goal is to assist in the development of apps which depend on the Legue of Legends API in a quick and easy way. This project will help maintain a query limit for the API and a caching system, both which are still in progress. The mantra of this wrapper is to be lazy. We will only load the information you need when you need it and will do everything we can to reduce the amount of requests to the API. You'll notice, further into this README, choices that where made because of this mantra.

Install

This package can be found on packagist and is best loaded using composer. We support php 5.4, 5.5 and 5.6.

Simple Example

You can find many examples of how to use the wrapper and any of its parts (which you will most likely never touch) in the tests directory. The tests are done using PHPUnit and are very small, a few lines each, and are a great place to start. Given that, I'll still be showing examples of how the package is intended to work. The following example is a very simplistic usage of the package, good place to start.

The above gets the basic information about the user 'bakasan'. The above example illustrates the general idea of how things work. You load up the API with your given key, this API object can be used as many times as possible and is encouraged to only have one instance of it. From the API you can select which API to query (in this case the summoner API). Finally, you use a method, dependant of the API you query, to perform a request on that API.

Regions

You can set the region that you wish to query. By default it is 'na' but it can be changed to any string.

The above is straight forward and applies to all API request objects that this API will generate. There is also built in support for API calls that restrict regional access. Continuing from the above code snippet.

The LeagueWrap\Api\RegionException in the above example will contain the string 'The region "br" is not permited to query this API.'.

It is also important to note that some regions, such as kr, require a certain url to be used and do not work on prod.api.pvp.net. This is taken care of automaticly and as long as you have the most recent version of the wrapper you do not need to worry about this.

Cache

Caching is very important, we all know that and given the query limit impossed on every application this part of the package is very important to every developer. Given this, by default, the cache requires memcached to be installed and operating on default port and localhost. This can easily be changed by implementing your own version of the LeagueWrap\CacheInterface. Lets start with an example of how to use the cache.

The above applies to every future request done trough the $api methods. If you wish to set the cache time for any individual request, which is reasonable given that things change at a different pace.

Now we will only remember the response for the info() method is cached for 1 hour (3600 seconds). All other API objects, such as League, does not get effected by this cache time and, by default, does not cache the response. If you want to be able to only get a response if the request got a cache hit you can turn on the cacheOnly flag.

If the request was not found in cache it will throw a LeagueWrap\Exception\CacheNotFoundException exception. Simillarly to the remember() method this can also be called on the API endpoint object to only effect a certain request or endpoint while leaving the other ones untouched.

Now, lets say you don't want to use memcached or you wish to use the caching service provided by your framework? I completly understand and that is why you can implement the LeagueWrap\CacheInterface to implement your own cache. This Dependency Injection (DI) is also used by the Api client as shown in the Quick Reference section. To use your own cache implementation you can just do the following.

It's even easyer to do using StaticProxys, which you will see after the Rate Limiting section.

Rate Limiting

Even with caching you must also take into consideration the rate limits impossed on your API key. With this in mind we added support, similar to the support for caching, for limiting your request rate to the API. The rate limiting method requires memcached to be installed and operating on default port and localhost. As with the cache implementation you can always use your own version of the LeagueWrap\LimitInterface. Lets start with a basic example.

The above will set the 2 limits that you will use for the average developer key at the time of writting. You can add as many limits to the collection as you wish and each one will be tracked in the memcached memory. If you go over the limit the application will throw a LeagueWrap\Limit\LimitReachedException exception. As with the Cache, it's just as easy to implement this using the DI of a proper LeagueWrap\LimitInterface, you may even use multiple Limit interfaces... not that I see a point to it.

Also note that the limit functionality fully supports the Static API described further down.

Attach Static Data

Some requests come with static IDs referencing data in the static API. To do this you need to get the original data, extract the ID and follow up with a call to the static API. We make this entire process much simpler and optimize the amount of API requests that we do for all the data to reduce bandwidth and request. The extra static requests do not count towards your request limit so, in that regard, this does not effect the amount of requests you can do in a certain amount of time, it just takes time.

It will also optimize the static call so that the following example only attempt 3 static API calls even if it requires over 2 dozen different static id for multiple DTOs.

StaticProxy

You can use LeagueWrap through a static client to make it even easier to send API requests.

All normal API methods and API requests can be done using the static proxys and you no longer need to have an instance of LeagueWrap\Api. You must always set the key at least once before you can call any API requests but after it is set it will be used everywhere. The same can be applied to the cache reminder.

And with limits.

Http Error Exceptions

When you attempt to make any of the requests using this API and, for one reason or another, you receive an http error from the API we will throw an exception. All of the Http exception can be found in the LeagueWrap\Response namespace. The exceptions are split into 3 levels, depending on how specific you want to catch the exception at.

We attempts to implement all documented error codes that the API should throw at you. The response message can also be found in the Riot API documentation.

Quick Reference

LeagueWrap implements a very strict interface for the API where everything is within your control and easy to test. Here's a sampling of the possible startup methods.

Creates a new Api instance with the key. The key is mandatory and will throw a LeagueWrap\NoKeyException if not given. This instance will be used to orginize future calls to the API with out having to re-enter the key.

Using the DI principle we allow you to inject your own client object that implements LeagueWrap\ClientInterface. This allows you to use your own REST client if you wish to instead of Guzzle (which is what comes with the package).

Array Access

A good number of the DTO response will extend LeagueWrap\Dto\AbstractListDto instead of LeagueWrap\Dto\AbstractDto. The DTO that extends the abstract list gain the ability to be used as an array for access, traversing (using foreach()), and counting (using count()).

Setting Timeout

It is worth noting that the LeagueWrap\ClientInterface interface has a method called setTimeout($seconds). You can invoke this feature by calling this method on the request object.

Or, you can call it directly on the API object which will then apply to any future request objects created.

Summoner

To get an instance of the LeagueWrap\Api\Summoner object which is used to request information of the summoner API. This is the primary way you should be getting this object.

Selecting a valid version to be used by the summoner API. These version can be found in the object class file and we have a goal of only support at most 2 minor version of any major versions. Therefore you should not expect to be able to use v1.1 if v1.2 has been released for over a month.

Doing a summoner info request by the summoner name 'bakasan' will return a LeagueWrap\Dto\Summoner DTO that contains the information for this summoner.

You may also do an info request by the summoner id 76204. It works in the same way as the above method.

To do a single request and get the information for multiple summoner ids you can pass in an array. It will then return an array of all the information about said summoners. You really should use this to get information from multiple summoners as it only costs you 1 request.

You can also mix up ids and names and it will return an array. This will take 2 requests though, so be careful with it. Another limitation is a limit of 40 ids and 40 names per request, this is impossed by the API so we throw a LeagueWrap\Api\ListMaxException if you attempt this.

If you wish to know how many requests you have done so far with a single API object you can always request the request count. It will simply return the number of requests to the API it has performed so far.

To get the only the name of a summoner but no other information (saves on data transfer and speed) you can us the name() method in the summoner object.

It also accepts an array of ids instead of a single id and will return an associate array where id => summonername.

To get the runePage of a summoner you have multiple options. First using the summoner request object and the summoner id. This will return an array of LeagueWrap\Dto\RunePage objects. The runePages() method also accepts an array of ids instead of a single id.

And, lastly, you can use a summoner dto object that you received from info() or an array of such objects.

To get the first rune page of a summoner when you use the above method, passing in a summoner dto object, you can call the runePage() method of the object. The index of the runepage is what is expected as the first argument of the method call.

The same applies to the mastery pages but using the masteryPages() method instead of the runePages() method on the summoner request object. We also have a short cut method allInfo which will get all the information for each summoner passed in. It works in the same way as info but does an extra 2 request for the rune pages and mastery pages information

Champion

The champion API is very bare as most of the information in this API is static information so you are best to get that information from the static API. To get the champion request object you can call the champion() method on the API instance.

To get all champion information in a single request you only have to call the all() method. It will return a LeagueWrap\Dto\ChampionList object.

You can also get the information about a single champion by id.

Lastly, you can get a list of all free champions for the given region. This will return a LeagueWrap\Dto\ChampionList object, containing each free champion for the given region and week.

Game

The game API is very simple but returns a lot of information about the given summoner. To get this request object you only need to call game() on the API object.

We have 2 ways of getting the information about a summoners recent games. You can either pass in the summoner id or the summoner object LeagueWrap\Dto\Summoner which has been loaded by a previous call to info.

Match

NOTE: The MatchHistory API endpoint has been deprecated by Riot and will be removed on September 22nd, 2015. Please use the Matchlist endpoint instead!

The Match API can be used to get a more detailed match history then the game API provides. This does only include ranked games though. You can either pass in the summoner id or a summoner object LeagueWrap\Dto\Summoner.

The Matchlist API gives you a condensed list of all played ranked matches since the match api went live. It will return a LeagueWrap\Dto\MatchList and you can pass in the summoner id or a summoner object LeagueWrap\Dto\Summoner.

You can add filter parameters for queue, season, played champions, start and end index as well as time, respectivly.

For even more details on a specific match, the match API can be used to get detailed statistics for every summoner as well as an optional timeline of events. As argument, you need to pass a match id that you can get from LeagueWrap\Dto\Match->matchId, LeagueWrap\Dto\MatchReference->matchId or LeagueWrap\Dto\Game->gameId.

To include the timeline:

League

The documentation for the League Api is not complete but it is fully functional.

Stat

The documentation for the Stat Api is not complete but it is fully functional.

Champion Mastery

The documentation for the Champion mastery Api is not complete but it is fully functional.

Team

The documentation for the Team Api is not complete but it is fully functional.

Current Game

The current game API gives information about a running game.

Static Data

The documentation for the Static Data Api is not complete but it is fully functional.

Status

The documentation for the Status Api is not complete but it is fully functional.

Disclaimer

It is the responsibility of the User to evaluate the content and I will not be liable for any damage or loss caused by the use of this open source software. We do not provide any guarantee that the software will do as expeccted and it is the responsiblity of the User to ensure that the interaction with the software is correct.

This product is not endorsed, certified or otherwise approved in any way by Riot Games, Inc. or any of its affiliates.