Skip to content

Commit d0a365d

Browse files
garakgarak
committed
🎉 first commit
1 parent 578633f commit d0a365d

14 files changed

Lines changed: 5239 additions & 0 deletions

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/.git* export-ignore
2+
/Dockerfile export-ignore
3+
/.php-cs-fixer.php export-ignore
4+
/phpstan.neon export-ignore
5+
/tests export-ignore

‎.github/workflows/build.yaml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Build
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request: ~
8+
9+
jobs:
10+
phpstan:
11+
runs-on: ubuntu-24.04
12+
name: PHPStan
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v6
16+
- name: PHPStan
17+
uses: docker://oskarstark/phpstan-ga:1.8.0
18+
env:
19+
REQUIRE_DEV: true
20+
with:
21+
args: analyse
22+
cs-fixer:
23+
runs-on: ubuntu-24.04
24+
name: PHP-CS-Fixer
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v6
28+
- name: Fix CS
29+
uses: docker://oskarstark/php-cs-fixer-ga
30+
with:
31+
args: --diff --dry-run
32+
tests:
33+
runs-on: ubuntu-24.04
34+
strategy:
35+
matrix:
36+
include:
37+
- description: 'Lowest'
38+
php: '8.2'
39+
dependencies: lowest
40+
- description: '8.3'
41+
php: '8.3'
42+
- description: '8.4'
43+
php: '8.4'
44+
- description: '8.5'
45+
php: '8.5'
46+
name: PHP ${{ matrix.php }} tests (${{ matrix.description }})
47+
steps:
48+
- name: Checkout
49+
uses: actions/checkout@v6
50+
- name: Setup PHP
51+
uses: shivammathur/setup-php@v2
52+
with:
53+
php-version: ${{ matrix.php }}
54+
- name: Install dependencies
55+
uses: ramsey/composer-install@v3
56+
with:
57+
dependency-versions: ${{ matrix.dependencies }}
58+
- name: Run tests
59+
run: vendor/bin/phpunit --colors=always
60+

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/.*.cache
2+
/phpunit.xml
3+
/vendor

‎.php-cs-fixer.php‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?php
2+
3+
return (new PhpCsFixer\Config())
4+
->setRules([
5+
'@PSR12' => true,
6+
'@PHP8x2Migration' => true,
7+
'binary_operator_spaces' => ['operators' => ['=>' => 'single_space', '=' => 'single_space']],
8+
'blank_line_before_statement' => ['statements' => ['return']],
9+
'cast_spaces' => true,
10+
'concat_space' => ['spacing' => 'none'],
11+
'declare_strict_types' => true,
12+
'fully_qualified_strict_types' => true,
13+
'phpdoc_separation' => true,
14+
'native_function_invocation' => ['include' => ['@all']],
15+
'no_extra_blank_lines' => true,
16+
'no_spaces_around_offset' => ['positions' => ['inside', 'outside']],
17+
'no_unneeded_control_parentheses' => true,
18+
'no_unused_imports' => true,
19+
'no_whitespace_in_blank_line' => true,
20+
'phpdoc_align' => true,
21+
'phpdoc_no_access' => true,
22+
'php_unit_fqcn_annotation' => true,
23+
'self_accessor' => true,
24+
'single_quote' => true,
25+
'return_type_declaration' => true,
26+
'trailing_comma_in_multiline' => ['elements' => ['arguments', 'arrays', 'match', 'parameters']],
27+
'trim_array_spaces' => true,
28+
'void_return' => true,
29+
])
30+
->setFinder(
31+
PhpCsFixer\Finder::create()
32+
->in(__DIR__ . '/src')
33+
->in(__DIR__ . '/tests')
34+
)
35+
->setRiskyAllowed(true)
36+
;

‎Dockerfile‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
FROM composer:2.9 AS composer
2+
FROM php:8.5-alpine
3+
4+
COPY --from=composer /usr/bin/composer /usr/local/bin/composer
5+
6+
WORKDIR /srv/chess-api
7+
8+
# prevent the reinstallation of vendors at every changes in the source code
9+
COPY . ./
10+
11+
RUN set -eux; \
12+
composer install; \
13+
composer clear-cache; \
14+
vendor/bin/phpunit
15+
16+
CMD ["/init"]

‎LICENSE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# MIT License
2+
3+
Copyright (c) 2026 Massimiliano Arione
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
22+

‎README.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Chess API Client
2+
3+
A PHP client for [chess-api.com](https://chess-api.com/) using PSR-18 HTTP Client.
4+
5+
## Requirements
6+
7+
- PHP 8.2+
8+
- PSR-18 HTTP Client implementation (e.g. Symfony HttpClient, Guzzle)
9+
- PSR-17 HTTP Factory implementation
10+
11+
## Installation
12+
13+
```bash
14+
composer require p-chess/api
15+
```
16+
17+
If you want to use Symfony HttpClient:
18+
19+
```bash
20+
composer require nyholm/psr7 symfony/http-client
21+
```
22+
23+
If you want to use Guzzle:
24+
25+
```bash
26+
composer require guzzlehttp/guzzle
27+
```
28+
29+
## Usage
30+
31+
```php
32+
use PChess\Api\ChessApiClient;
33+
34+
// Create the client with your PSR-18/PSR-17 implementations
35+
$client = new ChessApiClient(
36+
$httpClient, // PSR-18 ClientInterface
37+
$requestFactory, // PSR-17 RequestFactoryInterface
38+
$streamFactory, // PSR-17 StreamFactoryInterface
39+
);
40+
41+
// Get the best move for a position
42+
$fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
43+
$move = $client->getBestMove($fen);
44+
// Returns: 'e4' (or similar)
45+
46+
// Restrict the engine to specific moves
47+
$move = $client->getBestMove($fen, ['e2e4', 'd2d4', 'g1f3']);
48+
// Returns one of the allowed moves
49+
```
50+
51+
### Parameters
52+
53+
| Parameter | Type | Description |
54+
|-----------------|----------|--------------------------------------------------------------------------|
55+
| `$fen` | `string` | The chess position in FEN notation (includes side to move) |
56+
| `$allowedMoves` | `array` | Optional array of allowed moves in UCI format (e.g., `['e2e4', 'd2d4']`) |
57+
58+
### Return Value
59+
60+
The method returns a `string` containing the best move in UCI format (e.g., `'e2e4'`).
61+
62+
### Exceptions
63+
64+
The client throws `ChessApiException` in the following cases:
65+
66+
- HTTP error (non-2xx status code)
67+
- Invalid API response (missing `move` field)
68+
- API error (e.g., invalid FEN)
69+
70+
```php
71+
use PChess\Api\ChessApiException;
72+
73+
try {
74+
$move = $client->getBestMove($fen);
75+
} catch (ChessApiException $e) {
76+
// Handle the error
77+
echo $e->getMessage();
78+
}
79+
```
80+
81+
## Example with Symfony HttpClient
82+
83+
```php
84+
use Nyholm\Psr7\Factory\Psr17Factory;
85+
use PChess\Api\ChessApiClient;
86+
use Symfony\Component\HttpClient\Psr18Client;
87+
88+
$factory = new Psr17Factory();
89+
$httpClient = new Psr18Client();
90+
91+
$chessClient = new ChessApiClient($httpClient, $factory, $factory);
92+
93+
$fen = 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1';
94+
$move = $chessClient->getBestMove($fen);
95+
96+
echo "Best move: $move\n";
97+
```
98+
99+
## Example with Guzzle
100+
101+
```php
102+
use GuzzleHttp\Client;
103+
use GuzzleHttp\Psr7\HttpFactory;
104+
use PChess\Api\ChessApiClient;
105+
106+
$httpClient = new Client();
107+
$factory = new HttpFactory();
108+
109+
$chessClient = new ChessApiClient($httpClient, $factory, $factory);
110+
111+
$fen = 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1';
112+
$move = $chessClient->getBestMove($fen);
113+
114+
echo "Best move: $move\n";
115+
```
116+
117+
## Development
118+
119+
Before exdecuting one of the following, you must execute at least once
120+
121+
```bash
122+
docker build -t chess-api .
123+
```
124+
125+
### Running Tests
126+
127+
```bash
128+
docker run --rm -v "$(pwd)":/srv/chess-api chess-api vendor/bin/phpunit --color=always
129+
```
130+
131+
### Coding Standard
132+
133+
```bash
134+
docker run --rm -v "$(pwd)":/srv/chess-api chess-api vendor/bin/php-cs-fixer --ansi
135+
```
136+
137+
### Static Analysis
138+
139+
```bash
140+
docker run --rm -v "$(pwd)":/srv/chess-api chess-api vendor/bin/phpstan --ansi
141+
```

‎composer.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"name": "p-chess/api",
3+
"description": "PHP client for chess-api.com using PSR-18 HTTP Client",
4+
"license": "MIT",
5+
"type": "library",
6+
"authors": [
7+
{
8+
"name": "Massimiliano Arione",
9+
"email": "garakkio@gmail.com"
10+
}
11+
],
12+
"require": {
13+
"php": "^8.2",
14+
"psr/http-client": "^1.0",
15+
"psr/http-factory": "^1.1"
16+
},
17+
"require-dev": {
18+
"friendsofphp/php-cs-fixer": "^3.93",
19+
"phpstan/phpstan-strict-rules": "^2.0",
20+
"phpunit/phpunit": "^11.5 || ^12.5 || ^13.0"
21+
},
22+
"autoload": {
23+
"psr-4": {
24+
"PChess\\Api\\": "src/"
25+
}
26+
},
27+
"autoload-dev": {
28+
"psr-4": {
29+
"PChess\\Api\\Tests\\": "tests/"
30+
}
31+
}
32+
}

0 commit comments

Comments
 (0)