Blizzard Starcraft 2 API

A PHP 5.3+ wrapper for the Starcraft 2 API

by Petre Pătrașc

Download .zip Documentation View on GitHub

Travis CI Status Scrutinizer Score Coverage Status Packagist Stable Version License Dependency Status

What is this project about?

This project is an open-source PHP API wrapper for Blizzard Entertainment's Starcraft 2. It provides a clear and easy way to interface with the methods exposed for data minining purposes, and allows for developers to interact with native PHP objects and an extensible architecture in order to expose new functionality and data grouping, while having less to worry about data mapping.

What are the key features?

  • Support for PHP 5.3 and later.
  • Integration via Composer or stand-alone.
  • Extensible architecture, customisable for future needs.
  • Integrates with the Symfony 2 framework as a Bundle.
  • Very high standard of testing.
  • Very high code quality.
  • MIT License.
  • Built and supported with ♥ for an amazing community and an amazing game.

What are the methods exposed?

All of the currently exposed API functionality is wrapped. Retrieving is supported across all Battle.NET regions for the following requests:

  • Player profile
  • Latest matches played by player
  • Information regarding a player's ladder
  • Information on grandmaster league (for current or previous season)
  • Information regarding the rewards available in the game
  • Information regarding the achievements available in the game

How to install?

Super easy, using Composer. Simply add the following line to your composer.json, in the "requires" section:

"petrepatrasc/blizzard-starcraft-api": ">=1.0.0",

And then simply update your Composer dependencies in order to use the package.

$ composer update

If you would like to use the stand-alone package (without Composer), download the ZIP archive from the GitHub repository and make sure to add it to your autoloader.

How to use?

Once you've installed the package, you can already interact with the system. The main API methods are exposed via the ApiService class (petrepatrasc\BlizzardApiBundle\Service\ApiService.php) all you need to do is to instantiate it, as shown below.

use petrepatrasc\BlizzardApiBundle\Entity\Region;

class TestClass
{
    public function index()
    {
        $apiService = new \petrepatrasc\BlizzardApiBundle\Service\ApiService();
        $leagueInformation = $apiService->getGrandmasterLeagueInformation(Region::Europe);
    }
}

Symfony 2 integration?

The package completely integrates into Symfony 2's Bundle system. In order to enable the functionality, simply add the following entry to your AppKernel.app file.

new petrepatrasc\BlizzardApiBundle\BlizzardApiBundle(),

You then gain access to the services layer designed for Symfony 2, via the following command:

$this->get('blizzard_api')->getGrandmasterLeagueInformation(Region::Europe);

Quick overview

The best place to start would be to have a look at the ApiService documentation. Essentially, the methods that are exposed are:

public function getPlayerProfile($region, $battleNetId, $playerName, $realm = 1)
public function getPlayerLatestMatches($region, $battleNetId, $playerName, $realm = 1)
public function getPlayerLaddersInformation($region, $battleNetId, $playerName, $realm = 1)
public function getGrandmasterLeagueInformation($region, $previousSeason = false)
public function getLeagueInformation($region, $id)
public function getRewardsInformation($region)
public function getAchievementsInformation($region)
public function makeCall($region, $apiMethod, $params = array(), $trailingSlash = true)

How is the quality of the package ensured?

At the moment, continuous integration is handled via Travis CI, code quality is measured via Scrutinizer, code coverage is measured via Coveralls. The package will receive regular releases by following the semantic versioning convention, and will receive regular updates on Packagist.

At the moment, the code quality is extremely high (over 90%), and there's been a special focus on very clear and very clean testing - mock data is used for data checking (mostly in unit testing), while integration testing is used for data integrity, sanity checks, as well exception handling.

Future support

I'm planning on using this API wrapper in a larger project that I'll be working on, and will thus carry on supporting the package. Travis is set up with a cron that will immediately notify me if the daily integration tests fail. At the moment, I'm looking at setting up a mini road-map, but I'm sure I'll revisit this package once the other one evolves.

I also want to make sure that everything is properly explained in comments. All of the public things are, but for future purposes, there may be value in ensuring that the overall design is also explained somewhere.

For any questions and support, please open an issue on the GitHub repository, email me at: petre@dreamlabs.ro or tweet to @petrepatrasc. Thanks for reading, and hope you enjoy!

©2014 StarCraft and Blizzard Entertainment are trademarks or registered trademarks of Blizzard Entertainment, Inc. in the U.S. and/or other countries.

Blizzard Starcraft 2 API is maintained by @petrepatrasc.
Tactile theme by Jason Long.