README

A comprehensive media server platform built with PHP 8.3+, featuring real-time WebSocket communication, HTTP REST APIs, and support for multiple client platforms including Roku, Samsung Tizen, and Windows.

Repository moved 2026-05-17: this codebase migrated from github.com/detain/phlix to github.com/detain/phlix-server as part of the Phase B repo split (see PHLIX_EXPANSION_PLAN.md). Update existing local clones with git remote set-url origin git@github.com:detain/phlix-server.git. The old repo is being archived in step B.4b.

Overview

Phlix Media Server provides a complete media management and streaming solution:

Media Library Management: Organize and browse media collections with automatic scanning
User Authentication: JWT-based auth with refresh tokens
Real-time SyncPlay: Watch content together with friends
Live TV Support: DVR and guide integration
DLNA Streaming: Standard protocol support for compatible devices
Transcoding: On-the-fly media conversion via FFmpeg with automatic quality selection
HLS Streaming: Adaptive bitrate streaming for web clients with multi-quality playlists
WebSocket Events: Real-time progress and notification delivery
Multi-Source Metadata: Automatic metadata fetching from TMDB (movies), TVDB (TV series), Fanart.tv (artwork), and local NFO files with 24-hour cache and provider fallback
Content Filtering: Parental controls with rating and genre-based filtering

Architecture

src/
├── Server/
│   ├── Core/           # Application bootstrap and core
│   ├── Http/            # HTTP REST API layer
│   │   ├── Controllers/ # Request handlers
│   │   ├── Request.php  # HTTP request representation
│   │   ├── Response.php # HTTP response builder
│   │   └── Router.php  # Route dispatching
│   ├── WebSocket/       # Real-time communication
│   │   ├── Connection.php      # Client connection wrapper
│   │   ├── ConnectionPool.php  # Connection management
│   │   ├── MessageHandler.php  # Event routing
│   │   ├── WebSocketServer.php # Server implementation
│   │   └── Events.php          # Event type constants
│   └── WebPortal/       # Web portal (HTML UI)
│       ├── WebPortalRouter.php # REST API for portal
│       └── PageRenderer.php    # Smarty template rendering
├── Session/            # Playback session management
├── Media/              # Media library and metadata
│   ├── Library/        # Library management (LibraryManager, ItemRepository, MediaScanner)
│   ├── Metadata/      # Metadata fetching (TMDB, TVDB, Fanart, NFO providers)
│   ├── Transcoding/    # FFmpeg transcoding with EncodingHelper
│   └── Streaming/      # HLS streaming with adaptive bitrate
├── Auth/               # Authentication services
└── Common/             # Shared utilities

public/
├── index.php           # Web portal entry point
├── templates/          # Smarty templates
└── assets/             # Static assets (css, js)

Requirements

PHP: 8.3 or higher
MySQL: 8.0+ or MariaDB 10.6+
Workerman: 5.0+ (bundled via Composer)
FFmpeg: For transcoding (optional)

Features

Foundation

PSR-11 DI container (PHP-DI 7): auto-wired services with provider-based composition; see docs/dev/architecture-server.md
PSR-14 event dispatcher (Tukio): playback, library-scan, and auth lifecycle events with typed readonly DTOs. Plugins subscribe by event class FQCN; see docs/dev/event-reference.md.
Plugin system: install / enable / disable / uninstall lifecycle, sandboxed per-plugin vendor/ directories, signature-checked manifests, and PSR-14 event subscription via Phlix\Shared\Plugin\LifecycleInterface (the Phlix\Plugins\Contract\LifecycleInterface FQCN remains a deprecated bridge through 0.11.x). Plugin developer guide: docs/plugins/developer-guide.md. Server-internals reference for contributors extending the loader: docs/dev/plugin-sdk.md. Reference plugin: detain/phlix-plugin-example.
Shared interfaces / DTOs in detain/phlix-shared: framework-neutral Composer package shared with phlix-hub. Phlix\Shared\Plugin\*, Phlix\Shared\Events\*, Phlix\Shared\Auth\JwtClaims, and Phlix\Shared\Hub\* DTOs live there since phlix-server 0.11.0.

Web Portal

Smarty-based Templates: Server-side rendered HTML pages using Smarty
REST API Endpoints: Complete API for library browsing, media info, and user data
JWT Authentication: Integrated token-based auth with refresh support
Responsive Design: CSS-first approach with utility classes
JavaScript Client: ApiClient helper with auth, library, and player helpers
Continue Watching: Track and display in-progress media
Library Browser: Browse media by library with item counts

Authentication & Security

JWT-based Authentication: Stateless auth with access tokens (1 hour TTL) and refresh tokens (7 days TTL)
Secure Password Hashing: Argon2ID for password storage
Multi-Device Sessions: Track and manage sessions across devices
User Profiles: Multiple profiles per account with parental controls
- Up to 5 profiles per user account
- Profile-specific content rating restrictions (G, PG, PG-13, R, NC-17, X, UNRATED)
- PIN protection (4 or 6 digits) for profile settings
- Genre-based filtering (allowed/blocked genre lists)
- Daily watch time limits per profile
Content Rating Filters: Age-based access restrictions
Audit Logging: Complete security event logging

SyncPlay - Group Watching

Synchronized Playback: Watch content together with friends across devices with sub-second sync accuracy
Host-Controlled Playback: Only the host can control play/pause/seek; all members receive synchronized commands
NTP-Style Time Sync: Network time synchronization with latency compensation and drift correction
In-Group Chat: Real-time messaging with typing indicators and message history
Playback Queue: Host-managed queue with media info (title, thumbnail)
Host Election: Automatic host election when current host leaves (oldest member becomes host)
Password Protection: Optional password protection for private watch parties
Position Tolerance: Configurable sync tolerance (default 2s) to prevent excessive seeking

Session Management

Device Sessions: Track authenticated devices with activity timestamps
Playback Progress: Resume where you left off across sessions
Continue Watching: Track items in progress per profile
Watch History: Complete viewing history per profile with:
- Automatic completion detection at 90% progress threshold
- Watch time statistics (total, daily, by period)
- Resume position tracking for seamless playback continuation

Live TV & DVR

Multi-Tuner Support: DVB-T, DVB-S, DVB-C, and ATSC tuner types
Channel Scanning: Automatic discovery of broadcast services
Electronic Program Guide: Full EPG with program info, categories, and search
DVR Scheduling: Schedule recordings with priority management
Time-Shifting: Pause and rewind live TV with buffer
Channel Lineups: Custom channel lineups per user
Favorites: Personal favorite channels per user
Storage Management: Recording storage tracking and limits

Installation

# Clone the repository
git clone https://github.com/detain/phlix-server.git
cd phlix-server

# Install dependencies
composer install

# Configure environment
cp .env.example .env
# Edit .env with your database and service credentials

# Run database migrations
php scripts/migrate.php

# Start the development server
php start.php server

Configuration

Configuration is managed via PHP files in config/:

// config/server.php
return [
    'server' => [
        'name' => 'Phlix Media Server',
        'host' => '0.0.0.0',
        'port' => 8080,
    ],
    'websocket' => [
        'host' => '0.0.0.0',
        'port' => 8097,
    ],
    'database' => [
        'host' => '127.0.0.1',
        'port' => 3306,
        'database' => 'phlix',
        'username' => 'phlix',
        'password' => 'secure-password',
    ],
    'debug' => false,
];

API Reference

HTTP Endpoints

Method	Path	Description
GET	`/health`	Health check
GET	`/system/info`	Server information
POST	`/api/v1/auth/register`	User registration
POST	`/api/v1/auth/login`	User login
POST	`/api/v1/auth/refresh`	Token refresh
GET	`/api/v1/auth/me`	Current user profile
GET	`/api/v1/sessions`	List user sessions
DELETE	`/api/v1/sessions/{id}`	End a session
POST	`/api/v1/sessions/{id}/progress`	Report playback progress
GET	`/api/v1/sessions/{id}/progress`	Get playback state

WebSocket Events

Connection Events:

connected - Sent on successful connection
client_disconnected - Broadcast when client disconnects

Authentication Events:

auth_request - Request authentication
auth_success - Authentication successful
auth_failure - Authentication failed

Playback Events:

playback_start - Playback started
playback_pause - Playback paused
playback_stop - Playback stopped
playback_progress - Progress update
playback_seek - Seek performed

SyncPlay Events:

syncplay_create_group - Create watch group
syncplay_join_group - Join watch group
syncplay_leave_group - Leave watch group
syncplay_sync_state - State synchronization

Development

Running Tests

# Run all tests
./vendor/bin/phpunit

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage-report

# Run specific test suite
./vendor/bin/phpunit --testsuite Unit
./vendor/bin/phpunit --testsuite Integration

Code Standards

This project follows PSR-12 coding standards and uses static analysis tools:

# Check code style
./vendor/bin/phpcs --standard=PSR12 src/

# Run static analysis
./vendor/bin/phpstan analyze src/ --level=9
./vendor/bin/psalm

Git Workflow

Create a feature branch: git checkout -b feature/my-feature
Make changes and commit: git commit -am 'Add new feature'
Push to remote: git push origin feature/my-feature
Create Pull Request on GitHub
After review, merge via squash-merge

Contributing

Fork the repository
Create your feature branch
Ensure all tests pass (./vendor/bin/phpunit)
Follow PSR-12 coding standards
Submit a pull request

License

Support

For issues and feature requests, please use the GitHub issue tracker.

For detailed development documentation, see DEVELOPER.md.

detain / phlix-server

Maintainers

Package info

Statistics

Security