Xtream PHP Client

English | Português do Brasil

A PHP 7.0+ client for Xtream-compatible IPTV Player APIs.

This project is under active development. The public API may change before the first stable 1.0.0 release.

Features

• Account profile and server information.
• Live TV, VOD, series, episodes, and EPG endpoints.
• Category filters and local pagination.
• Live, movie, episode, timeshift, and XMLTV URL generation.
• URL-safe credentials and exceptions that do not expose responses or secrets.
• Injectable HTTP transport for deterministic tests.
• Raw, Camel Case, Standardized, JSON:API, and custom callback responses.
• Remain compatible with PHP 7.0 through current PHP versions.
• Keep the runtime lightweight and framework-independent.

Methods return raw associative arrays by default. Optional serializers can normalize every response without changing endpoint calls.

Requirements

• PHP 7.0 or newer
• cURL extension
• JSON extension
• Composer

Installation

Install the package from Packagist:

composer require giovanipatrick/xtream-php-client

Usage

<?php

require __DIR__ . '/vendor/autoload.php';

use Xtream\Client;
use Xtream\Serializer\StandardizedSerializer;

$client = new Client([
    'url' => 'https://example.com',
    'username' => 'username',
    'password' => 'password',
    'preferred_format' => 'm3u8',
    'serializer' => new StandardizedSerializer(),
]);

$profile = $client->getProfile();
$server = $client->getServerInfo();

$channels = $client->getChannels([
    'category_id' => 10,
    'page' => 1,
    'limit' => 50,
]);

$movies = $client->getMovies(['category_id' => 20]);
$movie = $client->getMovie(['movie_id' => 123]);
$shows = $client->getShows(['category_id' => 30]);
$show = $client->getShow(['show_id' => 456]);

$shortEpg = $client->getShortEpg(['channel_id' => 789, 'limit' => 5]);
$fullEpg = $client->getFullEpg(['channel_id' => 789]);

Available serializers are CamelCaseSerializer, StandardizedSerializer, and JsonApiSerializer. Use CallbackSerializer to override only selected resource responses. Omit the serializer option to keep raw provider arrays.

Both snake_case option names and their camelCase counterparts from the TypeScript inspiration are accepted. See the API reference for transport options, URL generation, and error behavior.

Development

Install development dependencies and run all checks:

composer install
composer check

To run the opt-in live-provider suite, export the variables from a local ignored .env file and run:

composer test:integration

Unit tests must not depend on a real IPTV provider. Integration test source may be committed, but credentials, private fixtures, provider responses, generated stream URLs, and test output are local-only and ignored by Git. Public CI does not run live-provider tests.

Workflow and releases

• main contains reviewed and tested code only.
• Work starts in a dedicated feature, fix, documentation, or maintenance branch.
• Pull requests must pass the complete PHP compatibility matrix.
• Commits use Conventional Commits, are written in English, and may include an optional matching emoji as described in CONTRIBUTING.md.
• Releases follow Semantic Versioning and are created from signed vX.Y.Z tags.

See the documentation site and contribution guide for details.

Acknowledgements

This project is inspired by @iptv/xtream-api. It is an independent PHP implementation and is not affiliated with Xtream Codes or IPTV providers.

License

Released under the MIT License.