moroz1999/zx-files

Zx Spectrum file containers parsers

4.1.0 2026-08-21 20:04 UTC

Requires

• php: ^8.5

Requires (Dev)

• phpunit/phpunit: ^12.0

CC0-1.0

• php
• basic
• tap
• zx spectrum
• trd
• scl
• tzx

Published on Packagist.org on 2026-08-21 20:04 UTC

README

Reads ZX Spectrum container files and extracts the files stored inside them, together with their metadata. Requires PHP 8.5.

Disk images:

• TRD

• SCL

• DSK (+3DOS, CP/M file system)

• FDI, UDI (physical disk images — IS-DOS file system, including protected disks)

• OPD / OPU (Opus Discovery)

Tape images:

• TAP
• TZX

Archives:

• TAR (esxDOS distribution trees, with real directories)

Plus a decoder for tokenized ZX Spectrum BASIC listings.

Usage

use ZxFiles\Binary\Binary;
use ZxFiles\ZxSpectrum\TrDos\TrdParser;

$volume = (new TrdParser())->parse(Binary::fromFile('demo.trd'));

echo $volume->label, ' ', $volume->freeSectors, " free sectors\n";
foreach ($volume->files() as $file) {
    echo $file->fullName, ' ', $file->size, "\n";
    file_put_contents($file->fullName, $file->contents());
}

Tapes work the same way through TapParser or TzxParser. When the format is not known up front, let the library recognise it:

use ZxFiles\Detection\ContainerReader;

$detected = (new ContainerReader())->readFile('game.tzx');

echo $detected->describe(), "\n";      // ZX Spectrum, ZX ROM tape, TZX tape image
echo $detected->confidence->name, "\n"; // Certain

foreach ($detected->root()->files as $file) {
    echo $file->fullName, ' ', $file->size, "\n";
}

Containers are exposed as a file system — a root Directory with files, and subdirectories for the systems that have them. Track and sector layout stays inside the parser.

Russian names and text files convert to UTF-8 on request:

use ZxFiles\Text\Charset;
use ZxFiles\Text\TextDecoder;

$decoder = new TextDecoder();
echo $decoder->toUtf8($file->fullName, Charset::Cp866);   // цукен.tab
echo $decoder->toText($file->contents(), Charset::Cp866); // Создание RAM-диска…

BASIC loaders can be listed:

use ZxFiles\Basic\BasicProgramParser;

echo (new BasicProgramParser())->parse($file->contents())->toText();

Supported so far: ZX Spectrum with TR-DOS, +3DOS, IS-DOS, Opus DOS and ROM tapes. The namespace layout is <Platform>\<System>\, so SAM Coupé, +3DOS, IS-DOS, CP/M and Opus DOS fit alongside without disturbing what is there.

Runnable versions of both snippets are in example/.

Development

The toolchain runs in Docker, see docs/docker.md:

docker compose run --rm composer install
docker compose run --rm phpunit

Without Docker: composer install && composer test

Documentation lives in docs/, entry point AGENTS.md.