paquettg/leaguewrap

该包已被弃用且不再维护。作者建议使用 league-php/leaguewrap 包。

英雄联盟API的包装器。

维护者

详细信息

github.com/paquettg/leaguewrap

主页

源代码

问题

安装量: 19,668

依赖者: 1

建议者: 0

安全性: 0

星标: 71

关注者: 14

分支: 32

开放问题: 12

0.6.2 2015-03-26 18:03 UTC

Requires

Requires (Dev)

MIT 7dbcb8471b98dd71d1e665a6cbd1dbf2629c802d

apiproxywrapfacadeleaguelegends

This package is auto-updated.

Last update: 2020-02-05 08:31:46 UTC

README

版本 0.6.4

Build Status Coverage Status

[已弃用] 此存储库不再维护。请迁移到 LeaguePHP/LeagueWrap。

LeagueWrap 是英雄联盟API的包装器。目标是帮助以快速和简单的方式开发依赖英雄联盟API的应用程序。该项目将帮助维护API的查询限制和缓存系统，这两者仍在进行中。这个包装器的座右铭是懒惰。我们只在需要的时候加载所需的信息，并将尽可能减少对API的请求。你会在 README 的进一步内容中注意到由于这个座右铭而做出的选择。

安装

该包可以在 packagist 上找到，并建议使用 composer 加载。我们支持 php 5.4、5.5 和 5.6。

简单示例

你可以在测试目录中找到很多如何使用这个包装器及其任何部分的示例（你很可能会永远不接触它们）。测试使用PHPUnit进行，非常小，每个只有几行，是开始的好地方。考虑到这一点，我仍会展示这个包应该如何工作的示例。以下是一个非常简单的包使用示例，是一个很好的起点。

use LeagueWrap\Api;

$api      = new Api($myKey);            // Load up the API
$summoner = $api->summoner();           // Load up the summoner request object.
$bakasan  = $summoner->info('bakasan'); // Get the information about this user.

$bakasan = $summoner->info(74602);      // same thing as above, just to show that an id will work

echo $bakasan->summonerLevel;           // 30
echo $bakasan->id;                      // 74602
echo $bakasan->name;                    // "bakasan"
echo $bakasan->profileIconId;           // 24
echo $bakasan->revisionDate;            // 1387391523000
echo $bakasan->revisionDateStr;         // "12/18/2013 06:32 PM UTC"

上述代码获取了用户 'bakasan' 的基本信息。上述示例展示了事物工作的一般思路。你用给定的密钥加载API，这个API对象可以尽可能多地使用，并鼓励只有一个实例。从API中，你可以选择要查询哪个API（在这种情况下是召唤师API）。最后，你使用一个方法，该方法取决于你查询的API，对该API执行请求。

区域

你可以设置你希望查询的区域。默认是 'na'，但可以更改为任何字符串。

use LeagueWrap\Api;

$api = new Api($myKey);  // Load up the API
$api->setRegion('euw');  // Set the region to 'euw'

上述代码非常直接，适用于此API将生成的所有API请求对象。此外，还内置了对限制区域访问的API调用支持。从上述代码片段继续。

$api->setRegion('br');                 // Set the region to 'br'
$champions = $api->champion()->free(); // will throw a LeagueWrap\Api\RegionException

上述示例中的 LeagueWrap\Api\RegionException 将包含字符串 'The region "br" is not permited to query this API.'。

需要注意的是，一些区域，如 kr，需要使用特定的 URL，且在 prod.api.pvp.net 上不起作用。这会自动处理，只要你使用的是包装器的最新版本，你就不需要担心这个问题。

缓存

缓存非常重要，我们都知道这一点，考虑到每个应用都受到查询限制，这部分包对于每个开发者来说都非常重要。因此，默认情况下，缓存需要安装并运行在默认端口和localhost上memcached。这可以通过实现自己的LeagueWrap\CacheInterface版本来轻松更改。让我们从一个如何使用缓存的例子开始。

use LeagueWrap\Api;

$api = new Api($myKey); // Load up the API
$api->remember(60);     // Set the cache to remember every request for 60 seconds
// or
$api->remember();     // Enable cache with the default value for each API call.
$api->remember(null); // Same as above, null is the default value

上面的内容适用于通过$api方法进行的每个后续请求。如果您希望为任何单个请求设置缓存时间，这是合理的，因为事情变化的速度不同。

use LeagueWrap\Api;

$api      = new Api($myKey);           // Load up the API
$summoner = $api->summoner()           // Get the summoner API request object
                ->remember(3600);      // Remember all request done by this single request object
$bakasan = $summoner->info('bakasan'); // This request is cached for 1 hour (3600 seconds)

现在，我们只记得info()方法的响应被缓存了1小时（3600秒）。所有其他API对象，如League，都不会受到这个缓存时间的影响，并且默认情况下不会缓存响应。如果您希望只有在请求命中缓存时才获取响应，可以开启cacheOnly标志。

use LeagueWrap\Api;

$api = new Api($myKey); // Load up the API
$api->remember()        // Enable cache with the default values.
    ->setCacheOnly()    // Only check the cache, don't do any http requests.

如果请求在缓存中未找到，它将抛出LeagueWrap\Exception\CacheNotFoundException异常。与remember()方法类似，这也可以在API端点对象上调用，仅影响某些请求或端点，而不会影响其他端点。

现在，假设您不想使用memcached，或者希望使用框架提供的缓存服务？我完全理解，这就是为什么您可以实现LeagueWrap\CacheInterface来自定义缓存。这种依赖注入（DI）在快速参考部分也由API客户端使用。要使用自己的缓存实现，您只需这样做。

use LeagueWrap\Api;

$api = new Api($myKey);       // Load up the API
$api->remember(60, $myCache); // Set the cache to use your own cache implementation
// or
$api->remember(null, $myCache); // Set the cache implementation but keep the default cache times

在速率限制部分之后，您将看到使用StaticProxys做起来甚至更简单。

速率限制

即使有缓存，您还必须考虑施加在API密钥上的速率限制。考虑到这一点，我们添加了对API请求速率限制的支持，类似于对缓存的支持。速率限制方法需要安装并运行在默认端口和localhost上的memcached。与缓存实现一样，您始终可以使用自己的LeagueWrap\LimitInterface版本。让我们从一个基本的例子开始。

use LeagueWrap\Api;

$api = new Api($myKey); // Load up the API
$api->limit(10, 10);    // Set a limit of 10 requests per 10 seconds
$api->limit(500, 600);  // Set a limit of 500 requests per 600 (10 minutes) seconds

上面的示例将设置在撰写本文时为平均开发者密钥使用的两个限制。您可以根据需要向集合中添加尽可能多的限制，每个限制都会在memcached内存中跟踪。如果您超过限制，应用程序将抛出LeagueWrap\Limit\LimitReachedException异常。与缓存一样，使用正确的LeagueWrap\LimitInterface的DI实现这一点同样简单，您甚至可以使用多个限制接口... 我看不出这样做有什么意义。

use LeagueWrap\Api;

$api = new Api($myKey);             // Load up the API
$api->limit(10, 10, $myLimiter);    // Set a limit using your own limit implementation
$api->limit(500, 600, $myLimiter);

请注意，限制功能完全支持下面的静态API。

附加静态数据

一些请求包含引用静态API中数据的静态ID。为此，您需要获取原始数据，提取ID，然后对静态API进行调用。我们使整个过程变得更加简单，并优化了我们对所有数据进行API请求的数量，以减少带宽和请求。额外的静态请求不计入您的请求限制，因此，在这方面，这不会影响您在一定时间内可以进行的请求数量，它只是花费时间。

use LeagueWrap\Api;

$api = new Api($myKey);                          // Load up the Api
$api->attachStaticData();                        // Tell the api to attach all static data
$champion = $api->champion()->championById(10);  // Get the champion by id 10
echo $champion->championStaticData->name;        // Outputs "Kayle"

它还将优化静态调用，即使需要超过20个不同的静态ID来处理多个DTO，下面的示例也只会尝试3次静态API调用。

use LeagueWrap\Api;

$api = new Api($myKey);                          // Load up the Api
$api->attachStaticData();                        // Tell the API to attach all static data
$match = $api->match()->match(1399898747);
echo $match->team(0)->ban(0)->championStaticData->name; // outputs LeBlanc

静态代理

您可以通过静态客户端使用LeagueWrap，使发送API请求更加简单。

LeagueWrap\StaticApi::mount(); // Mount all the static static proxys

Api::setKey('my-key'); // set the key for the API

$summoner = Api::summoner(); // get a LeagueWrap\Api\Summoner instance
$summoner->info('bakasan');  // get info about summoner
echo $summoner->bakasan->id; // 74602
// or
Summoner::info('bakasan');        // get info about the summoner 'bakasan'
echo Summoner::get('bakasan')->id // 74602

Game::recent(Summoner::get('bakasan'));          // get the recent games for bakasan
$game = Summoner::get('bakasan')->recentGame(0); // get the most recent game

所有正常API方法和API请求都可以使用静态代理完成，您不再需要LeagueWrap\Api的实例。您必须至少设置一次密钥才能调用任何API请求，但设置后它将在所有地方使用。同样适用于缓存提醒。

LeagueWrap\StaticApi::mount(); // Mount all the static static proxys

Api::setKey('my-key');                // set the key for the API
Api::remember(60);                    // cache all request for 60 seconds
$bakasan = Summoner::info('bakasan'); // cached for 60 seconds
// or
Api::remember(60, $myCache);          // cache all request using my own
$bakasan = Summoner::info('bakasan'); // cached for 60 seconds using $myCache

并且有限制。

LeagueWrap\StaticApi::mount(); // Mount all the static static proxys

Api::setKey('my-key');                // set the key for the API
Api::remember();                      // cache all request for the default number of seconds
Api::limit(10, 10);                   // Limit of 10 request per 10 seconds
Api::limit(500, 600);                 // Limit of 500 request per 10 minutes
$bakasan = Summoner::info('bakasan'); // cached for 60 seconds

HTTP错误异常

当您尝试使用此API发出任何请求时，由于某种原因，您从API收到HTTP错误，我们将抛出异常。所有HTTP异常都可以在LeagueWrap\Response命名空间中找到。异常分为3个级别，具体取决于您想要捕获异常的详细程度。

use LeagueWrap\Api;

$api = new Api($myKey); // Load up the API
try
{
	$summoner = $api->summoner(); // Load up the summoner request object.
}
catch (LeagueWrap\Response\Http404 $e)
{
	// Only thrown when a 404 http error is found
}
catch (LeagueWrap\Response\HttpClientError $e)
{
	// All Http4XX extend this abstract class.
	// Which is a catch all for client errors
}
catch (LeagueWrap\Response\ResponseException $e)
{
	// All http error codes extends from this abstract class.
	// This is a catch all (both 4xx and 5xx http errors)
	
	// To get more detailed information about the response, the following methods are available
	$e->hasResponse(); // Checks if response was attached
	$response = $e->getResponse(); // Instance of LeagueWrap\Response
	// In some cases like resolving 429 status codes, information from headers could be useful
	// see: https://developer.riotgames.com/docs/rate-limiting 
	$headers = $response->getHeaders(); // ['Retry-After' => ..., ...]
	$response->hasHeader('Retry-After');
	$response->getHeader('that does not exist'); // null
}
catch (LeagueWrap\Response\UnderlyingServiceRateLimitReached $e)
{
    // See https://github.com/paquettg/leaguewrap/issues/119
    // Extends Http429 for backwards compatibility
}

我们尝试实现API应抛给您的所有已记录的错误代码。响应消息也可以在Riot API文档中找到。

快速参考

LeagueWrap为API实现了一个非常严格的接口，其中所有内容都在您的控制之下，并且易于测试。以下是可能的启动方法的样本。

使用密钥创建一个新的Api实例。密钥是必需的，如果没有提供，将抛出LeagueWrap\NoKeyException异常。此实例将用于组织未来的API调用，而无需重新输入密钥。

$api = new \LeagueWrap\Api($myKey);

使用DI原则，我们允许您注入自己的客户端对象，该对象实现了LeagueWrap\ClientInterface。这允许您使用自己的REST客户端，如果您愿意，而不是使用Guzzle（这是包中包含的）。

$api = new \LeagueWrap\Api($myKey, $myClient);

数组访问

许多DTO响应将扩展LeagueWrap\Dto\AbstractListDto而不是LeagueWrap\Dto\AbstractDto。扩展抽象列表的DTO将获得用作数组进行访问、遍历（使用foreach()）和计数（使用count()）的能力。

$game       = $api->game();
$games      = $game->recent(74602);
$mostRecent = $games->game(0);
// instead to access
$mostRecent = $games[0];

// traversing
foreach ($games as $game)
{
	// do some stuff to each recent game
}

// counting
$recentGameCount = count($games);

设置超时

值得注意的是，LeagueWrap\ClientInterface接口有一个名为setTimeout($seconds)的方法。您可以通过在请求对象上调用此方法来调用此功能。

$game = $api->game()
            ->setTimeout(3.14); // wait a maximum of 3.14 seconds for a response.

或者，您可以直接在API对象上调用它，这将应用于创建的任何未来请求对象。

$api->setTimeout(3.14);
$game       = $api->game();
$mostRecent = $game->recent(74602); // this reques will wait a maximum of 3.14 seconds for a response.

召唤师

获取LeagueWrap\Api\Summoner对象的实例，该对象用于请求召唤师API的信息。这是获取此对象的主要方式。

$summoner = $api->summoner();

选择召唤师API使用的有效版本。这些版本可以在对象类文件中找到，我们的目标是最多支持任何主要版本的2个次要版本。因此，如果您在v1.2发布超过一个月后仍然期望使用v1.1，这是不合理的。

$summoner->selectVersion('v1.2')

通过召唤师名称“bakasan”进行召唤师信息请求将返回包含此召唤师信息的LeagueWrap\Dto\Summoner DTO。

$bakasan = $summoner->info('bakasan');

您也可以通过召唤师ID 76204进行信息请求。它与上述方法的工作方式相同。

$info = $summoner->info(76204);

要执行单个请求并获取多个召唤师ID的信息，您可以传入一个数组。然后它会返回关于这些召唤师的全部信息数组。您真应该使用这个方法来获取多个召唤师的信息，因为这只需要您1次请求。

$summoners = $summoner->info([
	76204,
	1234,
	111111,
	1337,
]);

您还可以混合使用ID和名称，并返回一个数组。但这需要2次请求，所以请小心使用。另一个限制是每次请求的ID和名称数量最多为40，这是API规定的，如果您尝试这样做，我们会抛出LeagueWrap\Api\ListMaxException异常。

$summoners = $summoner->info([
	76204,
	'C9 Hai',
	'riot',
	1234,
]);

如果您想了解使用单个API对象到目前为止已执行了多少次请求，您总是可以请求请求计数。它将简单地返回到目前为止已对API执行的请求次数。

$summoner->getRequestCount()

要获取召唤师的名字而不获取其他信息（节省数据传输和速度），您可以在召唤师对象中使用name()方法。

$names = $summoner->name(76204);

它还接受ID数组而不是单个ID，并返回一个关联数组，其中id => summonername。

$names = $summoner->name([
	76204,
	1234,
	1337,
	123456789
]);

要获取召唤师的符文页，您有多种选择。首先使用召唤师请求对象和召唤师ID。这将返回一个LeagueWrap\Dto\RunePage对象数组。符文页方法也接受ID数组而不是单个ID。

$runePages = $summoner->runePages(76204);

最后，您可以使用从info()接收的召唤师DTO对象或此类对象的数组。

$summoner->runePages($bakasan);

当您使用上述方法并通过传递召唤师DTO对象来获取召唤师的第一个符文页时，您可以调用对象的runePage()方法。符文页的索引是方法调用中期望的第一个参数。

$runePage = $bakasan->runePage(0);

同样适用于精通页，但使用的是召唤师请求对象上的masteryPages()方法而不是runePages()方法。我们还有一个快捷方法allInfo，它将获取传递给每个召唤师的全部信息。它与info方法的工作方式相同，但会额外执行2次请求来获取符文页和精通页信息。

$bakasan = $summoner->allInfo(76204); // 3 requests
// or
$summoners = $summoner->allInfo([
	76204,
	'C9 Hai',
	'riot',
	1234,
]); // this will take 4 requests

英雄

英雄API非常简单，因为该API中的大部分信息都是静态信息，所以您最好从静态API获取这些信息。要获取英雄请求对象，您可以在API实例上调用champion()方法。

$champion = $api->champion();

要使用单个请求获取所有英雄信息，您只需要调用all()方法。它将返回一个LeagueWrap\Dto\ChampionList对象。

$champions = $champion->all();
$kayle     = $champions->getChampion(10);
// or
$kayle     = $champions->champions[10];

您还可以通过ID获取单个英雄的信息。

$aatrox = $champion->championById(266);

最后，您还可以获取给定区域的全部免费英雄列表。这将返回一个包含给定区域和每周每个免费英雄的LeagueWrap\Dto\ChampionList对象。

$freeChampions = $champion->free();

游戏

游戏API非常简单，但返回了关于给定召唤师的大量信息。要获取此请求对象，您只需要在API对象上调用game()。

$game = $api->game();

我们有两种获取召唤师最近游戏信息的方法。您可以选择传递召唤师ID或召唤师对象LeagueWrap\Dto\Summoner，该对象是通过info之前的调用加载的。

$games = $game->recent(74602);
$game  = $games->recentGame(0);
// or
$game  = $games->games[0];
// or
$game->recent($bakasan);
$game = $bakasan->recentGame(0);

比赛

注意：MatchHistory API 端点已被 Riot 弃用，并将于2015年9月22日删除。请使用 Matchlist 端点代替！

Match API 可以用来获取比游戏 API 提供的更详细的比赛历史。但这仅包括排位赛。您可以通过传递召唤师 ID 或召唤师对象 LeagueWrap\Dto\Summoner 来实现。

$matchHistory = $api->matchHistory();
$matches = $matchHistory->history(74602);

$match = $matches[0];

Matchlist API 会为您提供一个自比赛 API 上线以来所有玩过的排位赛的精简列表。它将返回一个 LeagueWrap\Dto\MatchList，您可以通过传递召唤师 ID 或召唤师对象 LeagueWrap\Dto\Summoner 来实现。

$matchlistapi = $api->matchlist();
$matchlist = $matchlist->matchlist(30447079);
$numberOfplayedGames = $matchlist->totalGames;
$roleInGame = $matchlist->match(0)->role;

您可以为队列、赛季、已玩过的英雄、起始和结束索引以及时间添加过滤器参数。

$matchlistapi = $api->matchlist();
$matchlist = $matchlist->matchlist(30447079, "RANKED_SOLO_5x5", "SEASON2015", [1,2,3], 5, 7, 12346586, 35483434);

对于特定比赛的更多细节，可以使用 Match API 获取每个召唤师的详细统计数据以及可选的事件时间线。作为参数，您需要传递一个匹配 ID，您可以从 LeagueWrap\Dto\Match->matchId、LeagueWrap\Dto\MatchReference->matchId 或 LeagueWrap\Dto\Game->gameId 获取。

$matchapi = $api->match();
$match = $matchapi->match(1399898747);

要包括时间线

$matchapi = $api->match();
$match = $matchapi->match(1399898747, true);

$timeline = $match->timeline

联盟

关于 League API 的文档尚不完整，但它完全可用。

$league = $api->league();

统计

关于 Stat API 的文档尚不完整，但它完全可用。

$stat = $api->stat();

英雄精通

关于英雄精通 API 的文档尚不完整，但它完全可用。

$championMastery = $api->championMastery();
$masteryList = $championMastery->champions($summonerId);
$championPointsAnnie = $masteryList->getChampion(1)->championPoints

队伍

关于队伍 API 的文档尚不完整，但它完全可用。

$team = $api->team();

当前游戏

当前游戏 API 提供有关进行中游戏的信息。

// receive a current game
$currentGame = $api->currentGame();
$game = $currentGame->currentGame($summonerId);

$game->ban(1) // first ban of the ban phase
$game->observers->encriptionKey // observer key for spectating

// participant of a game
$participant = $game->participant($summonerId)
$participant->masteries
$participant->runes
$participant->championId

静态数据

关于静态数据 API 的文档尚不完整，但它完全可用。

$staticData = $api->staticData();

状态

关于状态 API 的文档尚不完整，但它完全可用。

$status = $api->status();
$shardStatus = $status->shardStatus('euw');
$service = $shardStatus->getService('Game');
if(sizeof($service->incidents) > 0)
    echo "There are incidents";

免责声明

用户有责任评估内容，我不会对因使用此开源软件而造成的任何损害或损失承担责任。我们不保证软件会按预期工作，确保与软件的正确交互是用户的责任。

本产品未经 Riot Games, Inc. 或其任何关联公司的任何方式认可、认证或批准。