Download the PHP package detain/phlix-server without Composer

Phlix Media Server

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 [email protected]: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. Transcoded output is normalized for browser playback: 8-bit H.264 video, stereo AAC audio (surround layouts like AC-3 5.1(side) are downmixed — a channel_configuration=0 PCE otherwise breaks hls.js), and even scale widths (force_divisible_by=2)
• 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

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 phlix-docs / dev / architecture-server.
• PSR-14 event dispatcher (Tukio): playback, library-scan, and auth lifecycle events with typed readonly DTOs. Plugins subscribe by event class FQCN; see phlix-docs / dev / event-reference.
• 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: phlix-docs / plugins / developer-guide. Server-internals reference for contributors extending the loader: phlix-docs / dev / plugin-sdk. 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, Phlix\Shared\Metadata\MetadataSourceInterface (the typed metadata-source plugin contract, since phlix-shared 0.15.0), and Phlix\Shared\Hub\* DTOs live there since phlix-server 0.11.0.
• Library matching & de-duplication: filename→title cleaning strips multi-word noise suffixes (Directors Cut, YIFY, …) before metadata matching (admin-tunable via matching.noise_suffixes); a canonical-key resolver prevents duplicate top-level series/movies at scan time; and the admin Duplicates page + scripts/dedup-series.php merge historical duplicates. Metadata source order is configurable per media type via the metadata.provider_priority setting. See phlix-docs / admin / library-management and phlix-docs / admin / server-settings.

Web Portal

• Vue SPA (/app) — the ONLY web UI: The web UI is the shared @phlix/ui Vue SPA, served at /app (SPA shell via SharedUiController + ViteAssets; built bundle under public/assets/app/). Routes + nav are registered in web-ui/src/main.ts, covering Browse/Library, Player, Music sub-pages (/app/music/*), Books (/app/books/*), Audiobooks (/app/audiobooks/*), Photos (/app/photo/*), Search (/app/search), Settings (incl. the Security/passkey tab at /app/settings/security), and Admin (/app/admin/*).
• Legacy Smarty page rendering removed: The old server-rendered (Smarty) portal pages — PageRenderer, the page controllers, and all public/templates/**/*.tpl page templates — have been deleted. Their old paths now 302-redirect to the /app equivalent (e.g. /login → /app/login, /library → /app, /player/{id} → /app/player/{id}, /music|/books|/audiobooks|/photo → their /app pages), dispatched in src/Server/Workerman/HttpHandler.php (the served daemon; the pre-S171 public/index.php copy of that logic was unserved and deleted). Smarty (smarty/smarty) is retained on the server only for the newsletter email (src/Admin/NewsletterGenerator.php + public/templates/emails/newsletter.tpl).
• 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)
• External SSO — OIDC, LDAP & GitHub: Optional OpenID Connect, LDAP and GitHub OAuth2 login backends, toggled per-provider from the admin Integrations → Auth providers page (persisted as the auth.oidc.enabled / auth.ldap.enabled / auth.github.enabled server settings). OIDC uses the authorization-code flow with PKCE + state + nonce and id-token validation (GET /auth/oidc/authorize → GET /auth/oidc/callback). GitHub is plain OAuth2 + PKCE with no OIDC discovery and no id_token (GET /auth/github/authorize → GET /auth/github/callback), identifying the user from GET https://api.github.com/user (default scopes read:user user:email) and keying the identity on GitHub's stable numeric id (github.<id>), never the renameable login or the e-mail. LDAP rides POST /auth/login with an ldap:-prefixed username (e.g. ldap:jdoe). Sessions are delivered as httpOnly + Secure + SameSite=Lax cookies; the OIDC/GitHub post-login redirect is allowlisted to same-origin paths only, and the OAuth state is additionally bound to the browser that started the flow by a short-lived HttpOnly correlation cookie (phlix_oauth_oidc / phlix_oauth_github). Account linking lets an already-signed-in user attach an external identity to their account — GET /auth/identities lists linked identities, GET /auth/identities/link/oidc and GET /auth/identities/link/github start a verified OAuth round-trip link, POST /auth/identities/link/ldap links via a live LDAP bind, and DELETE /auth/identities/{id} unlinks one (own-identity-only, and refused with 409 if it would remove your last sign-in method); linking always proves control of the identity, never mints a new session, and rejects an identity already linked to another account with 409. A linked identity is usable for login (it resolves your existing account instead of creating a duplicate), and the auth provider registry supports multiple instances of the same family (e.g. two OIDC issuers; configuring named instances from the admin console is a later step).
  • Provider configuration is DB-backed (migration 093_plugin_settings.sql, table plugin_settings) rather than a per-plugin settings.json; an existing file is imported once, automatically, on first read — no operator action on upgrade. The OIDC and GitHub settings saves preserve any optional key absent from the request body (only an explicitly empty value clears one), so a partial payload cannot wipe a field it does not know about. (The LDAP save still rebuilds its document from the body alone apart from bind_pw — send it the complete map.)
  • The provider redirect_uri is always absolute and is pinned to PHLIX_DOMAIN. Register https://<your PHLIX_DOMAIN>/auth/oidc/callback (or /auth/github/callback) at the IdP / OAuth App. If neither PHLIX_DOMAIN nor an absolute per-provider redirect_uri setting is configured, /auth/{provider}/authorize fails closed with 503 callback_url_not_configured. See Environment variables and the SSO/external-auth guide in phlix-docs for the full setup, including the GitHub provider (which has admin API endpoints but no admin-SPA card yet).
• 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
• Security Headers / CSP: Every response carries X-Content-Type-Options, X-Frame-Options, HSTS, and a strict Content-Security-Policy (SecurityHeaders). The SPA CSP allows media-src/worker-src 'self' blob: so hls.js can attach its MSE blob: object URL and transmux Web Worker (required for browser HLS playback), and the /app shell's inline bootstrap <script> runs under a per-request script nonce rather than 'unsafe-inline'; non-/app responses keep the strict default policy. img-src additionally allowlists the two TMDB image CDN hosts (https://image.tmdb.org and https://tmdb.org, no wildcard) so poster/backdrop/cast artwork served directly from TMDB renders rather than being blocked. This is a stopgap until the generic image caching/loader work (updates.md #47 / S71-S73) proxies all remote artwork through our own origin, at which point the explicit TMDB hosts are removed.

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

One-line install (Ubuntu/Debian)

On a fresh Ubuntu/Debian host, scripts/install.sh does the whole thing: system packages (PHP 8.3+, MySQL, ffmpeg), a dedicated phlix system user, MySQL database + user, application code, env file at /etc/phlix/env, generated PHLIX_SECRET_KEY, database migrations, a systemd phlix-server service, and an HAProxy reverse proxy with an auto-renewing Let's Encrypt certificate.

The installer also compiles the Swoole + php-uv extensions from source (the coroutine runtime Workerman uses), idempotently skipping the build when they already load, and runs a disable_functions preflight — see Swoole & php-uv on Linux.

Provision HTTPS in the same run by passing your domain and a Let's Encrypt contact email:

The script prompts for the install path, database user/password, and hostname when run in a terminal (with sensible defaults), and runs fully unattended when piped or given -y. Run sudo bash scripts/install.sh --help for every flag. Default ports: HTTP on :8096 behind HAProxy on :80/:443; DLNA discovery on 1900/udp.

Install flags

sudo bash scripts/install.sh --help lists every option. The most useful:

Updating an existing install

The same scripts/install.sh updates an in-place install without rotating any secrets. It reads the existing /etc/phlix/env (so DB_PASSWORD and PHLIX_SECRET_KEY are preserved), pulls the latest code, refreshes Composer dependencies, runs migrations, and restarts the service:

Or via the one-liner, which works regardless of where the server was installed because --update discovers the install path from the systemd unit. This is the exact string the admin console's update banner offers for copy-to-clipboard (config/updates.php's update_command, surfaced by GET /api/v1/admin/updates/status) — the server never runs it for you:

Pin to a specific tag or branch with --branch:

--update discovers the install path from the systemd unit's WorkingDirectory, fetches code as the install dir owner (so it doesn't trip Git's CVE-2022-24765 dubious-ownership check), runs composer install --no-dev --optimize-autoloader, clears templates_c/, runs scripts/run-migrations.php, restarts phlix-server, and curl-checks /health. It deliberately leaves the env file, MySQL grants, HAProxy config, and Let's Encrypt cert alone.

Uninstalling

scripts/install.sh --uninstall removes an existing install. It is interactive by default and prompts separately before each destructive step. The MySQL database, the /var/phlix data directory, and the Let's Encrypt certificate are kept unless you opt in:

Add --purge to also drop the database (and user), wipe /var/phlix (config, library cache, backups), and delete the Let's Encrypt certificate via certbot delete. Combine with -y for a fully unattended teardown:

What it removes when present:

1. The phlix-server systemd unit (stop, disable, remove file, daemon-reload).
2. HAProxy fragment at /etc/haproxy/phlix-managed/phlix-server.cfg.fragment, and /etc/haproxy/haproxy.cfg is rebuilt. If phlix-hub is still installed, its frontend + backend stay. If phlix-server was the last Phlix project, the pre-Phlix snapshot at /etc/haproxy/haproxy.cfg.pre-phlix.bak is restored (or haproxy.cfg is removed and haproxy is stopped + disabled if no snapshot exists).
3. The combined PEM at /etc/haproxy/certs/<domain>.pem.
4. /etc/cron.d/phlix-server-certbot and the certbot deploy hook.
5. The Let's Encrypt cert via certbot delete — only with --purge or interactive confirm.
6. The MySQL database + user — only with --purge or interactive confirm.
7. The install dir (/var/www/phlix by default; system paths refused).
8. /var/phlix (config, library cache, backups) — only with --purge or interactive confirm.
9. /var/log/phlix and /var/run/phlix.
10. /etc/phlix/env (env file).
11. The dedicated system user phlix via userdel — only with --purge or interactive confirm. Refuses to touch shared OS accounts (www-data, root, etc.). Cross-detects phlix-hub's systemd unit and refuses to remove a user that's still being used by it.

System packages (php-*, mysql-server, ffmpeg, haproxy, certbot) and ufw rules are left in place — sudo apt remove … / sudo ufw delete … to remove them.

Running alongside phlix-hub on the same server

Both installers can share a single HAProxy instance — they auto-merge into one /etc/haproxy/haproxy.cfg. Just run both installers normally; the second one detects the first's fragment and rebuilds a combined config that routes by Host: header.

After both finish, /etc/haproxy/haproxy.cfg looks like:

How the merge works. Each install drops a fragment at /etc/haproxy/phlix-managed/<project>.cfg.fragment with fe_http, fe_https, and backends sections. A rebuilder function then assembles the final haproxy.cfg from every fragment it finds. HAProxy's crt /etc/haproxy/certs/ directive auto-loads every .pem in that directory and picks the right one per SNI hostname.

The first install snapshots any pre-Phlix haproxy.cfg to /etc/haproxy/haproxy.cfg.pre-phlix.bak.

Uninstall behaviour: --uninstall removes only that project's fragment and rebuilds. If other Phlix projects remain, their frontend stays untouched. When the last Phlix project is uninstalled, the rebuilder restores the pre-Phlix snapshot (or removes haproxy.cfg outright if there was no pre-Phlix config) and stops/disables haproxy.

The hub server-tunnel port (:8802) is a separate listener — servers connect to that port directly. Open it on the firewall but don't put it behind the HAProxy 80/443 frontend.

If you'd rather use your own reverse proxy (nginx, Caddy, Traefik, etc.) instead of the managed HAProxy, pass --no-proxy to either install script. Each service then listens on its own port (8096 for phlix-server, 8800 for phlix-hub) and you point your proxy at those.

Everything else is already namespaced: env files (/etc/phlix-hub.env vs /etc/phlix/env), systemd units (phlix-hub.service vs phlix-server.service), install dirs (/opt/phlix-hub vs /var/www/phlix), service users (www-data vs phlix), MySQL DBs (phlix_hub vs phlix), backend ports (8800/8802/8803 vs 8096), and certbot artefacts.

Manual install (from source)

Configuration

Configuration is managed via PHP files in config/:

Environment variables

Most operators only set DB_PASSWORD and JWT_SECRET; the following knobs cover the streaming and auth-hardening features and all have safe defaults.

Rate limiting. The auth surfaces above (register / refresh / WebAuthn start+finish / public JWKS / WS-connect on :8097) are rate-limited. HTTP surfaces reply 429 Too Many Requests + Retry-After with body {"error":"Too Many Requests","code":"rate_limited"}; WS-connect rejects the handshake. login keeps its own DB-backed IP limiter (migration 074).

Loudness normalization. config/ffmpeg.php → loudness (disabled by default) applies an EBU R128 loudnorm filter to re-encoded audio when enabled. Copy-audio rungs (the original variant) and direct-play sessions are not normalized — you cannot filter a copied (non-decoded) stream.

Migration required on deploy. SV-4.15 adds migrations/085_rate_limit_buckets.sql (the shared DB-backed rate-limit bucket table). Run php bin/phlix migrate (or php scripts/run-migrations.php) after pulling — migrations are idempotent, so re-running is safe.

No one-time cleanup needed for media_items any more (S152). migrations/096_path_hash_unique_index.sql adds UNIQUE KEY idx_media_items_library_path_hash (library_id, path_hash) as part of the ordinary migration chain, so a fresh install gets the path-dedupe constraint from php bin/phlix migrate alone. Before it, migration 072 deferred the index to migrations/cleanup_072.php and migration 087 dropped it, so an install nobody hand-finalized had no duplicate-path protection — and every scanner path lookup lost the const plan. The migration is idempotent and refuses to touch a table that still holds duplicates, failing instead with a message that names the remedy: run php migrations/cleanup_072.php once to merge them, then re-run migrations. That script now owns de-duplication only.

No one-time cleanup needed for playback_state any more (S156). migrations/097_playback_state_unique_key.sql adds UNIQUE KEY uq_playback_state_session_media (session_id, media_item_id) as part of the ordinary migration chain, so a fresh install gets the progress-upsert constraint from php bin/phlix migrate (or php scripts/run-migrations.php) alone. Before it, migration 090 (S29, updates.md #29) reserved the number but carried no executable statement at all and deferred the key to the manual migrations/cleanup_090.php, which neither scripts/install.sh nor the Docker entrypoint nor either migrate command ever calls — so an install nobody hand-finalized had no (session_id, media_item_id) constraint, the ON DUPLICATE KEY UPDATE in PlaybackController::reportProgress() / StreamManager::persistStreamState() could never fire, and every ~15 s progress tick inserted a new row instead of updating one (finished episodes never left Continue Watching and playback_state grew without bound). The migration is idempotent and refuses to touch a table that still holds duplicate rows, failing instead with a message that names the remedy: run php migrations/cleanup_090.php once to merge them, then re-run migrations. That script now owns de-duplication only — it is needed only on an existing install that accumulated duplicate rows while the key was missing, never on a fresh one.

Migration AND rescan required on deploy (S331). Music albums with no artist tag are no longer discarded whole — they are ingested under a structural placeholder artist whose display label is [Unknown Artist]. migrations/102_music_artists_placeholder_flag.sql adds music_artists.is_placeholder and widens uk_name to (name, is_placeholder), so a REAL album genuinely tagged [Unknown Artist] stays a distinct artist (is_placeholder = 0) from the untagged bucket (is_placeholder = 1). Run php bin/phlix migrate (or php scripts/run-migrations.php) after pulling — migrations are idempotent, so re-running is safe. ⚠ A scan (or rescan) of each music library is ALSO required: albums the old policy discarded were never written to the database, and no backfill can reconstruct them without re-reading the audio files — the migration itself only adds the column and touches no rows. The scan summary key skipped_no_artist is renamed placeholder_artist_files (untagged albums are now indexed, not skipped).

API Reference

HTTP Endpoints

Rate limiting. POST /auth/register, POST /auth/refresh, the WebAuthn login start/finish endpoints, and the public JWKS endpoint reply 429 Too Many Requests + Retry-After (body {"error":"Too Many Requests","code":"rate_limited"}) when a caller exceeds the per-surface limit. Tune via RATE_LIMIT_* (see Environment variables).

JWKS key format. GET /.well-known/jwks.json serves this server's Ed25519 public key from config/hub-server-key.pem. The reader accepts both the app's native -----BEGIN ED25519 PRIVATE KEY----- format and a standard PKCS#8 Ed25519 key (-----BEGIN PRIVATE KEY-----, e.g. from openssl genpkey -algorithm Ed25519). If the key cannot be loaded, the endpoint degrades to a valid empty keyset ({"keys":[]}, HTTP 200) and logs an error rather than returning a 500.

Client capability negotiation. Send an X-Phlix-Client-Capabilities request header (a JSON codec-support map, e.g. {"eac3":false}) on playback-info requests. When present, the direct_play verdict is set from whether the client can decode the item's audio codec; absent/empty header keeps the previous always-true behavior.

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

Real-database integration tests self-skip. Tests under tests/Integration/ that need a live MySQL probe the configured host first and skip when it is unreachable, so ./vendor/bin/phpunit is green on a machine with no database — it just reports more skips. To actually exercise them, point the suite at a throwaway MySQL that has had php scripts/run-migrations.php applied:

CI does exactly this (.github/workflows/phpunit.yml provisions a mysql:8.0 service and runs the migrations before the suite), so these tests are not decorative. Note that the network-dependent group is excluded by phpunit.xml on purpose: Phlix\Plugins\OAuth2\OAuth2HttpClient (the live OAuth2 transport) is driven by a fake in every provider test and is effectively uncovered — closing that gap needs a live HTTP fixture.

Comparing skip sets between two runs — never compare the COUNT

phpunit.xml sets displayDetailsOnSkippedTests="true", so every run of this suite that loads that file and uses PHPUnit's default result printer — CI, local, --testsuite Unit, syncplay-e2e.yml — prints each skipped test BY NAME. Use the names, not the number:

Against a CI run (the script strips gh's job<TAB>step<TAB>timestamp prefix for you):

That is also how the mechanism is checked after a merge: master's own pre-S345 log exits 4 on this command (measured on run 32027697809), so an exit of 0 with a non-empty file is the before/after demonstration. The exit code is the whole contract — an empty set is never handed over silently:

Denominators always go to stderr, on every exit, so a set can be checked against the count PHPUnit itself printed. The script's header enumerates the same six codes with the exact input class that reaches each one.

The evaluation is per run, not per input: a multi-run log — the normal gh run view <id> --log shape — is segmented at PHPUnit's banners and terminating summary lines, and each run's arithmetic is judged on its own denominators. When any run fails, every failing run is named on stderr (ordinal, banner, that run's own numbers), no set is written, and the first failing run's exit code wins; the input-wide tallies still printed on stderr are audit-only and decide nothing. The old failure mode — one run's shortfall paid for by another run's surplus, netting to a code right for the sum and wrong for both runs — is closed, so a refusal now points at a specific run instead of the input as a whole.

⚠ --testdox is the one invocation this cannot cover, and it is a PHPUnit limitation, not a config mistake. PHPUnit constructs the default result printer for a testdox run with its $displayDetailsOnSkippedTests argument hardcoded false (the outputIsTestDox() branch of Facade::createResultPrinter() — the configuration value is not consulted there; vendor/phpunit/phpunit/src/TextUI/Output/Facade.php:204-221 in the pinned PHPUnit 10.5.64, which is the citation the script's own error message prints), so a --testdox run adds to Skipped: N and can never name those skips, with or without --display-skipped. No workflow passes --testdox any more (syncplay-e2e.yml dropped it in S345 for exactly this reason). If you add it back, or use it locally, the script exits 5 and says so — do not "fix" phpunit.xml in response; re-run without --testdox. Exit 5 is decided inside the run whose OWN glyphs prove it is a testdox run: any ↩ glyph that does not surplus the run's shortfall marks the run, and because the attribution uses the run's own Skipped: N rather than the glyph count, a SINGLE glyph is enough to carry the whole shortfall to exit 5 — the glyph-less suite skip (a testSuiteSkipped event produces no glyph) is accounted for exactly this way. Only a SURPLUS — more glyphs than the run's shortfall, which no real testdox run can produce because PHPUnit counts every glyph it prints in the same run's Skipped: N — attributes nothing to testdox: both causes are then named and phpunit.xml is not exonerated. A surplus can only come from other output sharing the log, which gh run view --log makes routine. Stray glyphs are attributed to NO run only when they fall outside every run's segment — before any PHPUnit banner, or after a run's terminating summary line, since the segment is flushed and closed at that line — so those can never reach exit 5 whatever their count. A stray glyph that lands INSIDE a run's segment is attributed to that run and can carry it to exit 5, because it is arithmetically identical to the genuine mixed testdox shape above. Exit 5 is also taken for a run that ends No tests executed! with nothing named: a whole-suite skip under --testdox prints exactly that (the suite skip is invisible), so a quietly-empty set would be a lie. The message says to verify the invocation, because a genuinely empty run (a typo'd --filter, an empty directory) prints a byte-identical shape and is refused the same way — see the KNOWN LIMITS note below.

⚠ The second exception is the assertion-escape-probe job. It runs PHPUnit from scripts/assertion-escape-audit.php, which captures the output into a PHP variable and only tests it for a marker — it never echoes it. So no log line and no name set is obtainable from that job, whatever phpunit.xml says. Nothing is wrong with its config; its output simply never leaves the process. Those are the only two exceptions: PHPUnit's --teamcity printer still emits the skipped-details list, and was checked.

Skipped test suites (a class-level #[Requires*], or markTestSkipped() in setUpBeforeClass()) are counted in the same Skipped: N but named under a different header, and a run in which every suite skipped prints No tests executed! with no Tests: line at all. The script parses that shape too and emits such an entry as SUITE:<name>.

Why names and not Skipped: N. The number drifts between runs on its own — this repo has legitimate environment-dependent skips, and this box reports ~259 where CI reports 3 — and a moved count cannot distinguish "a test started skipping" from "a conditionally-skipped test turned into a failure" from "a test disappeared". All three move it identically, and two of the three can leave it unmoved. comm over the name set separates them; the count cannot. scripts/skipped-test-names.sh writes only the sorted set to stdout (so comm/diff can eat it directly), puts its denominators on stderr, and fails loudly rather than printing an empty set — with one of the exit codes in the table above. Each code names the cause its own arithmetic supports, and never attributes more to a cause than that cause can carry — a wrong diagnosis would send the next reader to fix the wrong thing, and rounds 2 and 3 of the S345 review plus its test engineer each caught one doing exactly that before it shipped (the last was a clamp that trimmed a surplus of testdox glyphs down to the shortfall; it is removed rather than re-tuned, because a surplus cannot come from a real testdox run at all).

⚠ That is not a guarantee that the code is right for every input — the script's header carries a numbered KNOWN LIMITS block, re-derived for per-run evaluation, and this section is its summary. Two of the old input-wide limits are closed by the segmentation and are no longer true: a shortfall in one run can no longer be paid for by another run's surplus (the multi-run refusal above replaces the netting), and N stray glyphs beside a run that lost N names no longer read as one testdox run that skipped N (exit 5 needs the run's OWN glyphs). What remains, all measured on this version:

• A run that genuinely executed nothing is refused too. A typo'd --filter or an empty directory prints a byte-identical No tests executed! to the invisible suite-skip shape, so it exits 5 with no set written and a message that says to verify the invocation — the right refusal for a shape that could otherwise hand over a silently-empty set.
• The input is assumed to be CONCATENATED runs, as ./vendor/bin/phpunit 2>&1 and a single job's gh run view --log produce. gh run view --log strips its job<TAB>step<TAB>timestamp prefix but does not group the lines by job: when two jobs' PHPUnit runs are INTERLEAVED in one log (parallel jobs), the banner-delimited segmentation splits at the wrong boundaries and exits 2 naming run 1 about input that is complete — the right refusal, wrong cause. The documented recipe is safe when a workflow's PHPUnit invocations are sequential steps of ONE job; for parallel jobs, pipe each job's log separately (gh run view --log --job <job-id>).
• A data-set label containing a literal newline is emitted truncated at that newline: the entry spans two lines, the denominators still agree, and this is the one shape that escapes the cross-check. No data provider here produces one and the truncation is stable across runs, so comm is not corrupted by it — but the denominator argument does not cover it.
• If a future PHPUnit renames the list header itself (There was 1 skipped test:), the refusal is still loud and nothing is written, but it arrives as exit 4 blaming phpunit.xml rather than as exit 3 blaming the parser — the right refusal with the wrong cause.

The script's header carries all six limits (three closed by S352, three still open, plus the refusal side-effect of limit 2 — the genuinely-empty run shape, listed first above), numbered, each with the input that reaches it, and enumerates every exit path with its input class; that header is the canonical statement of this contract, and this section is its summary.

Keep the suite hermetic w.r.t. the environment. PHLIX_DOMAIN changes real behaviour (it is the OAuth callback-URL allowlist — see Environment variables), so every test that depends on it sets it in setUp() and restores the ambient value in tearDown(), and the "no allowlist" cases pass '' explicitly instead of relying on the env being unset. Running the whole suite with and without PHLIX_DOMAIN exported yields identical per-test assertion counts; if you add a test that reads an env var, restore it.

Code Standards

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

Both are CI gates (.github/workflows/coding-standards.yml). Psalm is configured by psalm.xml at errorLevel="5"; there is no psalm-baseline.xml and the workflow fails if one appears. --show-info=false matches what CI runs — without it Psalm additionally prints ~1400 informational suggestions that are not gated.

Psalm needs PHP >= 8.3.16. Psalm 6.x aborts at startup on anything older (Psalm requires a PHP version ">= 8.3.16"), which includes the 8.3.6 that some dev boxes ship. CI is unaffected — shivammathur/setup-php with php-version: '8.3' installs the newest 8.3 patch. If your local PHP is too old, run it in a container instead of upgrading the box:

The extension list is not optional and mirrors the extensions: list in the Psalm CI job: Psalm resolves classes and constants from the extensions that are actually loaded, so a bare php:8.3-cli reports 140 phantom errors (Swoole\Coroutine\Channel, Socket, AF_INET, ZipArchive, GdImage, FFI, …) that do not exist on a properly configured runner.

CLI

Administrative tasks are exposed through the bin/phlix command-line tool (built on webman/console / Symfony Console):

php bin/phlix migrate is the supported equivalent of php scripts/run-migrations.php — both delegate to the same Phlix\Common\Database\MigrationRunner service. Re-running is safe: applied files are recorded in a schema_migrations ledger and skipped while their checksum matches, and a file that is re-applied tolerates the replay (statements use IF NOT EXISTS, and duplicate-column/duplicate-key errors are downgraded to notes because MySQL 8 has no IF NOT EXISTS on ADD COLUMN/ADD INDEX). More commands are added in later steps.

Exit codes (S159). Both commands exit 0 when every statement applied or failed only with an idempotent "already applied" error, and 1 when at least one genuine, non-idempotent statement error was recorded. A failing run does not stop at the first error — later files are still attempted — but the failing file is deliberately left out of the ledger so the next run retries it. Consequences worth knowing:

• scripts/install.sh runs under set -euo pipefail, so a failed migration aborts the install/update before the service is restarted.
• docker/docker-entrypoint.sh prints a loud PHLIX-MIGRATION-FAILURE banner to stderr and, by default, still starts the container (a crash-looping media server is worse than a degraded one). Set PHLIX_MIGRATIONS_STRICT=1 to make the container refuse to start instead. It also refuses to start when migrations could not run at all (no database host configured, or scripts/run-migrations.php missing).
• PHLIX_MIGRATIONS_DIR overrides the directory that is scanned for *.sql (default migrations/). Honoured by both commands.

⚠ "Idempotent" is a closed list, not "anything a replay raises". The squelch is decided on the MySQL error number, never on the exception text — the driver prefixes the whole failing statement to its message, so matching a phrase like already exists used to grep the migration's own SQL and reclassify hard failures as successes. The set is exactly four: 1050 table exists, 1060 duplicate column, 1061 duplicate key name, 1091 can't drop / check that column-key exists. Each names an object that can only be the one the failing statement was creating — a table in this schema, or a column/index, which are table-local.

Everything else fails the run, including several shapes a re-run can legitimately produce — write the migration so they never fire:

1062 in particular is deliberate: it is also what ADD UNIQUE raises when the existing data violates the new constraint, which is the most valuable failure a migration can report. 1068 names no object, so a replay and a genuine "a different primary key is already there" are indistinguishable.

1826/3822 were considered for the idempotent set and rejected — do not add them. Foreign-key and CHECK-constraint names are unique per schema, not per table, so the object that already holds the name can belong to a completely different table, and the statement that failed can be a CREATE TABLE that consequently created nothing. Squelching them let such a file exit 0 and enter schema_migrations, so it was never retried — worse than no squelch at all.

Exit codes: library:scan (S347). php bin/phlix library:scan <libraryId> (with or without --rescan) returns one of:

The same table is printed by php bin/phlix library:scan --help. 3 (not 2) is the "completed but lost files" code because 2 is Symfony's reserved invalid-input code — a wrapper must be able to tell a scan that never ran from one that lost files.

Admin SPA (admin-ui)

The admin console is a React + TypeScript + Vite single-page app. Its source lives in admin-ui/; the production build is emitted into public/assets/admin/ and committed to the repo, so the running Workerman server has no Node build dependency at runtime (it just serves the static shell + bundle). admin-ui/node_modules/ is gitignored.

The SPA mounts at /admin and /admin/*, served by AdminAppController (returns the built index.html shell; 503 if the bundle is missing) and gated by the existing AdminMiddleware — a non-admin (401/403) is redirected (302) to /login. Its typed ApiClient reuses the same JWT mechanism as public/assets/js/api-client.js (access_token/refresh_token in localStorage, Bearer header, single retry on 401 via POST /auth/refresh).

When you change anything under admin-ui/src/, re-run npm run build and commit the refreshed public/assets/admin/ bundle along with your source changes.

CI runs the SPA build + Vitest suite on any change under admin-ui/ via the Admin UI GitHub Actions workflow (.github/workflows/admin-ui.yml): npm ci → npm run build → npm run test on push/PR to master/main/develop (path-filtered, so PHP-only changes don't trigger it).

The first feature page on top of the scaffold is the Libraries page at /admin/libraries (step 1.1c): list / add / edit / delete libraries, a PathPicker driving the 0.6 GET /api/v1/admin/fs/browse endpoint, per-row Scan / Rescan buttons that hit the async 1.1b scan API (POST /api/v1/libraries/{id}/scan|rescan → 202 {job_id, status: "queued"}), live coarse lifecycle status by polling GET .../scan-status every 2 s (polling stops on completed / failed), and a per-library scan-history modal. No backend changes — the page consumes only contracts already shipped by 0.6 and 1.1b.

The Settings page at /admin/settings (step 1.3) renders all 15 server-setting keys across 8 tabbed groups (Transcoding, Metadata, Markers, Subtitles, Discovery, Trickplay, Newsletter, Port Forward). It consumes the 0.5 GET/PUT /api/v1/admin/settings contract — no new endpoints were added. Bool keys render as toggle switches; numeric keys render as number inputs with min/max constraints; tmdb.api_key renders as a password field with Show/Hide toggle. Overridden keys (DB-persisted vs. config-file default) display a "custom" badge. A sticky Save button fires PUT /api/v1/admin/settings; dirty-state gating keeps the button disabled when no fields have changed.

The Webhooks page at /admin/webhooks (step 1.4a) provides full CRUD for webhook subscriptions plus a per-webhook test trigger. It consumes the five endpoint contract in WebhookAdminController (GET list, POST create, PUT update, DELETE remove, POST test). The PUT /api/v1/admin/webhooks/{id} route, plus the backing WebhookDispatcher::update() and WebhookAdminController::update() PHP methods, were added in this step to support edit-in-place (the controller already had index/create/delete/test before 1.4a). The event multi-select shows 7 subscribable events grouped into 5 categories (Playback, Library, Downloads, Recordings, Alerts); webhook.test is internal-only. Secret is write-only — GET never returns it; the edit form shows an empty field with "(unchanged)" placeholder and omits secret from the PUT payload when blank, so the server retains the stored value. Coverage: 97.29% on webhooks.ts, 89.74% on WebhooksPage.tsx.

Full operator + contributor docs live in the phlix-docs site (docs/admin/integrations.md, docs/admin/server-settings.md, and docs/dev/admin-spa.md).

Git Workflow

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

Contributing

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

License

LICENSE for the full text.

MPL-2.0 is per-file weak copyleft. In short:

• You can use Phlix Server in a larger project, including a commercial or closed-source one.
• If you modify a file that is part of Phlix Server, you must make that file's source available under the MPL-2.0.
• New files you add alongside it can be licensed however you like.

"Phlix" is a trademark — see TRADEMARK.md for what that does and doesn't restrict.

Third-party components

Phlix Server depends on two LGPL-3.0 libraries — Smarty (smarty/smarty) and Tukio (crell/tukio) — plus a number of MIT-licensed packages. MPL-2.0 lists the GPL family as Secondary Licenses (MPL-2.0 §1.12, §3.3), so those are compatible. If you redistribute Phlix Server, you must still meet each dependency's own terms; composer licenses lists them.

Support

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

For detailed development documentation, see DEVELOPER.md.