kashmiry / sportmonks-football-php

v1.0.1 2026-11-06 12:37 UTC

Requires

• php: ^8.3
• symfony/http-client: ^6.4.50 || ^7.4.23 || ^8.1.11

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0
• rector/rector: ^2.8

MIT

• Carsten Tetzlaff
• Kashmiry

• php
• API-Client
• soccer
• football
• sportmonks

Published on Packagist.org on 2026-11-06 12:47 UTC

README

Actively maintained PHP client for the Sportmonks Football API.

📋 Requirements

• PHP >= 8.3
• A Sportmonks API token (your plan determines which endpoints you can call)
• Sportmonks API v3

📦 Installation

composer require kashmiry/sportmonks-football-php

⚙️ Configuration

Variable	Required	Description
SPORTMONKS_API_TOKEN	Yes	Your Sportmonks API token
SPORTMONKS_TIMEZONE	No	Timezone for returned dates (default: UTC)

From $_ENV (default): set the variables once, and every call uses them.

$_ENV['SPORTMONKS_API_TOKEN'] = getenv('SPORTMONKS_API_TOKEN') ?: '';
$_ENV['SPORTMONKS_TIMEZONE'] = 'Asia/Riyadh';

Tip

Using a .env file? symfony/dotenv loads it into $_ENV for you.

Per endpoint: pass settings to the constructor. Each one is optional and falls back to $_ENV. Use httpClient to bring your own Symfony HTTP client for timeouts, retries, or tests.

use Kash\Sportmonks\Football\Endpoint\Fixtures;

$fixtures = new Fixtures(token: $token, timezone: 'Asia/Riyadh', httpClient: $httpClient);

🚀 Usage

Pick an endpoint from FootballApi, chain any options, then make the request:

use Kash\Sportmonks\Football\FootballApi;

$response = FootballApi::fixtures()
    ->setIncludes(['scores', 'lineups', 'events'])
    ->getByDate('2026-11-05');

foreach ($response->data as $fixture) {
    echo $fixture->name, PHP_EOL; // e.g. "Real Madrid vs FC Barcelona"
}

Every call returns the decoded JSON response:

• $response->data: the results
• $response->pagination: paging info, when available

📖 See the API reference for pagination, includes, filters, and all endpoints.

🤖 AI Assistants

The package ships an agent skill that teaches coding agents how to use this client:

npx skills add kashmiry/sportmonks-football-php

# or directly copy it from the installed package
mkdir -p .agents/skills && cp -r vendor/kashmiry/sportmonks-football-php/skills/* .agents/skills/

Sportmonks also offers AI docs and an MCP server for exploring the API.

🤝 Contributing

Contributions are welcome.

• Bug reports: include steps to reproduce, expected and actual behavior, and your PHP version.
• Pull requests: target main, keep changes focused, and explain why they are needed. Include a regression test for bug fixes.

🙏 Credits

Derived from the work of Carsten Tetzlaff and Joe Saunderson.

📄 License

Licensed under the MIT License.