README

Chess.com PHP API SDK

A simple PHP SDK to work with the public chess.com API.

Warning: This package is still in active development and in very early stages.

Table of Contents

• Introduction
• Usage
• Development
• Contributing

Introduction

This PHP Composer package provides a simple SDK to interact with Chess.com's "Published Data" API. Their API provides all public data that Chess.com makes available without authenticating with their service. As this package is a work in progress, not all endpoints are implemented yet but eventually this will encompass...

• Player Data
• Clubs
• Tournaments
• Team Matches
• Countries
• Daily Puzzles
• Streamers
• Leaderboards

This package can be used out-of-box with zero configuration. However, you may provide a configured HTTP client if you wish, given it follows PSR-18.

Usage

This package is not yet complete, but I am actively working on it. I'm slowly working my way through the various endpoints. To get started, install the package with Composer.

composer require joebocock/chess-api-php

General usage is simple and you can be up and running in no time.

use JoeBocock\ChessApi\Chess;

$client = new Chess();

/** @var JoeBocock\ChessApi\Entities\PlayerProfile */
$playerProfile = $client->playerProfile('gothamchess');

echo $playerProfile->name;
// 'Levy Rozman'

Under the hood, Guzzle will be used to make the request - but if you have your own PSR-18 compliant HTTP client, you may provide it while constructing the Chess class. This is great for when you need to configure the Client beforehand.

use GuzzleHttp\Client;
use JoeBocock\ChessApi\Chess;

$client = new Chess(
    new Client([
        // configuration...
    ])
);

For all endpoints, the client provides descriptive methods to easily handle the request construction and subsequent hydration of the response. These methods also provide some basic input validation to help you catch issues before making the request.

Sometimes however, you may wish to handle the request construction yourself. The Chess client allows you to do just that.

use JoeBocock\ChessApi\Chess;
use JoeBocock\ChessApi\Requests\PlayerProfileRequest;

$client = new Chess();

$request = new PlayerProfileRequest();

$request->setUsername('lud-skywalker');

$response = $client->send($request);

While we'd hope nothing goes wrong during usage, sometimes Chess.com might return a 4XX or even 5XX. In this case, our Chess class throws three different exceptions to help discern the problem.

Invalid arguments will produce an InvalidArgumentException as expected. A ChessRequestException will occur whenever there was an issue produced by the HTTP Client. Finally, a ChessResponseException will happen whenever a response was returned that cannot be properly hydrated into an entity.

use JoeBocock\ChessApi\Chess;
use JoeBocock\ChessApi\Exceptions\ChessRequestException;
use JoeBocock\ChessApi\Exceptions\ChessResponseException;

$client = new Chess();

try {
    $playerProfile = $client->playerProfile('gothamchess');
} catch (ChessRequestException|ChessResponseException|\InvalidArgumentException $e) {
    // handle...
}

Development

As this is just a package, it has no requirement for a web server locally. Development is powered by a very simple Docker container that is used to run all commands.

To get started, first clone the repository. A Makefile is provided for convenience of command handling...

# Build the container
make build

# Install Composer Dependencies
make install

# Run the test suite
make test

# Run static analysis
make stan

# Format the codebase
make format

# Lint the codebase
make lint

Contributing

As the package is still in development and hasn't reached v1 yet, I haven't written any contribution guidelines. But don't let that stop you! Please feel free to fork the codebase, get a feel for the style and submit a PR.